Panduan penggunaan Messaging

API Layanan Pesan adalah setara Open Cloud dari MessagingService Engine, yang memungkinkan Anda berkomunikasi di antara server dan klien game Anda. API Engine hanya memungkinkan Anda untuk menulis dan memperbarui skrip secara manual di Studio untuk menerbitkan pesan, tetapi API Open Cloud memungkinkan Anda mengirim pesan ke server yang aktif dari alat eksternal untuk mengotomatiskan dan meningkatkan alur kerja operasi Anda.

Penggunaan

Ada beberapa alat bermanfaat yang dapat Anda bangun dengan mendukung komunikasi lintas server menggunakan API Layanan Pesan, termasuk:

• Portal Pengumuman: Portal web dapat membantu mendukung pengiriman pengumuman kepada semua pengguna di seluruh server dalam game Anda, seperti mengumumkan acara yang akan datang, pembaruan, dan pemenang kompetisi. Di portal, Anda dapat mengedit pesan dan mengklik tombol yang memanggil API untuk mengirimkan pesan kepada semua pengguna atau pengguna yang dipilih.

• Sistem Moderasi: Sistem moderasi dapat membantu menjaga game Anda tetap aman dan terjamin. Ketika mendeteksi pengguna dengan perilaku yang tidak pantas, Anda dapat menerbitkan pesan untuk memicu server game memberikan peringatan atau melarang pengguna tertentu. Anda juga dapat menggunakan data stores dalam sistem moderasi untuk menambahkan akun pengguna ke daftar blokir yang mencegah mereka untuk bergabung kembali.

• Dasbor LiveOps: Dasbor LiveOps adalah alat berguna untuk mengelola acara langsung, seperti pesta Halloween. Di dasbor, Anda dapat pra-kode sebuah acara, memperbarui pesan acara, memicu acara saat sudah siap, dan memberi penghargaan kepada pengguna yang dipilih dengan barang-barang khusus seperti mahkota virtual tanpa memperbarui kode game.

Batasan

API Layanan Pesan mengikuti batasan yang sama seperti MessagingService Engine. Batasan laju dibagi di antara kedua API, dan penggunaan dari kedua API dihitung terhadap batasan yang sama.

Siapkan topik untuk mengirim pesan

Sebelum Anda dapat menerbitkan pesan ke server aktif game Anda, Anda harus menyiapkan sebuah topik, yaitu saluran pesan yang dapat disesuaikan dan dapat diakses dari beberapa server. Setelah mendefinisikan sebuah topik, Anda harus melanggan pengguna ke topik tersebut untuk menerima pesan masuk Anda.

Saat ini, Anda hanya dapat mendefinisikan sebuah topik di Studio dan menggunakan API Luau MessagingService:SubscribeAsync() untuk melanggan pengguna. Contoh kode berikut melanggani setiap pengguna ke topik saat mereka bergabung dalam game:

Siapkan dan Melanggan Pengguna ke Topik
local MessagingService = game:GetService("MessagingService")
local Players = game:GetService("Players")

local function onPlayerAdded(player)
	-- Definisikan dan langgani ke topik
	local topic = "TopikAnda"
	local connection = MessagingService:SubscribeAsync(topic, function(message)
		print(message.Data)
	end)

	player.AncestryChanged:Connect(function()
		-- Berhenti melanggan dari topik saat perubahan keturunan pemain
		connection:Disconnect()
	end)
end

Players.PlayerAdded:Connect(onPlayerAdded)

Terbitkan pesan ke server yang aktif

Setelah menyiapkan sebuah topik, terbitkan pesan ke server aktif game Anda:

1. Buat kunci API di Dasbor Creator dan salin di tempat yang aman. Pastikan Anda melakukan pengaturan berikut:

   1. Tambahkan messaging-service ke Izin Akses.
   2. Pilih sebuah game, dan tambahkan operasi universe-messaging-service:publish.

2. Dapatkan ID Universe untuk game Anda:

   1. Arahkan ke Dasbor Creator.

   2. Temukan game yang ingin Anda kirimkan pesannya.

   3. Arahkan kursor ke thumbnail game, klik tombol ⋯ dan pilih Salin ID Universe.

      

3. Tambahkan kunci API dan universe ke permintaan POST, seperti contoh berikut:

   Contoh Permintaan untuk Menerbitkan Pesan
   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": "topik-anda",
    "message": "Halo, semuanya!"
   }'

4. Kirim permintaan HTTP untuk menerbitkan pesan.

   Jika permintaan Anda berhasil, itu akan mengembalikan HTTP 200 dengan body respon yang kosong.

Tambahkan API Layanan Pesan ke aplikasi OAuth 2.0

Anda dapat membuat aplikasi OAuth 2.0 yang memungkinkan pengguna Anda menerbitkan pesan ke server aktif mereka sendiri.

Untuk menggunakan API Layanan Pesan untuk aplikasi Anda dan meminta izin dari pengguna Anda, lakukan pengaturan berikut:

1. Saat mendaftarkan aplikasi Anda, di bawah Izin, pilih ruang lingkup universe-messaging-service:publish.

2. Saat mengimplementasikan alur otorisasi, sertakan universe-messaging-service:publish dalam parameter scope dari URL otorisasi yang mengalihkan pengguna kembali ke aplikasi Anda, seperti contoh berikut:

   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. Minta akses ke universeId dari game yang ingin pengguna menerbitkan pesan mereka. Aplikasi Anda dapat mengirim permintaan POST ke endpoint sumber daya token dengan token akses, ID klien dan rahasia, atau code challenge, tergantung pada implementasi alur otorisasi Anda, sebagai parameter permintaan untuk mendapatkan daftar universeIds dari game yang pengguna berikan izin:

   Contoh Permintaan
   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 ini mengembalikan daftar universeIds seperti contoh respon berikut:

   Contoh Respon
   {
     "resource_infos": [
       {
         "owner": {
           "id": "1516563360",
           "type": "User"
         },
         "resources": {
           "universe": {
             "ids": ["3828411582"]
           }
         }
       }
     ]
   }

4. Aplikasi Anda kini dapat mengirim pesan ke game mana pun yang diberikan izin oleh pengguna. Saat mengirim permintaan, sertakan token akses di header otorisasi dan universeId serta topik di URI permintaan dengan format berikut:

   Contoh Permintaan
   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": "topik-some","message":"pesan untuk diterbitkan"}'

Gunakan dengan HTTPService

API ini adalah salah satu dari endpoint Open Cloud yang didukung oleh HttpService. Anda dapat menggunakannya untuk menerbitkan pesan di seluruh game dari dalam sebuah game.