HttpService

Quando definido para true, permite que scripts enviem solicitações para sites usando HttpService:GetAsync(), HttpService:PostAsync() e HttpService:RequestAsync().

Essa propriedade deve ser alternada através da interface Configurações do Jogo no Studio, ou para experiências não publicadas definindo essa propriedade para usando a barra de comando :

game:GetService("HttpService").HttpEnabled = true

Este método gera uma string de identificador universalmente única aleatória UUID (UUID).Os dezesseis bytes de um UUID são representados como 32 dígitos hexadecimais (base 16), exibidos em cinco grupos separados por hifens na forma 8-4-4-4-12 para um total de 36 caracteres, por exemplo 123e4567-e89b-12d3-a456-426655440000 .

A especificação UUID usada é Versão 4 (aleatória), variante 1 (DCE 1.1, ISO/IEC 11578:1996).Os UIDs desta versão são os mais comumente usados devido à sua simplicidade, pois são gerados aleatoriamente inteiramente.Observe que esta versão não tem certas características que outras versões do UUID têm, como marcas de tempo codificadas, endereços MAC ou classificação baseada em tempo, como UUIDv7 ou ULID.

Existem mais de 5.3×10 ³⁶ UIDs exclusivos v4, nos quais a probabilidade de encontrar um duplicado dentro de 103 trilhões de UIDs é de um em um bilhão.

O argumento wrapInCurlyBraces determina se a string retornada está em curvetas ( {} ). Por exemplo:

• true : {94b717b2-d54f-4340-a504-bd809ef5bf5c}
• false : db454790-7563-44ed-ab4b-397ff5df737b

Parâmetros

Devolução

local HttpService = game:GetService("HttpService")

local result = HttpService:GenerateGUID(true)

print(result) --> Example output: {4c50eba2-d2ed-4d79-bec1-02a967f49c58}

Este método retorna um valor previamente adicionado à loja de segredos para a experiência.O conteúdo secreto não é impressível e não está disponível quando a experiência é executada localmente.

O retornado Secret pode ser transformado usando métodos integrados, como Secret:AddPrefix(). Espera-se que seja enviado como parte de uma solicitação HTTP.

Para mais informações, veja o guia de uso.

Parâmetros

Devolução

Este método transforma um objeto JSON ou array em uma tabela Luau com as seguintes características:

• As chaves da tabela são strings ou números, mas não ambos. Se um objeto JSON contiver ambos, as chaves de string são ignoradas.
• Um objeto JSON vazio gera uma tabela Luau vazia ( {} ).
• Se a string input não for um objeto JSON válido, este método irá lançar um erro.

Para codificar uma tabela Luau em um objeto JSON, use o método HttpService:JSONEncode().

Este método pode ser usado independentemente de se as solicitações HTTP estão habilitadas.

Parâmetros

Devolução

local HttpService = game:GetService("HttpService")

local jsonString = [[
{
	"message": "success",
	"info": {
		"points": 120,
		"isLeader": true,
		"user": {
			"id": 12345,
			"name": "JohnDoe"
		},
		"past_scores": [50, 42, 95],
		"best_friend": null
	}
}
]]

local data = HttpService:JSONDecode(jsonString)

