Przewodnik po użyciu wiadomości

API Messaging Service jest odpowiednikiem MessagingService w Open Cloud, który pozwala na komunikację pomiędzy serwerami i klientami w twojej grze. API silnika pozwala jedynie na ręczne pisanie i aktualizację skryptów w Studio w celu publikowania wiadomości, ale API Open Cloud umożliwia wysyłanie wiadomości do aktywnych serwerów z zewnętrznych narzędzi, co automatyzuje i poprawia przepływy pracy operacyjne.

Użycie

Istnieje wiele przydatnych narzędzi, które możesz stworzyć, wspierając komunikację między serwerami za pomocą API Messaging Service, w tym:

• Portale Ogłoszeniowe: Portal internetowy może być przydatny do wspierania wysyłania ogłoszeń do wszystkich użytkowników na serwerach w twojej grze, takich jak ogłaszanie nadchodzącego wydarzenia, aktualizacji i zwycięzcy konkursu. Na portalu możesz edytować wiadomość i kliknąć przycisk, który wywołuje API, aby wysłać wiadomość do wszystkich użytkowników lub wybranych użytkowników.

• System Moderacji: System moderacji może pomóc w zapewnieniu bezpieczeństwa w twojej grze. Gdy wykryjesz użytkownika o niewłaściwym zachowaniu, możesz opublikować wiadomość, aby wywołać statystykę serwera gry w celu ostrzeżenia lub zbanowania konkretnego użytkownika. Możesz również użyć sklepów z danymi w systemie moderacji do dodania kont użytkowników do czarnej listy, co uniemożliwia im ponowne dołączenie.

• Dashboard LiveOps: Dashboardy LiveOps to przydatne narzędzia do zarządzania wydarzeniami na żywo, takimi jak impreza Halloweenowa. Na dashboardzie możesz wcześniej zaprogramować wydarzenie, aktualizować wiadomości o wydarzeniu, wywołać wydarzenie, gdy będzie gotowe, oraz nagradzać wybranych użytkowników specjalnymi przedmiotami, takimi jak wirtualna korona, bez aktualizacji kodu gry.

Limity

API Messaging Service podlega tym samym limitom, co MessagingService w silniku. Limity są dzielone pomiędzy oba API, a użycie z obu API jest liczone na te same limity.

Skonfiguruj temat do wiadomości

Zanim opublikujesz wiadomość do aktywnych serwerów swojej gry, musisz skonfigurować temat, który jest dostosowanym kanałem wiadomości dostępnym z wielu serwerów. Po zdefiniowaniu tematu subskrybujesz użytkowników do tematu, aby otrzymywać nadchodzące wiadomości.

Obecnie możesz jedynie zdefiniować temat w Studio i użyć API Luau MessagingService:SubscribeAsync() do subskrybowania użytkowników. Następujący przykładowy kod subskrybuje każdego użytkownika do tematu, gdy dołącza do gry:

local MessagingService = game:GetService("MessagingService")
local Players = game:GetService("Players")

local function onPlayerAdded(player)
	-- Zdefiniuj i subskrybuj temat
	local topic = "TwójTemat"
	local connection = MessagingService:SubscribeAsync(topic, function(message)
		print(message.Data)
	end)

	player.AncestryChanged:Connect(function()
		-- Zrezygnuj z subskrypcji z tematu po zmianie pochodzenia gracza
		connection:Disconnect()
	end)
end

Players.PlayerAdded:Connect(onPlayerAdded)

Publikuj wiadomości do aktywnych serwerów

Po skonfigurowaniu tematu, opublikuj wiadomość do aktywnych serwerów swojej gry:

1. Utwórz klucz API na Creator Dashboard i skopiuj go w bezpieczne miejsce. Upewnij się, że wykonujesz następujące ustawienia:

   1. Dodaj messaging-service do Uprawnień Dostępu.
   2. Wybierz grę i dodaj operację universe-messaging-service:publish.

2. Uzyskaj ID Uniwersum dla swojej gry:

   1. Przejdź do Creator Dashboard.

   2. Znajdź grę, do której chcesz publikować wiadomości.

   3. Najedź na miniaturkę gry, kliknij przycisk ⋯ i wybierz Kopiuj ID Uniwersum.

      

3. Dodaj klucz API oraz uniwersum do żądania POST, jak w tym przykładzie:

   Przykładowe żądanie publikacji wiadomości

   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": "twój-temat",
    "message": "Cześć, wszyscy!"
   }'

4. Wyślij żądanie HTTP, aby opublikować wiadomość.

   Jeśli twoje żądanie się powiedzie, zwraca HTTP 200 z pustym ciałem odpowiedzi.

Dodaj API Messaging Service do aplikacji OAuth 2.0

Możesz tworzyć aplikacje OAuth 2.0, które pozwalają twoim użytkownikom publikować wiadomości na ich własnych aktywnych serwerach.

Aby użyć API Messaging Service w swojej aplikacji i poprosić użytkowników o uprawnienia, wykonaj następujące ustawienia:

1. Podczas rejestracji swojej aplikacji, w sekcji Uprawnienia, wybierz zakres universe-messaging-service:publish.

2. Podczas wdrażania przepływu autoryzacji, zawrzyj universe-messaging-service:publish w parametrze scope adresu URL autoryzacji, który przekierowuje użytkowników z powrotem do twojej aplikacji, jak w poniższym przykładzie:

   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. Poproś o dostęp do universeId gry, do której użytkownik chce publikować swoje wiadomości. Twoja aplikacja może wysłać żądanie POST do punktu końcowego zasobów tokenów z tokenem dostępu, identyfikatorem klienta i sekretem lub code challenge, w zależności od twojego wdrożenia przepływu autoryzacji, jako parametrami żądania, aby uzyskać listę universeIds gier, do których użytkownik przyznał uprawnienia:

   Przykładowe żądanie

   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>'

   Ten punkt końcowy zwraca listę universeIds, jak w poniższym przykładzie odpowiedzi:

   Przykładowa odpowiedź

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

4. Twoja aplikacja może teraz wysyłać wiadomości do każdej gry, do której użytkownik przyznał uprawnienia. Podczas wysyłania żądania dołącz token dostępu w nagłówku autoryzacji oraz universeId i temat w URI żądania w następującym formacie:

   Przykładowe żądanie

   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": "jakis-temat","message":"wiadomość do publikacji"}'

Użyj z HTTPService

To API jest jednym z punktów końcowych Open Cloud wspieranych przez HttpService. Możesz użyć go do publikowania wiadomości pomiędzy różnymi grami z jednego gry.