Guide d'utilisation de la messagerie

L'API du service de messagerie est l'équivalent Open Cloud de l'Engine MessagingService, qui vous permet de communiquer entre les serveurs et les clients de votre jeu. L'API de l'Engine ne permet d'écrire et de mettre à jour les scripts qu'en manuel dans Studio pour publier des messages, mais l'API Open Cloud vous permet d'envoyer des messages à des serveurs en direct depuis des outils externes pour automatiser et améliorer vos flux de travail.

Utilisation

Il existe plusieurs outils utiles que vous pouvez construire en supportant la communication inter-serveurs avec l'API du service de messagerie, notamment :

• Portails d'annonces : Un portail web peut être utile pour envoyer des annonces à tous les utilisateurs sur les serveurs de votre jeu, tels que l'annonce d'un événement à venir, d'une mise à jour ou du gagnant d'une compétition. Sur le portail, vous pouvez éditer un message et cliquer sur un bouton qui appelle l'API pour envoyer le message à tous les utilisateurs ou à des utilisateurs sélectionnés.

• Système de modération : Un système de modération peut aider à garder votre jeu sûr et sécurisé. Lors de la détection d'un utilisateur ayant un comportement inapproprié, vous pouvez publier un message pour déclencher le serveur de jeu afin de prévenir ou de bannir l'utilisateur spécifique. Vous pouvez également utiliser les magasins de données dans le système de modération pour ajouter des comptes utilisateurs à une liste de blocage qui les empêche de revenir.

• Tableau de bord LiveOps : Les tableaux de bord LiveOps sont des outils utiles pour gérer des événements en direct, comme une fête d'Halloween. Sur le tableau de bord, vous pouvez pré-coder un événement, mettre à jour les messages d'événement, déclencher l'événement quand il est prêt et récompenser des utilisateurs sélectionnés avec des objets spéciaux comme une couronne virtuelle sans mettre à jour le code du jeu.

Limites

L'API du service de messagerie suit les mêmes limites que l'Engine MessagingService. Les limites de taux sont partagées entre les deux APIs, et l'utilisation des deux APIs est comptée contre les mêmes limites.

Configurer un sujet pour la messagerie

Avant de pouvoir publier un message sur les serveurs en direct de votre jeu, vous devez configurer un sujet, qui est un canal de message personnalisé accessible depuis plusieurs serveurs. Après avoir défini un sujet, vous devez abonner les utilisateurs à ce sujet pour recevoir vos messages entrants.

Actuellement, vous ne pouvez définir un sujet que dans Studio et utiliser l'API Luau MessagingService:SubscribeAsync() pour y abonner les utilisateurs. L'exemple de code suivant abonne tout utilisateur à un sujet lorsqu'il rejoint le jeu :

Configurer et Abonner les Utilisateurs à un Sujet
local MessagingService = game:GetService("MessagingService")
local Players = game:GetService("Players")

local function onPlayerAdded(player)
	-- Définir et s'abonner au sujet
	local topic = "VotreSujet"
	local connection = MessagingService:SubscribeAsync(topic, function(message)
		print(message.Data)
	end)

	player.AncestryChanged:Connect(function()
		-- Se désabonner du sujet lors d'un changement d'ascendance du joueur
		connection:Disconnect()
	end)
end

Players.PlayerAdded:Connect(onPlayerAdded)

Publier des messages sur des serveurs en direct

Après avoir configuré un sujet, publiez un message sur les serveurs en direct de votre jeu :

1. Créez une clé API sur le Tableau de bord des créateurs et copiez-la dans un endroit sûr. Assurez-vous de réaliser les réglages suivants :

   1. Ajoutez messaging-service aux Permissions d'accès.
   2. Sélectionnez un jeu, et ajoutez l'opération universe-messaging-service:publish.

2. Obtenez l'ID de l'univers pour votre jeu :

   1. Accédez au Tableau de bord des créateurs.

   2. Trouvez le jeu auquel vous souhaitez publier vos messages.

   3. Survolez la vignette d'un jeu, cliquez sur le bouton ⋯ et sélectionnez Copier l'ID de l'univers.

      

3. Ajoutez la clé API et l'univers à une requête POST, comme dans cet exemple :

   Exécution d'une Requête pour Publier un Message
   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": "votre-sujet",
    "message": "Bonjour à tous !"
   }'

4. Envoyez la requête HTTP pour publier le message.

   Si votre requête réussit, elle renvoie HTTP 200 avec un corps de réponse vide.

Ajouter l'API du service de messagerie aux applications OAuth 2.0

Vous pouvez créer des applications OAuth 2.0 qui permettent à vos utilisateurs de publier des messages sur leurs propres serveurs en direct.

Pour utiliser l'API du service de messagerie pour votre application et demander des permissions à vos utilisateurs, réalisez les réglages suivants :

1. Lorsque vous enregistrez votre application, sous Permissions, sélectionnez la portée universe-messaging-service:publish.

2. Lorsque vous implémentez le flux d'autorisation, incluez universe-messaging-service:publish dans le paramètre scope de l'URL d'autorisation qui redirige les utilisateurs vers votre application, comme dans cet exemple :

   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. Demandez l'accès à l'universeId du jeu auquel l'utilisateur souhaite publier ses messages. Votre application peut envoyer une requête POST au point de terminaison des ressources de token avec le token d'accès, l'ID et le secret du client ou le code challenge, selon votre implémentation de votre flux d'autorisation, comme paramètres de requête pour obtenir une liste des universeIds des jeux auxquels l'utilisateur a accordé l'autorisation :

   Exécution d'une Requête
   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>'

   Ce point de terminaison renvoie une liste de universeIds comme l'exemple de réponse suivant :

   Exemple de Réponse
   {
     "resource_infos": [
       {
         "owner": {
           "id": "1516563360",
           "type": "User"
         },
         "resources": {
           "universe": {
             "ids": ["3828411582"]
           }
         }
       }
     ]
   }

4. Votre application peut maintenant envoyer des messages à n'importe quel jeu auquel un utilisateur a accordé l'autorisation. Lors de l'envoi de la requête, incluez le token d'accès dans l'en-tête d'autorisation et l'universeId et le sujet dans l'URI de la requête dans le format suivant :

   Exécution d'une Requête
   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":"message à publier"}'

Utiliser avec HTTPService

Cette API fait partie des points de terminaison Open Cloud pris en charge par HttpService. Vous pouvez l'utiliser pour publier des messages à travers différents jeux depuis un jeu.