Requêtes HTTP en jeu

*Ce contenu est traduit en utilisant l'IA (Beta) et peut contenir des erreurs. Pour consulter cette page en anglais, clique ici.

Vous pouvez utiliser HttpService pour envoyer des requêtes HTTP génériques à des services web tiers pour des cas d'utilisation tels que l'analyse, le stockage de données ou la journalisation des erreurs. HttpService prend également en charge certains points de terminaison d'Open Cloud.

Activer les requêtes HTTP

Les méthodes HttpService:GetAsync(), HttpService:PostAsync() et HttpService:RequestAsync() ne sont pas activées par défaut. Pour envoyer des requêtes, vous devez Autoriser les requêtes HTTP sous Fichier ⟩ Paramètres de l'expérience ⟩ Sécurité dans Studio.

Utiliser dans les plugins

Vous pouvez utiliser HttpService dans les plugins Studio pour vérifier les mises à jour, télécharger du contenu ou d'autres logiques métier. La première fois qu'un plugin tente d'utiliser le service, l'utilisateur peut être invité à donner au plugin la permission de communiquer avec l'adresse web particulière. Les utilisateurs peuvent accepter, refuser et révoquer ces 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 la fonctionnalité de votre plugin au-delà des capacités normales de Studio, comme interagir avec le système de fichiers de votre ordinateur. Attention, ces logiciels doivent être distribués séparément du plugin lui-même et peuvent poser des risques de sécurité.

Utiliser avec Open Cloud

HttpService peut actuellement appeler un sous-ensemble des points de terminaison d'Open Cloud. Vous pouvez appeler ces points de terminaison de la même manière que vous appelleriez n'importe quel autre point de terminaison via HttpService. La seule différence est que vous devez inclure une clé API Open Cloud dans la requête :

Créer une clé API Open Cloud.
Enregistrer la clé API dans votre magasin de secrets.
Effectuer la requête.

L'exemple de code suivant démontre comment mettre à jour l'appartenance d'un groupe d'un utilisateur depuis un jeu :

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", -- Lors de l'envoi de JSON, définissez ceci !
			["x-api-key"] = HttpService:GetSecret("APIKey"), -- Défini dans Creator Hub
		},
		Body = HttpService:JSONEncode({ role = `groups/{groupId}/roles/{roleId}` }),
	})

	if response.Success then
		print("La réponse a été réussie :", response.StatusCode, response.StatusMessage)
	else
		print("La réponse a renvoyé une erreur :", response.StatusCode, response.StatusMessage)
	end
	print("Corps de la réponse :\n", response.Body)
	print("En-têtes de la réponse :\n", HttpService:JSONEncode(response.Headers))
end

-- Enveloppez la fonction dans pcall() pour plus de sécurité
local success, errorMessage = pcall(request)
if not success then
	print("La requête HTTP a échoué à être envoyée :", errorMessage)
end

Points de terminaison Open Cloud pris en charge

Les points de terminaison suivants sont pris en charge. En raison des limitations actuelles de HttpService, la chaîne .. n'est pas autorisée dans les paramètres de chemin d'URL vers les domaines Roblox. Cela signifie, par exemple, que les magasins de données et les entrées contenant cette chaîne sont actuellement inaccessibles depuis HttpService.

Actifs

Interdictions et blocages

Configurations

Boutique des créateurs

Produits développeurs

Passes de jeu

Magasins de données et de mémoire

Magasins de données :

Magasins de mémoire :

Magasins de données ordonnés :

Groupes

Inventaires

ListInventoryItems

Exécution Luau

Notifications

CreateUserNotification

Lieux

Univers

Utilisateurs

Limitations

Seules les en-têtes x-api-key et content-type sont autorisées.
L'en-tête x-api-key doit être un Secret. Voir Magasins de secrets.
La chaîne ".." n'est pas autorisée dans les paramètres de chemin d'URL.
Seul le protocole HTTPS est pris en charge.
Vous ne pouvez pas utiliser le port 1194 ou tout port inférieur à 1024, sauf 80 et 443. Si vous essayez d'utiliser un port bloqué, vous recevez soit une erreur 403 Forbidden, soit une erreur ERR_ACCESS_DENIED.

Limites de taux

