Guia de uso de mensageria

O Serviço de Mensageria API é o equivalente aberto da Engenharia MessagingService, que permite que você se comunique entre os servidores e clientes de sua experiência.A API do Motor só permite que você escreva e atualize scripts manualmente no Studio para publicar mensagens, mas a API da Nuvem Aberta permite que você envie mensagens para servidores ao vivo de ferramentas externas para automatizar e melhorar seus fluxos de trabalho de operações.

Uso

Existem várias ferramentas úteis que você pode construir ao suportar a comunicação entre servidores com a API (Interface de Programação para Aplicações)do Serviço de Mensageria, incluindo:

• Portais de anúncios : Um portal da web pode ser útil para apoiar o envio de anúncios a todos os usuários em vários servidores em sua experiência, como anunciar um evento próximo, 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 sua experiência segura e segura.Ao detectar um usuário com comportamento inapropriado, você pode publicar uma mensagem para ativar o servidor de experiência para avisar ou banir o usuário específico.Você também pode usar armazenamentos de dados no sistema de moderação para adicionar contas de usuário a uma lista de bloqueio que os impede de se juntar novamente.

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

Limitos

Configure um tópico para mensagens

Antes de poder publicar uma mensagem nos servidores ao vivo da sua experiência, você deve configurar um tópico , que é um canal de mensagens personalizado que pode ser acessado por vários servidores.Depois de definir um tópico, você inscreve usuários no tópico para receber suas mensagens recebidas.

Atualmente, você só pode definir um tópico no Studio e usar a API Luau MessagingService:SubscribeAsync() nele.O seguinte exemplo de código inscreve qualquer usuário em um tópico quando eles se juntam à experiência:

Set up and Subscribe Users to a Topic
local MessagingService = game:GetService("MessagingService")
local Players = game:GetService("Players")

local function onPlayerAdded(player)
	-- Defina e se inscreva no tópico
	local topic = "YourTopic"
	local connection = MessagingService:SubscribeAsync(topic, function(message)
		print(message.Data)
	end)

	player.AncestryChanged:Connect(function()
		-- Desinscreva-se do tópico após a mudança de ancestralidade do jogador
		connection:Disconnect()
	end)
end

Players.PlayerAdded:Connect(onPlayerAdded)

Publicar mensagens em servidores ao vivo

Depois de definir um tópico, publique uma mensagem nos servidores ativos da sua experiência:

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

   1. Adicione serviço de mensageria a Permissões de acesso .
   2. Selecione uma experiência e adicione a operação universal mensaging service:publicar .

2. Obtenha o ID do Universo para sua experiência:

   1. Navegue até o Painel do Criador.

   2. Encontre a experiência para a qual você deseja publicar suas mensagens.

   3. Passe o mouse sobre uma miniatura de experiência, clique no botão ⋯ e selecione Copiar ID do Universo .

      

3. Adicione a chave da API e o universo a um solicitar / pedirPOST de API, como neste exemplo:

   Exemplo de Solicitaçã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": "your-topic",
    "message": "Hello, everyone!"
   }'

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

   Se a solicitação for bem-sucedida, ela retorna HTTP 200 com um corpo de resposta vazio.

Adicione a API de Serviço de Mensageria ao OAuth 2.0 aplicativos

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 de Serviço de Mensageria para o seu aplicativo e solicitar permissões de seus usuários, execute as seguintes configurações:

1. Ao registrar seu aplicativo , sob Permissões , selecione o escopo universal-mensageria-de-serviço:publicar.

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

   https://authorize.roblox.com?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 da experiência que o usuário quer publicar suas mensagens.Sua aplicação pode enviar um pedido de recursos de token com o token de acesso, ID do cliente e secreto ou , dependendo de sua implementação do fluxo de autorização , como parâmetros de solicitação para obter uma lista de experiências que o usuário concedeu permissão para:

   Exemplo de Solicitaçã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 ponto de extremidade retorna uma lista de universeIds como a seguinte resposta de exemplo:

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

4. Sua aplicação agora pode enviar mensagens para qualquer experiência que um usuário concedeu permissão.Ao enviar a solicitar / pedir, inclua o token de acesso no cabeçalho de autorização e o universeId e o tópico na URI da solicitação no seguinte formato:

   Exemplo de Solicitaçã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": "some-topic","message":"message to publish"}'