HttpService
*Ce contenu est traduit en utilisant l'IA (Beta) et peut contenir des erreurs. Pour consulter cette page en anglais, clique ici.
HttpService permet d'envoyer des demandes HTTP depuis les serveurs de jeu en utilisant RequestAsync, GetAsync et PostAsync .Ce service permet aux jeux d'être intégrés à des services Web hors Roblox tels que l'analyse, le stockage de données, la configuration de serveurs distants, la déclaration d'erreurs, les calculs avancés ou la communication en temps réel.En outre, quelques API Web de Roblox peuvent également être accessibles via HttpService (voir ci-dessous).
HttpService abrite également les méthodes JSONEncode et JSONDecode qui sont utiles pour communiquer avec des services qui utilisent le format JSON.En outre, la méthode GenerateGUID fournit des étiquettes aléatoires de 128 bits qui peuvent être traitées comme uniques de manière probabiliste dans une variété de scénarios.
Vous ne devez envoyer des demandes HTTP que sur des plates-formes tierces de confiance pour éviter de rendre votre expérience vulnérable aux risques de sécurité.
Cette propriété ne peut pas être interagie à l'exécution.
Activer les demandes HTTP
Les méthodes d'envoi de demandes ne sont pas activées par défaut. Pour envoyer des demandes, vous devez activer les demandes HTTP pour votre expérience.
Utiliser dans les plugins
HttpService peut être utilisé par les plugins de Studio.Ils peuvent le faire pour vérifier les mises à jour, envoyer des données d'utilisation, télécharger du contenu ou une autre logique d'entreprise.La première fois qu'un plugin essaie de le faire, l'utilisateur peut être invité à donner l'autorisation au plugin de communiquer avec l'adresse web spécifique.Un utilisateur peut accepter, refuser et révoquer de telles permissions à tout moment via la fenêtre gestion des plugins .
Les plugins peuvent également communiquer avec d'autres logiciels exécutés sur le même ordinateur via les hôtes localhost et 127.0.0.1.En exécutant des programmes compatibles avec de tels plugins, vous pouvez étendre les fonctionnalités de votre plugin au-delà des capacités normales de Studio, telles que l'interaction avec le système de fichiers de votre ordinateur.Attention, ce type de logiciel doit être distribué séparément du plugin lui-même et peut présenter des risques de sécurité si vous n'êtes pas prudent.
Appeler les domaines Roblox
HttpService ne peut actuellement appeler qu'un sous-ensemble des points de fin du cloud ouvert.Nous prévoyons d'étendre ce jeu au fil du temps, donc veuillez utiliser le bouton Commentaires si vous avez des points finaux spécifiques que vous souhaitez voir :
Groupes
Stockage de données
En raison des restrictions actuelles sur HttpService, seuls les caractères alphanumériques et le caractère - sont autorisés dans les paramètres du chemin d'URL pour les domaines Roblox.Cela signifie que les magasins/entrées de données avec d'autres caractères spéciaux sont actuellement inaccessibles à partir de HttpService .
Objets d'inventaire
Boutique des créateurs
Vous pouvez appeler ces points finaux de la même manière que vous appelleriez tout autre point final via HttpService.La seule différence est que vous devez inclure une clé Open Cloud API dans la demande :
- Faites la demande (exemple de code ci-dessous).
Les limitations incluent ce qui suit :
- Seuls les en-têtes x-api-key et content-type sont autorisés.
- La balise x-api-key doit être une Secret.
- Seuls les caractères alphanumériques et le caractère - sont autorisés dans les paramètres du chemin d'URL.
- Seul le protocole https:// est pris en charge.
Limitation du taux
Pour chaque serveur de jeu Roblox, il y a une limite de 500 demandes HTTP par minute.Dépasser cela peut provoquer l'arrêt complet des méthodes d'envoi de requêtes pendant environ 30 secondes.Votre pcall() peut également échouer avec un message de « Nombre de demandes dépassant la limite ».
Les demandes de cloud ouvertes consomment la même limite globale de 500 requêtes HTTP par minute appliquée à toutes les autres demandes.
Chaque point d'extrémité du cloud ouvert a sa propre limite par propriétaire de clé API (peut être un utilisateur ou un groupe) qui est appliquée peu importe d'où proviennent les appels (HttpService , le web, etc.).Les en-têtes suivants sont renvoyés avec chaque réponse et vous permettent de voir les limites et votre quota restant :
- x-ratelimit-limit - Le nombre total de demandes autorisées à être faites par propriétaire de clé API (généralement par minute).
- x-ratelimit-remaining - Le nombre de demandes que la clé API utilisée peut encore faire est toujours autorisé.Si ce nombre est 0 et que vous recevez un code de statut de réponse HTTP 429, alors vous avez atteint la limite de taux pour cet endpoint.
- x-ratelimit-reset - Le nombre de secondes restantes avant que la limite de taux ne soit réinitialisée (c'est-à-dire avant que x-ratelimit-remaining ne soit réinitialisé à x-ratelimit-limit ).
Considerations supplémentaires
- Il y a des restrictions de port.Vous ne pouvez pas utiliser le port 1194 ou n'importe quel port inférieur à 1024, sauf 80 et 443.Si vous essayez d'utiliser un port bloqué, vous recevrez soit une erreur 403 Forbidden ou ERR_ACCESS_DENIED.
- Les demandes Web peuvent échouer pour de nombreuses raisons, il est donc important de "coder défensivement" (utiliser pcall() ) et d'avoir un plan pour lorsque les demandes échouent.
- Bien que le protocole http:// soit pris en charge, vous devez utiliser https:// partout où cela est possible.
- Les demandes envoyées doivent fournir une forme sécurisée d'authentification, comme une clé secrète prépartagée, afin que les acteurs malveillants ne puissent pas se faire passer pour l'un de vos serveurs de jeu Roblox.
- Soyez conscient de la capacité générale et des politiques de limitation des taux des serveurs web auxquels les demandes sont envoyées.
Échantillons de code
Cet exemple de code utilise HttpService's GetAsync pour faire une demande à Open Notify, un service Web qui fournit des données de la NASA.La demande est faite à un point final qui fournit des informations sur le nombre d'astronautes actuellement dans l'espace.La réponse est fournie au format JSON, donc elle est analysée en utilisant JSONDecode.Enfin, les données de réponse sont ensuite traitées et imprimées dans la sortie.
Testez ce script en collant le code source dans un script (HttpService ne peut pas être utilisé par les scripts locaux).De plus, assurez-vous d'activer les demandes HTTP dans vos paramètres de jeu (accueil > paramètres de jeu).
local HttpService = game:GetService("HttpService")
local URL_ASTROS = "http://api.open-notify.org/astros.json"
-- Faites la demande à notre URL d'extrémité
local response = HttpService:GetAsync(URL_ASTROS)
-- Analyser la réponse JSON
local data = HttpService:JSONDecode(response)
-- Les informations dans la table de données dépendent de la réponse 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
This code sample uses HttpService's GetAsync to make a request to an endpoint at Open Notify, a website that provides information from NASA. The endpoint provides information on the current location of the International Space Station. This example uses a defensive coding technique that you should use when making web requests. It wraps the call to GetAsync and JSONDecode in pcall, which protects our script from raising an error if either of these fail. Then, it checks the raw response for all proper data before using it. All of this is put inside a function that returns true or false depending of the request's success.
Whenever you're working with web requests, you should prepare for anything to go wrong. Perhaps your web endpoint changes or goes down - you don't want your game scripts raising errors and breaking your game. You want to handle both success and failure gracefully - have a plan in case your data is not available. Use pcall and make plenty of validity checks (if statements) on your data to make sure you're getting exactly what you expect.
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
Pastebin.com is a website that allows users to paste text (usually source code) for others to view publicly. This code sample uses HttpService PostAsync and the pastebin web API to automatically create a new public paste on the website. Since pastebin's API is designed to take data in as a URL encoded string, the code uses a for-loop to turn the dataFields table into a URL encoded string, such as hello=world&foo=bar. This is used as the HTTP POST data.
Test this code by first going to pastebin.com/api#1 and getting an API key (you'll need a pastebin account to do this). Then, paste your unique developer API key into the field api_dev_key in the code sample's dataFields table. Fill in any other information about the post you want to make, then run this code in a Script (not a LocalScript). If all goes well, you'll get a URL to your new paste in the Output window (or some error string from pastebin).
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)
This code sample demonstrates sending a single HTTP PATCH request with JSON data to the Open Cloud Update Group Membership endpoint. Every Open Cloud endpoint requires adding your API key to the x-api-key header to receive a successful response. The generated API key must be stored as a Secret that can later be retrieved with HttpService:GetSecret("API KEY SECRET NAME").
-- 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("The response was successful:", response.StatusCode, response.StatusMessage)
else
print("The response returned an error:", response.StatusCode, response.StatusMessage)
end
print("Response body:\n", response.Body)
print("Response headers:\n", HttpService:JSONEncode(response.Headers))
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("The Http request failed to send:", message)
end
Résumé
Propriétés
Indique si les demandes HTTP peuvent être envoyées à des sites Web externes.
Méthodes
Génère une chaîne aléatoire UUID/GUID, optionnellement avec des crochets courbes.
Retourne un Secret de la boutique de secrets.
Décode une chaîne JSON en table Luau.
Générer une chaîne JSON à partir d'une table Luau.
Remplace les caractères non sécurisés URL par '%' et deux caractères hexadécimaux.
Envoie une demande HTTP GET .
- PostAsync(url : Variant,data : string,content_type : Enum.HttpContentType,compress : boolean,headers : Variant):string
Envoie une demande HTTP POST .
Envoie une demande HTTP en utilisant n'importe quelle méthode HTTP donnant un dictionnaire d'informations.
Propriétés
HttpEnabled
Méthodes
GenerateGUID
Paramètres
Retours
Échantillons de code
local HttpService = game:GetService("HttpService")
local result = HttpService:GenerateGUID(true)
print(result) --> Example output: {4c50eba2-d2ed-4d79-bec1-02a967f49c58}
JSONDecode
Paramètres
Retours
Échantillons de code
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
JSONEncode
Paramètres
Retours
Échantillons de code
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)
UrlEncode
Paramètres
Retours
Échantillons de code
local HttpService = game:GetService("HttpService")
local content = "Je suis allé au cinéma." -- Français pour "Je suis allé au cinéma"
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)
GetAsync
Paramètres
Retours
Échantillons de code
local HttpService = game:GetService("HttpService")
local URL_ASTROS = "http://api.open-notify.org/astros.json"
-- Faites la demande à notre URL d'extrémité
local response = HttpService:GetAsync(URL_ASTROS)
-- Analyser la réponse JSON
local data = HttpService:JSONDecode(response)
-- Les informations dans la table de données dépendent de la réponse 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
PostAsync
Paramètres
Retours
Échantillons de code
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)
RequestAsync
Paramètres
Retours
Échantillons de code
-- 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("The response was successful:", response.StatusCode, response.StatusMessage)
else
print("The response returned an error:", response.StatusCode, response.StatusMessage)
end
print("Response body:\n", response.Body)
print("Response headers:\n", HttpService:JSONEncode(response.Headers))
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("The Http request failed to send:", message)
end