Pour chaque serveur de jeu Roblox, il y a une limite de 2500 requêtes Open Cloud par minute. Dépasser cette limite peut entraîner un blocage des méthodes d'envoi de requêtes pendant environ 30 secondes. Votre pcall() peut également échouer avec un message indiquant que Le nombre de requêtes Open Cloud a dépassé la limite.

Les requêtes Open Cloud ne consomment pas la même limite globale de 500 requêtes HTTP par minute imposée sur toutes les autres requêtes.
Chaque point de terminaison a sa propre limite par propriétaire de clé API (qui peut être un utilisateur ou un groupe) qui est appliquée peu importe d'où proviennent les appels (HttpService, le web, etc.).

Pour des informations détaillées sur les limites de taux d'Open Cloud, la limitation de taux basée sur l'authentification et les meilleures pratiques, voir Limites de taux.

Meilleures pratiques

Pour optimiser votre utilisation de HttpService et éviter de dépasser les limites, appliquez les meilleures pratiques suivantes :

Gérez les erreurs avec grâce. Les requêtes web peuvent échouer pour de nombreuses raisons. Utilisez pcall() et ayez un plan pour lorsque les requêtes échouent. De plus, validez et assainissez strictement toutes les données reçues des API externes, en vous assurant de la validité des données lorsque cela est possible.
Utilisez l'atténuation exponentielle pour rester en dessous des limites.

Si une requête renvoie une erreur récupérable, au lieu de réessayer immédiatement, attendez deux secondes, puis quatre, huit, etc. entre les tentatives. Cela aide à limiter la congestion et améliore les chances d'une requête réussie en donnant au point de terminaison le temps de "se refroidir".
Agrégez et envoyez des données en masse.

Lorsque cela est possible, il est recommandé de laisser votre serveur collecter toutes les données nécessaires afin d'envoyer une seule requête HTTP, plutôt que plusieurs petites requêtes. Par exemple, si vous envoyez une requête HTTP pour chaque joueur de votre serveur, vérifiez si l'API dispose d'un point de terminaison en masse/batch et, si c'est le cas, collectez les informations de tous les joueurs et envoyez-les toutes dans une seule requête.

Dans certains cas, vous devrez peut-être utiliser HttpService:RequestAsync() pour inclure des données dans le corps de la requête.
Utilisez les points de terminaison HTTP/2. HTTP/2 offre des avantages de performance significatifs grâce à des fonctionnalités telles que la compression des en-têtes et le multiplexage des requêtes/réponses sur une seule connexion. HttpService utilise automatiquement HTTP/2 lorsqu'il est disponible. Notez que la spécification HTTP/2 exige que tous les noms d'en-tête soient envoyés en minuscules.

Observabilité

Le Tableau de bord d'observabilité fournit des informations et des analyses pour surveiller et dépanner votre utilisation de HttpService. Le tableau de bord présente deux graphiques principaux : Nombre de requêtes qui suit le volume de requêtes HttpService de votre jeu, et Temps de réponse qui mesure la latence pour que les points de terminaison répondent.

Les dimensions disponibles pour le filtrage et la répartition sont définies comme suit :

Type de requête

GET
POST
PUT
PATCH
DELETE
Autre (pour les types de requêtes non spécifiés)

Statut

Succès (codes d'état HTTP 1xx et 2xx)
Redirection (codes d'état HTTP 3xx)
400 (Mauvaise requête)
401 (Non autorisé)
403 (Interdit)
404 (Non trouvé)
429 (Trop de requêtes)
500 (Erreur interne du serveur)
503 (Service indisponible)
ExternalError (tous les autres codes d'erreur non spécifiés renvoyés par le service externe)
InternalError (un problème renvoyé par HttpService au sein de Roblox)

Le graphique Temps de réponse n'est pas corrélé avec les données de statut. Si vous sélectionnez "Statut" comme répartition ou filtre, ce graphique ne montrera pas de données.

Considérations supplémentaires

Les requêtes doivent fournir une forme d'authentification sécurisée, telle qu'une clé secrète pré-partagée, afin que des acteurs malveillants ne puissent pas se faire passer pour l'un de vos serveurs Roblox.
Soyez conscient des politiques de capacité générale et de limitation de taux des serveurs web auxquels les requêtes sont envoyées.

Français