Przewodnik po użyciu komunikacji

API Usługi Komunikacyjnej jest odpowiednikiem Open Cloud dla MessagingService z silnika, który pozwala na komunikację między serwerami i klientami twojego doświadczenia. API silnika pozwala jedynie na ręczne pisanie i aktualizowanie skryptów w Studio do publikowania wiadomości, ale API Open Cloud umożliwia przesyłanie wiadomości do serwerów na żywo z zewnętrznych narzędzi, aby zautomatyzować i poprawić przepływy pracy operacyjne.

Użycie

Istnieje kilka pomocnych narzędzi, które możesz stworzyć, wspierając komunikację między serwerami za pomocą API Usługi Komunikacyjnej, w tym:

• Portale ogłoszeniowe: Portal internetowy może być pomocny w wysyłaniu ogłoszeń do wszystkich użytkowników na różnych serwerach w twoim doświadczeniu, na przykład ogłaszając nadchodzące wydarzenie, aktualizację, oraz zwycięzcę 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 utrzymać bezpieczeństwo twojego doświadczenia. Po wykryciu użytkownika z niewłaściwym zachowaniem możesz opublikować wiadomość, aby wywołać serwer doświadczenia, który ostrzeże lub zbanować konkretnego użytkownika. Możesz również użyć magazynów danych w systemie moderacji, aby dodać konta użytkowników do czarnej listy, co uniemożliwi im ponowne dołączenie.

• Dashboard LiveOps: Pulpity LiveOps to przydatne narzędzia do zarządzania wydarzeniami na żywo, takimi jak przyjęcie z okazji Halloween. Na pulpicie możesz wstępnie zakodować wydarzenie, aktualizować wiadomości wydarzenia, uruchomić wydarzenie, gdy będzie gotowe, i nagradzać wybranych użytkowników specjalnymi przedmiotami, takimi jak wirtualna korona, bez aktualizowania jakiegokolwiek kodu w doświadczeniu.

Limity

API Usługi Komunikacyjnej podlega tym samym limitom, co silnik MessagingService. Limity przepustowości są wspólne dla obu API, a użycie obu API jest liczone według tych samych limitów.

Ustaw temat dla komunikacji

Zanim opublikujesz wiadomość na żywych serwerach twojego doświadczenia, musisz ustawić temat, który jest dostosowanym kanałem wiadomości dostępnym z wielu serwerów. Po zdefiniowaniu tematu, musisz zasubskrybować użytkowników do tego tematu, aby mogli odbierać twoje przychodzące wiadomości.

Obecnie możesz tylko zdefiniować temat w Studio i użyć API Luau MessagingService:SubscribeAsync(), aby zasubskrybować użytkowników. Poniższy przykład kodu subskrybuje każdego użytkownika do tematu po dołączeniu do doświadczenia:

Ustaw i Zasubskrybuj Użytkowników do Tematu
local MessagingService = game:GetService("MessagingService")
local Players = game:GetService("Players")

local function onPlayerAdded(player)
	-- Zdefiniuj i zasubskrybuj do tematu
	local topic = "YourTopic"
	local connection = MessagingService:SubscribeAsync(topic, function(message)
		print(message.Data)
	end)

	player.AncestryChanged:Connect(function()
		-- Anuluj subskrypcję do tematu po zmianie pochodzenia gracza
		connection:Disconnect()
	end)
end

Players.PlayerAdded:Connect(onPlayerAdded)

Publikuj wiadomości na żywych serwerach

Po ustawieniu tematu, opublikuj wiadomość na żywych serwerach twojego doświadczenia:

1. Stwórz klucz API na Dashboardzie Twórcy i skopiuj go w bezpieczne miejsce. Upewnij się, że wykonasz następujące ustawienia:

   1. Dodaj messaging-service do Uprawnień dostępu.
   2. Wybierz doświadczenie i dodaj operację universe-messaging-service:publish.

2. Uzyskaj ID Uniwersum dla twojego doświadczenia:

   1. Przejdź do Dashboardu Twórcy.

   2. Znajdź doświadczenie, do którego chcesz publikować swoje wiadomości.

   3. Najedź kursorem na miniaturę doświadczenia, kliknij przycisk ⋯, a następnie wybierz Kopiuj ID Uniwersum.

      

3. Dodaj klucz API i uniwersum do żądania POST, jak w poniższym 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": "your-topic",
    "message": "Witajcie, wszyscy!"
   }'

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

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

Dodaj API Usługi Komunikacyjnej do aplikacji OAuth 2.0

Możesz stworzyć aplikacje OAuth 2.0, które pozwolą twoim użytkownikom publikować wiadomości na swoich własnych serwerach na żywo.

Aby używać API Usługi Komunikacyjnej w swojej aplikacji i żądać uprawnień od swoich użytkowników, wykonaj następujące ustawienia:

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

2. Podczas wdrażania przepływu autoryzacji, dołącz universe-messaging-service:publish do parametru scope adresu URL autoryzacji, który przekierowuje użytkowników z powrotem do twojej aplikacji, tak 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. Żądaj dostępu do universeId doświadczenia, do którego użytkownik chce publikować swoje wiadomości. Twoja aplikacja może wysłać żądanie POST do punktu końcowego token resources z tokenem dostępu, identyfikatorem klienta oraz sekretem lub code challenge, w zależności od twojego wdrożenia przepływu autoryzacji, jako parametry żądania, aby uzyskać listę universeIds doświadczeń, 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, która wygląda jak poniższa przykładowa odpowiedź:

   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żdego doświadczenia, które 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": "some-topic","message":"wiadomość do publikacji"}'

Użyj z HTTPService

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