Solicitações HTTP no 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 web de terceiros para 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 em Arquivo ⟩ Configurações da Experiência ⟩ Segurança no Studio.

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 tenta usar o serviço, o usuário pode ser solicitado a dar permissão ao plugin para se comunicar com o endereço web específico. 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 esses 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. Tenha cuidado, pois esse software deve ser distribuído separadamente do próprio plugin e pode representar riscos de segurança.

Uso com Open Cloud

HttpService pode atualmente 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 da API no 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 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 enviar:", 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 armazenamentos 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 do desenvolvedor

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 Luau

Notificações

CreateUserNotification

Lugares

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 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 parem 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 geral de 500 solicitações HTTP por minuto imposto a todas as outras solicitações.
Cada endpoint tem seu próprio limite por proprietário da chave da API (pode ser um usuário ou um grupo) que é imposto não importa de onde as chamadas venham (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:

Trate erros de forma adequada. Solicitações 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 tempo ao endpoint para "esfriar".
Agregue e envie dados em massa.

Quando possível, é recomendável deixar seu servidor coletar todos os dados necessários para enviar uma solicitação HTTP, em vez de várias solicitações pequenas. Por exemplo, se você estiver enviando uma solicitação HTTP para cada jogador em seu servidor, verifique se a API tem um endpoint de lote e, se sim, colete as informações de todos os jogadores e envie tudo em uma única solicitação.

Em alguns casos, você pode ter que 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. 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 do seu uso do 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)
Redirecionamento (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 (quaisquer outros códigos de erro não especificados retornados do serviço externo)
InternalError (um problema retornado do HttpService dentro do Roblox)

O gráfico de Tempo de Resposta não está correlacionado com os dados de status. Se você selecionar "Status" como um 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 web para os quais as solicitações estão sendo enviadas.

Português (Brasil)