คู่มือการใช้งานการส่งข้อความ

บริการ Messaging Service API คือสิ่งที่เปรียบเทียบได้กับ MessagingService ของ Engine ซึ่งช่วยให้คุณสามารถสื่อสารข้ามเซิร์ฟเวอร์และลูกค้าในเกมของคุณได้ API ของ Engine อนุญาตให้คุณเขียนและปรับปรุงสคริปต์ด้วยตนเองใน Studio เพื่อเผยแพร่ข้อความ แต่ Open Cloud API ช่วยให้คุณสามารถส่งข้อความไปยังเซิร์ฟเวอร์ที่กำลังใช้งานจากเครื่องมือภายนอกเพื่อทำให้การดำเนินงานของคุณมีประสิทธิภาพและสะดวกยิ่งขึ้น

การใช้งาน

มีเครื่องมือที่มีประโยชน์หลายอย่างที่คุณสามารถสร้างได้โดยการสนับสนุนการสื่อสารข้ามเซิร์ฟเวอร์ด้วย Messaging Service API รวมถึง:

• พอร์ทัลประกาศ: พอร์ทัลเว็บสามารถช่วยสนับสนุนการส่งประกาศถึงผู้ใช้ทุกคนข้ามเซิร์ฟเวอร์ในเกมของคุณ เช่น การประกาศกิจกรรมที่จะมาถึง การอัปเดต และผู้ชนะการแข่งขัน ในพอร์ทัล คุณสามารถแก้ไขข้อความและคลิกปุ่มที่เรียกใช้ API เพื่อส่งข้อความให้กับผู้ใช้ทั้งหมดหรือผู้ใช้ที่เลือก

• ระบบการModeration: ระบบการModeration สามารถช่วยทำให้เกมของคุณปลอดภัย เมื่อมีการตรวจพบผู้ใช้ที่มีพฤติกรรมไม่เหมาะสม คุณสามารถเผยแพร่ข้อความเพื่อกระตุ้นเซิร์ฟเวอร์เกมให้เตือนหรือแบนผู้ใช้ที่เฉพาะเจาะจง คุณยังสามารถใช้ data stores ในระบบการModeration เพื่อเพิ่มบัญชีผู้ใช้ลงในบล็อกลิสต์ที่ป้องกันไม่ให้พวกเขากลับมาเข้าร่วม

• แดชบอร์ด LiveOps: แดชบอร์ด LiveOps เป็นเครื่องมือที่มีประโยชน์สำหรับจัดการเหตุการณ์สด เช่น งานปาร์ตี้ฮาโลวีน ในแดชบอร์ด คุณสามารถเขียนโค้ดเหตุการณ์ล่วงหน้า อัปเดตข้อความเหตุการณ์ เรียกใช้เหตุการณ์เมื่อพร้อม และให้รางวัลแก่ผู้ใช้ที่ได้รับเลือกด้วยไอเทมพิเศษ เช่น มงกุฎเสมือน โดยไม่ต้องอัปเดตโค้ดใด ๆ ของเกม

ข้อจำกัด

Messaging Service API มีข้อจำกัดเดียวกันกับ MessagingService ของ Engine ข้อจำกัดของอัตราการใช้งานจะแบ่งปันระหว่างทั้งสอง API และการใช้งานจากทั้งสอง API จะถูกนับเป็นข้อจำกัดเดียวกัน

ตั้งค่าหัวข้อสำหรับการส่งข้อความ

ก่อนที่คุณจะสามารถเผยแพร่ข้อความไปยังเซิร์ฟเวอร์เกมที่กำลังใช้งาน คุณต้องตั้งค่า หัวข้อ ซึ่งเป็นช่องทางข้อความที่กำหนดเองที่สามารถเข้าถึงได้จากหลายเซิร์ฟเวอร์ หลังจากกำหนดหัวข้อแล้ว คุณจะต้องสมัครสมาชิกผู้ใช้ไปยังหัวข้อเพื่อให้ได้รับข้อความที่เข้ามา

ขณะนี้คุณสามารถกำหนดหัวข้อได้เพียงใน Studio และใช้ API Luau MessagingService:SubscribeAsync() เพื่อสมัครสมาชิกผู้ใช้ สำหรับตัวอย่างโค้ดด้านล่างนี้จะสมัครสมาชิกผู้ใช้ทุกคนไปยังหัวข้อเมื่อพวกเขาเข้าร่วมเกม:

ตั้งค่าและสมัครสมาชิกผู้ใช้ไปยังหัวข้อ
local MessagingService = game:GetService("MessagingService")
local Players = game:GetService("Players")

local function onPlayerAdded(player)
	-- กำหนดและสมัครสมาชิกไปยังหัวข้อ
	local topic = "YourTopic"
	local connection = MessagingService:SubscribeAsync(topic, function(message)
		print(message.Data)
	end)

	player.AncestryChanged:Connect(function()
		-- เลิกสมัครสมาชิกจากหัวข้อเมื่อมีการเปลี่ยนแปลงสายการสืบเชื้อ
		connection:Disconnect()
	end)
end

Players.PlayerAdded:Connect(onPlayerAdded)

