Messaging-Nutzungsanleitung

Die Messaging Service API ist das Open Cloud Pendant zu der Engine MessagingService, mit dem du über die Server und Clients deines Spiels kommunizieren kannst. Die Engine API erlaubt es nur, Skripte manuell in Studio für die Veröffentlichung von Nachrichten zu schreiben und zu aktualisieren, aber die Open Cloud API ermöglicht es dir, Nachrichten von externen Tools an Live-Server zu senden, um deine Betriebsabläufe zu automatisieren und zu verbessern.

Nutzung

Es gibt mehrere nützliche Tools, die du entwickeln kannst, indem du die serverübergreifende Kommunikation mit der Messaging Service API unterstützt, darunter:

• Ankündigungsportale: Ein Webportal kann hilfreich sein, um Ankündigungen an alle Benutzer über die Server deines Spiels zu senden, wie z. B. die Bekanntgabe eines bevorstehenden Ereignisses, eines Updates und des Gewinners eines Wettbewerbs. Auf dem Portal kannst du eine Nachricht bearbeiten und eine Schaltfläche klicken, die die API aufruft, um die Nachricht für alle Benutzer oder ausgewählte Benutzer zu senden.

• Moderationssystem: Ein Moderationssystem kann helfen, dein Spiel sicher und geschützt zu halten. Wenn ein Benutzer mit unangemessenem Verhalten erkannt wird, kannst du eine Nachricht veröffentlichen, um den Spielserver dazu zu bringen, den entsprechenden Benutzer zu warnen oder zu sperren. Du kannst auch Datenbanken im Moderationssystem verwenden, um Benutzerkonten in eine Sperrliste aufzunehmen, die ihnen das Wiederbeitreten verhindert.

• LiveOps-Dashboard: LiveOps-Dashboards sind nützliche Werkzeuge zur Verwaltung von Live-Events, wie z. B. einer Halloween-Party. Auf dem Dashboard kannst du ein Ereignis vorab codieren, Ereignisnachrichten aktualisieren, das Ereignis auslösen, wenn es bereit ist, und ausgewählte Benutzer mit speziellen Gegenständen wie einer virtuellen Krone belohnen, ohne den Code des Spiels zu aktualisieren.

Grenzen

Die Messaging Service API folgt denselben Grenzen wie die Engine MessagingService. Die Ratenlimits werden auf beide APIs aufgeteilt, und die Nutzung beider APIs wird gegen dieselben Grenzen gezählt.

Ein Thema für das Messaging einrichten

Bevor du eine Nachricht an die Live-Server deines Spiels veröffentlichen kannst, musst du ein Thema einrichten, das einen benutzerdefinierten Nachrichtenkanal darstellt, der von mehreren Servern aus zugänglich ist. Nachdem du ein Thema definiert hast, abonnierst du Benutzer für das Thema, um deine eingehenden Nachrichten zu empfangen.

Derzeit kannst du ein Thema nur in Studio definieren und die Luau-API MessagingService:SubscribeAsync() verwenden, um Benutzer dafür zu abonnieren. Das folgende Codebeispiel abonniert jeden Benutzer für ein Thema, wenn sie dem Spiel beitreten:

Thema einrichten und Benutzer abonnieren
local MessagingService = game:GetService("MessagingService")
local Players = game:GetService("Players")

local function onPlayerAdded(player)
	-- Thema definieren und abonnieren
	local topic = "YourTopic"
	local connection = MessagingService:SubscribeAsync(topic, function(message)
		print(message.Data)
	end)

	player.AncestryChanged:Connect(function()
		-- Vom Thema abmelden, wenn sich die Ancestry des Spielers ändert
		connection:Disconnect()
	end)
end

Players.PlayerAdded:Connect(onPlayerAdded)

Nachrichten an Live-Server veröffentlichen

Nachdem du ein Thema eingerichtet hast, veröffentliche eine Nachricht auf den Live-Servern deines Spiels:

1. Erstelle einen API-Schlüssel im Creator Dashboard und kopiere ihn an einen sicheren Ort. Stelle sicher, dass du die folgenden Einstellungen vornimmst:

   1. Füge messaging-service zu Zugriffsberechtigungen hinzu.
   2. Wähle ein Spiel aus und füge die Operation universe-messaging-service:publish hinzu.

2. Erhalte die Universum-ID deines Spiels:

   1. Navigiere zum Creator Dashboard.

   2. Finde das Spiel, für das du deine Nachrichten veröffentlichen möchtest.

   3. Bewege den Mauszeiger über das Miniaturbild eines Spiels, klicke auf die Schaltfläche ⋯ und wähle Universum-ID kopieren.

      

3. Füge den API-Schlüssel und die Universum-ID zu einer POST-Anfrage hinzu, wie in diesem Beispiel:

   Beispielanfrage für die Veröffentlichung einer Nachricht
   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": "Hallo, zusammen!"
   }'

4. Sende die HTTP-Anfrage, um die Nachricht zu veröffentlichen.

   Wenn deine Anfrage erfolgreich ist, erhältst du HTTP 200 mit einem leeren Antwortkörper.

Füge die Messaging Service API zu OAuth 2.0-Apps hinzu

Du kannst OAuth 2.0-Anwendungen erstellen, die es deinen Benutzern ermöglichen, Nachrichten an ihre eigenen Live-Server zu veröffentlichen.

Um die Messaging Service API für deine Anwendung zu nutzen und Berechtigungen von deinen Benutzern anzufordern, führe die folgenden Einstellungen aus:

1. Wähle beim Registrieren deiner Anwendung unter Berechtigungen den Bereich universe-messaging-service:publish aus.

2. Beziehe beim Implementieren des Autorisierungsflusses universe-messaging-service:publish im scope-Parameter der Autorisierungs-URL, die die Benutzer zurück zu deiner Anwendung umleitet, wie in folgendem Beispiel:

   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. Fordere Zugriff auf die universeId des Spiels an, zu dem der Benutzer seine Nachrichten veröffentlichen möchte. Deine Anwendung kann eine POST-Anfrage an den Token-Ressourcen-Endpunkt mit dem Zugriffstoken, der Client-ID und dem Geheimnis oder der code challenge, abhängig von deiner Implementierung des Autorisierungsflusses, als Anfrageparameter senden, um eine Liste von universeIds der Spiele zu erhalten, denen der Benutzer die Erlaubnis erteilt hat:

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

   Dieser Endpunkt gibt eine Liste von universeIds zurück, wie in folgendem Beispiel für die Antwort:

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

4. Deine Anwendung kann jetzt Nachrichten an jedes Spiel senden, dem ein Benutzer die Erlaubnis erteilt hat. Bei der Anfrage musst du das Zugriffstoken im Autorisierungsheader und die universeId sowie das Thema im Anfrage-URI im folgenden Format einfügen:

   Beispielanfrage
   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":"Nachricht zu veröffentlichen"}'

Verwendung mit HTTPService

Diese API ist ein Teil der Open Cloud-Endpunkte, die unterstützt werden durch HttpService. Du kannst sie verwenden, um Nachrichten über verschiedene Spiele hinweg aus innerhalb eines Spiels zu veröffentlichen.