Hướng dẫn sử dụng Messaging

API Dịch vụ Nhắn tin là tương đương với MessagingService của Engine, cho phép bạn giao tiếp giữa các máy chủ và khách hàng trong trò chơi của bạn. API Engine chỉ cho phép bạn viết và cập nhật các kịch bản bằng tay trong Studio để phát đi các thông điệp, nhưng API Đám mây Mở cho phép bạn gửi thông điệp đến các máy chủ đang hoạt động từ các công cụ bên ngoài để tự động hóa và cải thiện quy trình làm việc của bạn.

Sử dụng

Có nhiều công cụ hữu ích mà bạn có thể xây dựng bằng cách hỗ trợ giao tiếp giữa các máy chủ với API Dịch vụ Nhắn tin, bao gồm:

• Cổng Thông báo: Một cổng web có thể hữu ích để hỗ trợ gửi thông báo đến tất cả người dùng trên các máy chủ trong trò chơi của bạn, chẳng hạn như thông báo về một sự kiện sắp tới, một bản cập nhật, hoặc người chiến thắng trong một cuộc thi. Tại cổng, bạn có thể chỉnh sửa một thông điệp và nhấn nút gọi API để gửi thông điệp đến tất cả người dùng hoặc người dùng đã chọn.

• Hệ thống Điều chỉnh: Một hệ thống điều chỉnh có thể giúp giữ cho trò chơi của bạn an toàn và bảo mật. Khi phát hiện một người dùng có hành vi không phù hợp, bạn có thể phát đi một thông điệp để kích hoạt máy chủ trò chơi cảnh báo hoặc cấm người dùng cụ thể đó. Bạn cũng có thể sử dụng cửa hàng dữ liệu trong hệ thống điều chỉnh để thêm tài khoản người dùng vào danh sách chặn, ngăn họ tham gia lại.

• Bảng điều khiển LiveOps: Các bảng điều khiển LiveOps là các công cụ hữu ích để quản lý các sự kiện đang diễn ra, như một bữa tiệc Halloween. Trên bảng điều khiển, bạn có thể lập trình trước một sự kiện, cập nhật thông điệp sự kiện, kích hoạt sự kiện khi nó sẵn sàng, và thưởng cho những người dùng được chọn với các vật phẩm đặc biệt như vương miện ảo mà không cần cập nhật mã của trò chơi.

Giới hạn

API Dịch vụ Nhắn tin tuân theo các giới hạn giống như MessagingService của Engine. Các giới hạn tần suất được chia sẻ giữa cả hai API, và việc sử dụng từ cả hai API đều được tính vào cùng một giới hạn.

Thiết lập một chủ đề cho việc nhắn tin

Trước khi bạn có thể phát đi một thông điệp đến các máy chủ đang hoạt động của trò chơi, bạn phải thiết lập một chủ đề, là một kênh thông điệp tùy chỉnh có thể truy cập từ nhiều máy chủ. Sau khi định nghĩa một chủ đề, bạn đăng ký người dùng vào chủ đề để nhận thông điệp đến từ bạn.

Hiện tại, bạn chỉ có thể định nghĩa một chủ đề trong Studio và sử dụng API Luau MessagingService:SubscribeAsync() để đăng ký người dùng. Mẫu mã sau đây đăng ký bất kỳ người dùng nào vào một chủ đề khi họ tham gia trò chơi:

Thiết lập và Đăng ký Người dùng vào một Chủ đề
local MessagingService = game:GetService("MessagingService")
local Players = game:GetService("Players")

local function onPlayerAdded(player)
	-- Định nghĩa và đăng ký vào chủ đề
	local topic = "YourTopic"
	local connection = MessagingService:SubscribeAsync(topic, function(message)
		print(message.Data)
	end)

	player.AncestryChanged:Connect(function()
		-- Hủy đăng ký khỏi chủ đề khi thay đổi tổ tiên của người chơi
		connection:Disconnect()
	end)
end

Players.PlayerAdded:Connect(onPlayerAdded)

Phát đi thông điệp đến các máy chủ đang hoạt động

Sau khi thiết lập một chủ đề, phát đi một thông điệp đến các máy chủ đang hoạt động của trò chơi:

1. Tạo một API key trên Bảng điều khiển Người sáng tạo và sao chép nó vào nơi an toàn. Đảm bảo bạn thực hiện các cài đặt sau:

   1. Thêm messaging-service vào Quyền Truy cập.
   2. Chọn một trò chơi, và thêm thao tác universe-messaging-service:publish.

2. Lấy ID Vũ trụ cho trò chơi của bạn:

   1. Điều hướng đến Bảng điều khiển Người sáng tạo.

   2. Tìm trò chơi mà bạn muốn phát đi thông điệp của mình.

   3. Di chuột qua hình thu nhỏ của trò chơi, nhấp vào nút ⋯, và chọn Sao chép ID Vũ trụ.

      

3. Thêm API key và ID vũ trụ vào yêu cầu POST, như trong ví dụ này:

   Ví dụ Yêu cầu để Phát đi một Thông điệp
   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": "Xin chào mọi người!"
   }'

4. Gửi yêu cầu HTTP để phát đi thông điệp.

   Nếu yêu cầu của bạn thành công, nó sẽ trả về HTTP 200 với một phản hồi thân rỗng.

Thêm API Dịch vụ Nhắn tin vào ứng dụng OAuth 2.0

Bạn có thể tạo các ứng dụng OAuth 2.0 cho phép người dùng của bạn phát đi thông điệp đến các máy chủ đang hoạt động của họ.

Để sử dụng API Dịch vụ Nhắn tin cho ứng dụng của bạn và yêu cầu quyền từ người dùng của bạn, thực hiện các cài đặt sau:

1. Khi đăng ký ứng dụng của bạn, dưới Quyền, chọn phạm vi universe-messaging-service:publish.

2. Khi triển khai quy trình ủy quyền, bao gồm universe-messaging-service:publish trong tham số scope của URL ủy quyền chuyển hướng người dùng quay lại ứng dụng của bạn, như ví dụ sau:

   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. Yêu cầu quyền truy cập đến universeId của trò chơi mà người dùng muốn phát đi thông điệp của họ. Ứng dụng của bạn có thể gửi yêu cầu POST đến điểm cuối tài nguyên token với token truy cập, ID client và secret hoặc code challenge, tùy thuộc vào triển khai quy trình ủy quyền của bạn, như các tham số yêu cầu để lấy danh sách universeIds của các trò chơi mà người dùng đã cấp quyền:

   Ví dụ Yêu cầu
   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>'

   Điểm cuối này trả về một danh sách universeIds như phản hồi mẫu sau:

   Ví dụ Phản hồi
   {
     "resource_infos": [
       {
         "owner": {
           "id": "1516563360",
           "type": "User"
         },
         "resources": {
           "universe": {
             "ids": ["3828411582"]
           }
         }
       }
     ]
   }

4. Ứng dụng của bạn có thể gửi thông điệp đến bất kỳ trò chơi nào mà người dùng đã cấp quyền. Khi gửi yêu cầu, bao gồm token truy cập trong phần tiêu đề ủy quyền và universeId cũng như chủ đề trong URI yêu cầu theo định dạng sau:

   Ví dụ Yêu cầu
   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":"thông điệp để phát đi"}'

Sử dụng với HTTPService

API này là một trong những điểm cuối Đám mây Mở được hỗ trợ bởi HttpService. Bạn có thể sử dụng nó để phát đi thông điệp giữa các trò chơi khác nhau từ trong một trò chơi.