if data.message == "success" then
	-- Since tab["hello"] and tab.hello are equivalent,
	-- you could also use data["info"]["points"] here:
	print("I have " .. data.info.points .. " points")
	if data.info.isLeader then
		print("I am the leader")
	end
	print("I have " .. #data.info.past_scores .. " past scores")

	print("All the information:")
	for key, value in pairs(data.info) do
		print(key, typeof(value), value)
	end
end

Este método transforma uma tabela Luau em um objeto JSON ou array com base nas seguintes diretrizes:

• As chaves da tabela devem ser strings ou números. Se uma tabela contiver ambas, um array tem prioridade (chaves de strings são ignoradas).

• Uma tabela vazia de Luau ( {} ) gera um array JSON vazio.

• O valor nil nunca é gerado.

• Referências de tabela cíclicas causam um erro.

  Este método permite valores como inf e nan que não são JSON válidos.Isso pode causar problemas se você quiser usar o JSON emitido em outro lugar.

Para reverter o processo de codificação e decodificar um objeto JSON, use o método HttpService:JSONDecode().

Este método pode ser usado independentemente de se as solicitações HTTP estão habilitadas.

Parâmetros

Devolução

local HttpService = game:GetService("HttpService")

local tab = {
	-- Remember: these lines are equivalent
	--["message"] = "success",
	message = "success",

	info = {
		points = 123,
		isLeader = true,
		user = {
			id = 12345,
			name = "JohnDoe",
		},
		past_scores = { 50, 42, 95 },
		best_friend = nil,
	},
}

local json = HttpService:JSONEncode(tab)
print(json)

Este método codifica em porcentagem uma determinada string para que os caracteres reservados sejam codificados corretamente com % e dois caracteres hexadecimais.

Isso é útil ao formatar URLs para uso com HttpService:GetAsync() / HttpService:PostAsync() ou POST dados do tipo de mídia application/x-www-form-urlencoded ( Enum.HttpContentType.ApplicationUrlEncoded ).

Por exemplo, quando você codifica o URL https://www.roblox.com/discover#/, este método retorna https%3A%2F%2Fwww%2Eroblox%2Ecom%2Fdiscover%23%2F .

Parâmetros

Devolução

local HttpService = game:GetService("HttpService")

local content = "Je suis allé au cinéma." -- Francês para "Eu fui ao cinema"
local result = HttpService:UrlEncode(content)

print(result) --> Je%20suis%20all%C3%A9%20au%20cinema%2E

local HttpService = game:GetService("HttpService")

local URL_PASTEBIN_NEW_PASTE = "https://pastebin.com/api/api_post.php"
local dataFields = {
	-- Pastebin API developer key from
	-- https://pastebin.com/api#1
	["api_dev_key"] = "FILL THIS WITH YOUR API DEVELOPER KEY",

	["api_option"] = "paste", -- keep as "paste"
	["api_paste_name"] = "HttpService:PostAsync", -- paste name
	["api_paste_code"] = "Hello, world", -- paste content
	["api_paste_format"] = "text", -- paste format
	["api_paste_expire_date"] = "10M", -- expire date
	["api_paste_private"] = "0", -- 0=public, 1=unlisted, 2=private
	["api_user_key"] = "", -- user key, if blank post as guest
}

-- The pastebin API uses a URL encoded string for post data
-- Other APIs might use JSON, XML or some other format
local data = ""
for k, v in pairs(dataFields) do
	data = data .. ("&%s=%s"):format(HttpService:UrlEncode(k), HttpService:UrlEncode(v))
end
data = data:sub(2) -- Remove the first &

-- Here's the data we're sending
print(data)

-- Make the request
local response = HttpService:PostAsync(URL_PASTEBIN_NEW_PASTE, data, Enum.HttpContentType.ApplicationUrlEncoded, false)
-- The response will be the URL to the new paste (or an error string if something was wrong)
print(response)

Este método envia um pedido HTTP GET .Ela funciona de forma semelhante a RequestAsync() exceto que aceita parâmetros de solicitação HTTP como parâmetros de método em vez de um único dicionário e retorna apenas o corpo da resposta HTTP.Em geral, este método é útil apenas como abreviação e RequestAsync() deve ser usado na maioria dos casos.

Quando true , o parâmetro nocache impede que este método armazene resultados de chamadas anteriores com o mesmo url.

Parâmetros

Devolução

local HttpService = game:GetService("HttpService")

local URL_ASTROS = "http://api.open-notify.org/astros.json"

-- Faça o pedido para o nosso URL de endpoint
local response = HttpService:GetAsync(URL_ASTROS)

-- Analise a resposta JSON
local data = HttpService:JSONDecode(response)

-- A informação na tabela de dados depende da resposta JSON
if data.message == "success" then
	print("There are currently " .. data.number .. " astronauts in space:")
	for i, person in pairs(data.people) do
		print(i .. ": " .. person.name .. " is on " .. person.craft)
	end
end

local HttpService = game:GetService("HttpService")

-- Where is the International Space Station right now?
local URL_ISS = "http://api.open-notify.org/iss-now.json"

local function printISS()
	local response
	local data
	-- Use pcall in case something goes wrong
	pcall(function()
		response = HttpService:GetAsync(URL_ISS)
		data = HttpService:JSONDecode(response)
	end)
	-- Did our request fail or our JSON fail to parse?
	if not data then
		return false
	end

	-- Fully check our data for validity. This is dependent on what endpoint you're
	-- to which you're sending your requests. For this example, this endpoint is
	-- described here:  http://open-notify.org/Open-Notify-API/ISS-Location-Now/
	if data.message == "success" and data.iss_position then
		if data.iss_position.latitude and data.iss_position.longitude then
			print("The International Space Station is currently at:")
			print(data.iss_position.latitude .. ", " .. data.iss_position.longitude)
			return true
		end
	end
	return false
end

if printISS() then
	print("Success")
else
	print("Something went wrong")
end

Este método envia um pedido HTTP POST .Ela funciona de forma semelhante a RequestAsync() exceto que aceita parâmetros de solicitação HTTP como parâmetros de método em vez de um único dicionário e retorna apenas o corpo da resposta HTTP.Em geral, este método é útil apenas como abreviação e RequestAsync() deve ser usado na maioria dos casos.

Quando true , o parâmetro compress controla se grandes corpos de solicitação serão compactados usando gzip .

Parâmetros

Devolução

local HttpService = game:GetService("HttpService")

local URL_PASTEBIN_NEW_PASTE = "https://pastebin.com/api/api_post.php"
local dataFields = {
	-- Pastebin API developer key from
	-- https://pastebin.com/api#1
	["api_dev_key"] = "FILL THIS WITH YOUR API DEVELOPER KEY",

	["api_option"] = "paste", -- keep as "paste"
	["api_paste_name"] = "HttpService:PostAsync", -- paste name
	["api_paste_code"] = "Hello, world", -- paste content
	["api_paste_format"] = "text", -- paste format
	["api_paste_expire_date"] = "10M", -- expire date
	["api_paste_private"] = "0", -- 0=public, 1=unlisted, 2=private
	["api_user_key"] = "", -- user key, if blank post as guest
}

-- The pastebin API uses a URL encoded string for post data
-- Other APIs might use JSON, XML or some other format
local data = ""
for k, v in pairs(dataFields) do
	data = data .. ("&%s=%s"):format(HttpService:UrlEncode(k), HttpService:UrlEncode(v))
end
data = data:sub(2) -- Remove the first &

-- Here's the data we're sending
print(data)

-- Make the request
local response = HttpService:PostAsync(URL_PASTEBIN_NEW_PASTE, data, Enum.HttpContentType.ApplicationUrlEncoded, false)
-- The response will be the URL to the new paste (or an error string if something was wrong)
print(response)

Este método envia um pedido HTTP usando um dicionário para especificar os dados de solicitação, como o URL alvo, o método, os cabeçalhos e os dados do corpo da solicitação.Ele retorna um dicionário que descreve os dados de resposta recebidos.Opcionalmente, o pedido pode ser compactado usando Enum.HttpCompression.

Solicitar campos de dicionário

<th>Tipo</th>

    <th>Requerido</th>

    <th>Descrição</th>
  </tr>
</thead>

<tbody>
  <tr>
    <td><code>Url</code></td>

    <td>Corda</td>

    <td>sim</td>

    <td>O URL-alvo para este pedido. Deve usar <code>http</code> ou <code>https</code> protocolos.</td>
  </tr>

  <tr>
    <td><code>Método</code></td>

    <td>Corda</td>

    <td>no</td>

    <td>O método HTTP usado por este pedido, na maioria das vezes <code>obter</code> ou <code>enviar</code>.</td>
  </tr>

  <tr>
    <td><code>Cabeçalhos</code></td>

    <td>Dicionário</td>

    <td>no</td>

    <td>Um dicionário de cabeçalhos a ser usado com este pedido. A maioria dos cabeçalhos HTTP são aceitos aqui, mas não todos.</td>
  </tr>

  <tr>
    <td><code>Corpo</code></td>

    <td>Corda</td>

    <td>no</td>

    <td>O corpo da solicitação.Pode ser qualquer string, incluindo dados binários.Deve ser excluído ao usar os métodos <code>GET</code> ou <code>HEAD</code> HTTP.Pode ser necessário especificar o cabeçalho <code>Tipo de Conteúdo</code> ao enviar JSON ou outros formatos.</td>
  </tr>

  <tr>
    <td><code>Comprimir</code></td>

    <td><code>Enumeração.HttpCompression</code></td>

    <td>no</td>

    <td>Um campo de compressão opcional que compactará os dados na solicitação.O valor pode ser <code>Enum.HttpCompression.None</code> ou <code>Enum.HttpCompression.Gzip</code>.</td>
  </tr>
</tbody>

Métodos HTTP suportados

Os métodos de solicitação HTTP especificam o propósito da solicitação feita e o que é esperado se a solicitação for bem-sucedida.Por exemplo, o método de solicitação GET informa ao servidor no endereço solicitado que um recurso está sendo solicitado e, se for bem-sucedido, o recurso nesse endereço será retornado.Da mesma forma, o método de solicitação HEAD faz o mesmo, exceto que o servidor sabe retornar uma resposta sem um elemento Body.

<th>Descrição</th>

    <th>Segura</th>
  </tr>
</thead>

<tbody>
  <tr>
    <td><code>OBTER</code><a href="https://developer.mozilla.org/docs/Web/HTTP/Methods/GET">ⓘ</a></td>

    <td>O método <code>GET</code> solicita o recurso no endereço especificado. Não suporta o uso do parâmetro <code>Corpo</code>.</td>

    <td>Sim</td>
  </tr>

  <tr>
    <td><code>Cabeça</code><a href="https://developer.mozilla.org/docs/Web/HTTP/Methods/HEAD">ⓘ</a></td>

    <td>O método <code>Cabeça</code> solicita uma resposta idêntica a um pedido <code>Obter</code>, mas sem corpo de resposta.Não suporta o uso do parâmetro <code>Corpo</code>.</td>

    <td>Sim</td>
  </tr>

  <tr>
    <td><code>POST</code><a href="https://developer.mozilla.org/docs/Web/HTTP/Methods/POST">ⓘ</a></td>

    <td>O método <code>POST</code> envia os dados fornecidos de <code>Corpo</code> ao endereço solicitado.</td>

    <td>No</td>
  </tr>

  <tr>
    <td><code>PUT</code><a href="https://developer.mozilla.org/docs/Web/HTTP/Methods/PUT">ⓘ</a></td>

    <td>O método <code>PUT</code> substitui todas as iterações atuais do recurso especificado dentro dos dados fornecidos <code>Corpo</code>.</td>

    <td>No</td>
  </tr>

  <tr>
    <td><code>DELETE</code><a href="https://developer.mozilla.org/docs/Web/HTTP/Methods/DELETE">ⓘ</a></td>

    <td>O método <code>DELETE</code> exclui o recurso especificado nos dados fornecidos <code>Corpo</code> na endereço solicitado.</td>

    <td>No</td>
  </tr>

  <tr>
    <td><code>OPÇÕES</code>    <a href="https://developer.mozilla.org/docs/Web/HTTP/Methods/OPTIONS">ⓘ</a></td>

    <td>O método <code>OPÇÕES</code> solicita as opções de comunicação permitidas para o endereço fornecido.</td>

    <td>Sim</td>
  </tr>

  <tr>
    <td><code>RASTRO</code><a href="https://developer.mozilla.org/docs/Web/HTTP/Methods/TRACE">ⓘ</a></td>

    <td>O método <code>TRACE</code> realiza um teste de loop-back de mensagem ao longo do caminho para o recurso especificado nos dados fornecidos <code>Corpo</code>.</td>

    <td>Sim</td>
  </tr>

  <tr>
    <td><code>PATCH</code><a href="https://developer.mozilla.org/docs/Web/HTTP/Methods/PATCH">ⓘ</a></td>

    <td>O método <code>PATCH</code> aplica alterações parciais ao recurso especificado nos dados fornecidos do <code>Corpo</code> na endereço solicitado.</td>

    <td>No</td>
  </tr>
</tbody>

Cabeçalhos HTTP

No dicionário de solicitações, você pode especificar cabeçalhos HTTP personalizados para usar na solicitação.No entanto, alguns cabeçalhos não podem ser especificados.Por exemplo, Content-Length é determinado a partir do corpo da solicitação.User-Agent e Roblox-Id são bloqueados pelo Roblox.Outros cabeçalhos como Accept ou Cache-Control usam valores padrão, mas podem ser substituídos.Mais comumente, algumas APIs REST podem exigir que as chaves da API ou outra autenticação de serviço sejam especificadas nos cabeçalhos de solicitação.

O método RequestAsync() não detecta o formato do conteúdo do corpo.Muitos servidores web requerem que o cabeçalho Content-Type seja definido adequadamente ao enviar determinados formatos.Outros métodos de usam o enum; para este método, defina o cabeçalho apropriadamente: , , , ou são valores de cabeçalho de substituição para os respectivos valores de enum.

Campos do dicionário de resposta

RequestAsync() retorna um dicionário que contém os seguintes campos:

<th>Tipo</th>

    <th>Descrição</th>
  </tr>
</thead>

<tbody>
  <tr>
    <td><code>Sucesso</code></td>

    <td>Booleano</td>

    <td>O status de sucesso da solicitação. Isso é verdade se e somente se o <code>StatusCode</code> estiver dentro do alcance <code>200</code> - <code>299</code>.</td>
  </tr>

  <tr>
    <td><code>Código de Status</code></td>

    <td>Inteiro</td>

    <td>O código de resposta HTTP que identifica o status da resposta.</td>
  </tr>

  <tr>
    <td><code>Message de Status</code></td>

    <td>Corda</td>

    <td>A mensagem de status que foi enviada de volta.</td>
  </tr>

  <tr>
    <td><code>Cabeçalhos</code></td>

    <td>Dicionário</td>

    <td>Um dicionário de cabeçalhos que foram definidos nesta resposta.</td>
  </tr>

  <tr>
    <td><code>Corpo</code></td>

    <td />

    <td>O corpo da solicitação (conteúdo) recebido na resposta.</td>
  </tr>
</tbody>

Caixas de erro

RequestAsync() eleva um erro se os tempos de resposta expirarem ou se o servidor alvo rejeitar a solicitação.Se um serviço web cair por algum motivo, pode causar scripts que usam esse método a parar de funcionar completamente.Muitas vezes é uma boa ideia envolver chamadas a este método em pcall() e lidar com casos de falha de forma elegante se a informação necessária não estiver disponível.

Limitações

A limitação atual para enviar e receber solicitações HTTP é de 500 solicitações por minuto. Solicitações acima desse limite falharão.

Parâmetros

Devolução

-- Remember to set enable HTTP Requests in game settings!
local HttpService = game:GetService("HttpService")

local function request()
	local response = HttpService:RequestAsync({
		Url = "http://httpbin.org/post", -- This website helps debug HTTP requests
		Method = "POST",
		Headers = {
			["Content-Type"] = "application/json", -- When sending JSON, set this!
		},
		Body = HttpService:JSONEncode({ hello = "world" }),
	})

	if response.Success then
		print("Status code:", response.StatusCode, response.StatusMessage)
		print("Response body:\n", response.Body)
	else
		print("The request failed:", response.StatusCode, response.StatusMessage)
	end
end

-- Remember to wrap the function in a 'pcall' to prevent the script from breaking if the request fails
local success, message = pcall(request)
if not success then
	print("Http Request failed:", message)
end

-- Remember to set enable HTTP Requests in game settings!
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}`, -- Updates a user's group membership
		Method = "PATCH",
		Headers = {
			["Content-Type"] = "application/json", -- When sending JSON, set this!
			["x-api-key"] = HttpService:GetSecret("APIKey"), -- Set in Creator Hub
		},
		Body = HttpService:JSONEncode({ role = `groups/{groupId}/roles/{roleId}` }),
	})

	if response.Success then
		print("Status code:", response.StatusCode, response.StatusMessage)
		print("Response body:\n", response.Body)
		print("Response headers:\n", HttpService:JSONEncode(response.Headers))
	else
		print("The request failed:", response.StatusCode, response.StatusMessage)
	end
end

-- Remember to wrap the function in a 'pcall' to prevent the script from breaking if the request fails
local success, message = pcall(request)
if not success then
	print("Http Request failed:", message)
end