Guia de uso do Serviço de Mensagens

A API do Serviço de Mensagens é o equivalente Open Cloud do MessagingService do Engine, que permite comunicar-se entre os servidores e clientes do seu jogo. A API do Engine só permite que você escreva e atualize scripts manualmente no Studio para publicar mensagens, mas a API Open Cloud permite que você envie mensagens para servidores ativos a partir de ferramentas externas para automatizar e melhorar seus fluxos de trabalho operacionais.

Uso

Existem várias ferramentas úteis que você pode construir apoiando a comunicação inter-servidores com a API do Serviço de Mensagens, incluindo:

• Portais de Anúncios: Um portal na web pode ser útil para suportar o envio de anúncios a todos os usuários em diferentes servidores do seu jogo, como anunciar um evento futuro, uma atualização e o vencedor de uma competição. No portal, você pode editar uma mensagem e clicar em um botão que chama a API para enviar a mensagem para todos os usuários ou usuários selecionados.

• Sistema de Moderação: Um sistema de moderação pode ajudar a manter seu jogo seguro. Ao detectar um usuário com comportamento inadequado, você pode publicar uma mensagem para acionar o servidor do jogo para avisar ou banir o usuário específico. Você também pode usar data stores no sistema de moderação para adicionar contas de usuários a uma lista de bloqueio que impede que eles entrem novamente.

• Painel de LiveOps: Os painéis de LiveOps são ferramentas úteis para gerenciar eventos ao vivo, como uma festa de Halloween. No painel, você pode pré-codificar um evento, atualizar mensagens do evento, acionar o evento quando estiver pronto e recompensar usuários selecionados com itens especiais, como uma coroa virtual, sem atualizar nenhum código do jogo.

Limites

A API do Serviço de Mensagens segue os mesmos limites que o MessagingService do Engine. Os limites de taxa são compartilhados entre ambas as APIs, e o uso de ambas é contabilizado contra os mesmos limites.

Configurar um tópico para mensagens

Antes que você possa publicar uma mensagem nos servidores ativos do seu jogo, você deve configurar um tópico, que é um canal de mensagem personalizado acessível a partir de múltiplos servidores. Após definir um tópico, você assina usuários para esse tópico para receber suas mensagens.

Atualmente, você pode somente definir um tópico no Studio e usar a API Luau MessagingService:SubscribeAsync() para assinar usuários a ele. O seguinte exemplo de código assina qualquer usuário a um tópico quando ele entra no jogo:

Configurar e Assinar Usuários a um Tópico
local MessagingService = game:GetService("MessagingService")
local Players = game:GetService("Players")

local function onPlayerAdded(player)
	-- Defina e assine ao tópico
	local topic = "SeuTópico"
	local connection = MessagingService:SubscribeAsync(topic, function(message)
		print(message.Data)
	end)

	player.AncestryChanged:Connect(function()
		-- Cancele a assinatura do tópico ao mudar a ancestralidade do jogador
		connection:Disconnect()
	end)
end

Players.PlayerAdded:Connect(onPlayerAdded)

Publicar mensagens em servidores ativos

Após configurar um tópico, publique uma mensagem nos servidores ativos do seu jogo:

1. Crie uma chave de API no Painel do Criador e copie-a em um lugar seguro. Certifique-se de realizar as seguintes configurações:

   1. Adicione messaging-service a Permissões de Acesso.
   2. Selecione um jogo e adicione a operação universe-messaging-service:publish.

2. Obtenha o ID do Universo para o seu jogo:

   1. Navegue até o Painel do Criador.

   2. Encontre o jogo ao qual você deseja publicar suas mensagens.

   3. Passe o mouse sobre a miniatura do jogo, clique no botão ⋯ e selecione Copiar ID do Universo.

      

3. Adicione a chave de API e o universo a uma requisição POST, conforme neste exemplo:

   Exemplo de Requisição para Publicar uma Mensagem
   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": "seu-tópico",
    "message": "Olá a todos!"
   }'

4. Envie a requisição HTTP para publicar a mensagem.

   Se sua requisição for bem-sucedida, ela retornará HTTP 200 com um corpo de resposta vazio.

Adicionar a API do Serviço de Mensagens a aplicativos OAuth 2.0

Você pode criar aplicações OAuth 2.0 que permitem que seus usuários publiquem mensagens em seus próprios servidores ativos.

Para usar a API do Serviço de Mensagens em sua aplicação e solicitar permissões de seus usuários, siga as seguintes etapas:

1. Ao registrar sua aplicação, sob Permissões, selecione o escopo universe-messaging-service:publish.

2. Ao implementar o fluxo de autorização, inclua universe-messaging-service:publish no parâmetro scope da URL de autorização que redireciona os usuários de volta para sua aplicação, como no seguinte exemplo:

   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. Solicite acesso ao universeId do jogo ao qual o usuário deseja publicar suas mensagens. Sua aplicação pode enviar uma requisição POST para o endpoint de recursos de token com o token de acesso, ID do cliente e segredo ou o code challenge, dependendo de sua implementação do fluxo de autorização, como parâmetros de requisição para obter uma lista de universeIds dos jogos que o usuário concedeu permissão:

   Exemplo de Requisição
   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>'

   Este endpoint retorna uma lista de universeIds como o seguinte exemplo de resposta:

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

4. Sua aplicação agora pode enviar mensagens para qualquer jogo que um usuário tenha concedido permissão. Ao enviar a requisição, inclua o token de acesso no cabeçalho de autorização e o universeId e tópico na URI da requisição no seguinte formato:

   Exemplo de Requisição
   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": "algum-tópico","message":"mensagem para publicar"}'

Usar com HTTPService

Esta API é um dos endpoints Open Cloud suportados pelo HttpService. Você pode usá-la para publicar mensagens entre diferentes jogos de dentro de um jogo.