Solicitações HTTP em jogo

*Este conteúdo é traduzido por IA (Beta) e pode conter erros. Para ver a página em inglês, clique aqui.

Você pode usar HttpService para enviar solicitações HTTP genéricas para serviços da web de terceiros em casos de uso como análise, armazenamento de dados ou registro de erros. HttpService também suporta certos endpoints do Open Cloud.

Habilitar solicitações HTTP

Os métodos HttpService:GetAsync(), HttpService:PostAsync() e HttpService:RequestAsync() não estão habilitados por padrão. Para enviar solicitações, você deve Permitir Solicitações HTTP nas Configurações da Experiência do seu jogo.

Uso em plugins

Você pode usar HttpService em plugins do Studio para verificar atualizações, baixar conteúdo ou outras lógicas de negócios. Na primeira vez que um plugin tentar usar o serviço, o usuário poderá ser solicitado a dar permissão ao plugin para se comunicar com o determinado endereço da web. Os usuários podem aceitar, negar e revogar essas permissões a qualquer momento através da janela Gerenciamento de Plugins.

Os plugins também podem se comunicar com outros softwares em execução no mesmo computador através dos hosts localhost e 127.0.0.1. Ao executar programas compatíveis com tais plugins, você pode estender a funcionalidade do seu plugin além das capacidades normais do Studio, como interagir com o sistema de arquivos do seu computador. Cuidado, pois esses softwares devem ser distribuídos separadamente do próprio plugin e podem representar riscos de segurança.

Uso com Open Cloud

Atualmente, HttpService pode chamar um subconjunto dos endpoints do Open Cloud. Você pode chamar esses endpoints da mesma forma que chamaria qualquer outro endpoint via HttpService. A única diferença é que você deve incluir uma chave de API do Open Cloud na solicitação:

Crie uma chave de API do Open Cloud.
Salve a chave de API em seu armazenamento de segredos.
Faça a solicitação.

O seguinte exemplo de código demonstra como atualizar a associação de grupo de um usuário a partir de dentro de um jogo:


local HttpService = game:GetService("HttpService")

local groupId = "your_group_id"
local membershipId = "your_membership_id"
local roleId = "your_role_id"

local function request()
	local response = HttpService:RequestAsync({
		Url = `https://apis.roblox.com/cloud/v2/groups/{groupId}/memberships/{membershipId}`,
		Method = "PATCH",
		Headers = {
			["Content-Type"] = "application/json", -- Ao enviar JSON, defina isso!
			["x-api-key"] = HttpService:GetSecret("APIKey"), -- Definido no Creator Hub
		},
		Body = HttpService:JSONEncode({ role = `groups/{groupId}/roles/{roleId}` }),
	})

	if response.Success then
		print("A resposta foi bem-sucedida:", response.StatusCode, response.StatusMessage)
	else
		print("A resposta retornou um erro:", response.StatusCode, response.StatusMessage)
	end
	print("Corpo da resposta:\n", response.Body)
	print("Cabeçalhos da resposta:\n", HttpService:JSONEncode(response.Headers))
end

-- Envolva a função em pcall() para segurança
local success, errorMessage = pcall(request)
if not success then
	print("A solicitação HTTP falhou ao ser enviada:", errorMessage)
end

Endpoints do Open Cloud suportados

Os seguintes endpoints são suportados. Devido a limitações atuais no HttpService, a string .. não é permitida nos parâmetros de caminho da URL para domínios Roblox. Isso significa, por exemplo, que armazenamento de dados e entradas contendo essa string estão atualmente inacessíveis a partir do HttpService.

Ativos

Banimentos e bloqueios

Configurações

Loja do Criador

Produtos para desenvolvedores

Game passes

Armazenamentos de dados e memória

Armazenamentos de dados:

Armazenamentos de memória:

Armazenamentos de dados ordenados:

Grupos

Inventários

ListInventoryItems

Execução do Luau

Notificações

CreateUserNotification

Locais

Universos

Usuários

Limitações

Apenas os cabeçalhos x-api-key e content-type são permitidos.
O cabeçalho x-api-key deve ser um Secret. Veja Armazenamentos de segredos.
A string ".." não é permitida nos parâmetros de caminho da URL.
Apenas o protocolo HTTPS é suportado.
Você não pode usar a porta 1194 ou qualquer porta abaixo de 1024, exceto 80 e 443. Se você tentar usar uma porta bloqueada, receberá um erro de 403 Forbidden ou ERR_ACCESS_DENIED.