เผยแพร่ข้อความไปยังเซิร์ฟเวอร์ที่ใช้งานอยู่

หลังจาก ตั้งค่า หัวข้อแล้ว เผยแพร่ข้อความไปยังเซิร์ฟเวอร์ที่ใช้งานอยู่ของเกมของคุณ:

1. สร้าง API key บน Creator Dashboard และคัดลอกมันไว้ในที่ปลอดภัย ให้แน่ใจว่าคุณได้ตั้งค่าดังต่อไปนี้:

   1. เพิ่ม messaging-service ลงใน สิทธิ์ในการเข้าถึง.
   2. เลือกเกม และเพิ่มการทำงาน universe-messaging-service:publish.

2. รับ Universe ID สำหรับเกมของคุณ:

   1. ไปที่ Creator Dashboard.

   2. หาเกมที่คุณต้องการเผยแพร่ข้อความไปยัง

   3. เลื่อนเมาส์ไปที่รูปภาพของเกม คลิกที่ปุ่ม ⋯ และเลือก Copy Universe ID.

      

3. เพิ่ม API key และ universe ลงในคำขอ POST ดังในตัวอย่างนี้:

   ตัวอย่างคำขอสำหรับการเผยแพร่ข้อความ
   curl -L -X POST 'https://apis.roblox.com/cloud/v2/universes/{universe}:publishMessage' \
   -H 'x-api-key: {api-key}' \
   -H 'Content-Type: application/json' \
   --data '{
    "topic": "your-topic",
    "message": "สวัสดีทุกคน!"
   }'

4. ส่งคำขอ HTTP เพื่อเผยแพร่ข้อความ

   หากคำขอของคุณสำเร็จ จะคืนค่า HTTP 200 โดยไม่มีเนื้อหาตอบกลับ

เพิ่ม Messaging Service API ลงในแอป OAuth 2.0

คุณสามารถสร้าง แอป OAuth 2.0 ที่ช่วยให้ผู้ใช้ของคุณสามารถเผยแพร่ข้อความไปยังเซิร์ฟเวอร์ที่ใช้งานของตนเองได้

ในการใช้ Messaging Service API สำหรับแอปของคุณและขอสิทธิ์จากผู้ใช้ของคุณ ให้ตั้งค่าดังต่อไปนี้:

1. เมื่อ ลงทะเบียนแอปของคุณ ภายใต้ สิทธิ์, เลือกขอบเขต universe-messaging-service:publish.

2. เมื่อ ดำเนินการในกระบวนการอนุญาต ให้รวม universe-messaging-service:publish ไว้ในพารามิเตอร์ scope ของ URL อนุญาตที่เปลี่ยนเส้นทางผู้ใช้กลับมายังแอปของคุณ เช่น ในตัวอย่างด้านล่าง:

   https://apis.roblox.com/oauth/v1/authorize?client_id=816547628409595165403873012&redirect_uri=https://my-app.com/redirect&scope=openid+universe-messaging-service:publish&response_type=Code&prompts=login+consent&nonce=12345&state=6789

3. ขอเข้าถึง universeId ของเกมที่ผู้ใช้ต้องการเผยแพร่ข้อความไปยัง แอปของคุณสามารถส่งคำขอ POST ไปยัง endpoint แหล่งข้อมูล token ด้วย access token, client ID และ secret หรือ code challenge ขึ้นอยู่กับ การดำเนินการของกระบวนการอนุญาตของคุณ เพื่อขอรายการ universeIds ของเกมที่ผู้ใช้ได้ให้สิทธิ์:

   ตัวอย่างคำขอ
   curl --location --request POST 'https://apis.roblox.com/oauth/v1/token/resources' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'token=<access_token>' \
   --data-urlencode 'client_id=<client_id>' \
   --data-urlencode 'client_secret=<client_secret>'

   endpoint นี้จะคืนค่ารายการ universeIds ดังในตัวอย่างการตอบกลับด้านล่าง:

   ตัวอย่างการตอบกลับ
   {
     "resource_infos": [
       {
         "owner": {
           "id": "1516563360",
           "type": "User"
         },
         "resources": {
           "universe": {
             "ids": ["3828411582"]
           }
         }
       }
     ]
   }

4. แอปของคุณสามารถส่งข้อความไปยังเกมใด ๆ ที่ผู้ใช้ได้ให้สิทธิ์ ขณะส่งคำขอ ให้รวม access token ไว้ใน header การอนุญาตและ universeId และหัวข้อใน URI คำขอดังในรูปแบบนี้:

   ตัวอย่างคำขอ
   curl --location --request POST 'https://apis.roblox.com/cloud/v2/universes/{universe}:publishMessage' \
   --header 'Authorization: Bearer <access_token>' \
   --header 'Content-Type: application/json' \
   --data-raw '{"topic": "some-topic","message":"ข้อความที่จะเผยแพร่"}'

ใช้งานร่วมกับ HTTPService

API นี้เป็นหนึ่งใน endpoint Open Cloud ที่รองรับ โดย HttpService คุณสามารถใช้มันเพื่อเผยแพร่ข้อความข้ามเกมต่าง ๆ จากภายในเกม