Limites de taxa

Para cada servidor de jogo Roblox, há um limite de 2500 solicitações Open Cloud por minuto. Exceder isso pode fazer com que os métodos de envio de solicitações travem por cerca de 30 segundos. Seu pcall() também pode falhar com uma mensagem de Número de solicitações Open Cloud excedeu o limite.

Solicitações Open Cloud não consomem o mesmo limite total de 500 solicitações HTTP por minuto imposto a todas as outras solicitações.
Cada endpoint tem seu próprio limite por proprietário de chave de API (que pode ser um usuário ou um grupo) que é aplicado independentemente de onde as chamadas vêm (HttpService, a web, etc.).

Para informações detalhadas sobre limites de taxa do Open Cloud, limitação de taxa baseada em autenticação e melhores práticas, veja Limites de Taxa.

Melhores práticas

Para otimizar o uso do HttpService e evitar exceder os limites, aplique as seguintes melhores práticas:

Lide com erros de forma robusta. Solicitações da web podem falhar por muitos motivos. Use pcall() e tenha um plano para quando as solicitações falharem. Além disso, valide e sanitize rigorosamente todos os dados recebidos de APIs externas, garantindo dados corretos sempre que possível.
Use exponential backoff para ficar abaixo dos limites.

Se uma solicitação retornar um erro recuperável, em vez de tentar novamente imediatamente, espere dois segundos, depois quatro, oito, etc. entre as tentativas. Isso ajuda a limitar a congestão e melhora a chance de uma solicitação bem-sucedida, dando ao endpoint tempo para "esfriar".
Agregue e envie dados em lote.

Quando possível, é recomendado que seu servidor colete todos os dados necessários para enviar uma solicitação HTTP, em vez de múltiplas pequenas solicitações. Por exemplo, se você estiver enviando uma solicitação HTTP para cada jogador no seu servidor, verifique se a API tem um endpoint de bulk/batch e, se sim, colete as informações de todos os jogadores e envie tudo em uma solicitação.

Em alguns casos, pode ser necessário usar HttpService:RequestAsync() para incluir dados no corpo da solicitação.
Use endpoints HTTP/2. O HTTP/2 oferece benefícios significativos de desempenho através de recursos como compressão de cabeçalho e multiplexação de solicitações/respostas em uma única conexão. O HttpService usa automaticamente HTTP/2 quando disponível. Observe que a especificação HTTP/2 exige que todos os nomes de cabeçalho sejam enviados em letras minúsculas.

Observabilidade

O Painel de Observabilidade fornece insights e análises para monitorar e solucionar problemas de uso do seu HttpService. O painel apresenta dois gráficos principais: Contagem de Solicitações, que rastreia o volume de solicitações do HttpService do seu jogo, e Tempo de Resposta, que mede a latência para os endpoints responderem.

As dimensões disponíveis para filtragem e detalhamento são definidas da seguinte forma:

Tipo de Solicitação

GET
POST
PUT
PATCH
DELETE
Outro (para tipos de solicitação não especificados)

Status

Sucesso (códigos de status HTTP 1xx e 2xx)
Redirecionar (códigos de status HTTP 3xx)
400 (Solicitação Inválida)
401 (Não Autorizado)
403 (Proibido)
404 (Não Encontrado)
429 (Muitas Solicitações)
500 (Erro Interno do Servidor)
503 (Serviço Indisponível)
ExternalError (qualquer outro código de erro não especificado retornado pelo serviço externo)
InternalError (um problema retornado do HttpService dentro do Roblox)

O gráfico Tempo de Resposta não está correlacionado com os dados de status. Se você selecionar "Status" como detalhamento ou filtro, este gráfico não exibirá dados.

Considerações adicionais

As solicitações devem fornecer uma forma segura de autenticação, como uma chave secreta pré-compartilhada, para que agentes mal-intencionados não possam se passar por um dos seus servidores Roblox.
Esteja ciente da capacidade geral e das políticas de limitação de taxa dos servidores da web para os quais as solicitações estão sendo enviadas.

Português (Brasil)