Requêtes HTTP en jeu

Vous pouvez utiliser HttpService pour envoyer des requêtes HTTP génériques à des services Web tiers pour des cas d'utilisation comme l'analyse, le stockage de données ou la journalisation des erreurs. HttpService prend également en charge certains points de terminaison 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 Paramètres de l'expérience pour votre jeu.

Utilisation 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 la permission au plugin de communiquer avec l'adresse Web particulière. Les utilisateurs peuvent accepter, refuser et révoquer ces autorisations à 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, comme interagir avec le système de fichiers de votre ordinateur. Faites attention, car de tels logiciels doivent être distribués séparément du plugin lui-même et peuvent représenter des risques pour la sécurité.

Utilisation avec Open Cloud

HttpService peut actuellement appeler un sous-ensemble des points de terminaison 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 :

1. Créer une clé API Open Cloud.
2. Enregistrer la clé API dans votre magasin de secrets.
3. Faites la requête.

L'exemple de code suivant démontre comment mettre à jour l'appartenance à 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 réussi :", response.StatusCode, response.StatusMessage)
	else
		print("La réponse a retourné 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 n'a pas pu ê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 sur 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 à partir de HttpService.

Actifs

• GetAsset
• ListAssetVersions
• GetAssetVersion

Interdictions et blocages

• ListUserRestrictions (Place)
• GetUserRestriction (Place)
• UpdateUserRestriction (Place)
• ListUserRestrictions (Univers)
• GetUserRestriction (Univers)
• UpdateUserRestriction (Univers)
• ListUserRestrictionLogs (Univers)

Configurations

• GetConfigRepositoryValues
• GetConfigRepositoryDraft
• UpdateDraft
• DeleteDraft
• OverwriteDraft
• GetConfigRepositoryFull
• PublishDraft
• ListRevisions
• RestoreRevision

Boutique Créateur

• CreateCreatorStoreProduct
• GetCreatorStoreProduct
• UpdateCreatorStoreProduct
• CreatorStoreAssetsSearch

Produits développeur

• CreateDeveloperProduct
• UpdateDeveloperProduct
• GetDeveloperProductConfig
• ListDeveloperProductConfigsByUniverse

Passes de jeu

• CreateGamePass
• UpdateGamePass
• GetGamePassConfig
• ListGamePassConfigsByUniverse

Magasins de données et de mémoire

Magasins de données :

• ListDataStores
• SnapshotDataStores
• ListDataStoreEntries
• CreateDataStoreEntry
• GetDataStoreEntry
• DeleteDataStoreEntry
• UpdateDataStoreEntry
• IncrementDataStoreEntry
• ListDataStoreEntryRevisions
• ListDataStoreEntries (With Scope)
• CreateDataStoreEntry (With Scope)
• GetDataStoreEntry (With Scope)
• DeleteDataStoreEntry (With Scope)
• UpdateDataStoreEntry (With Scope)
• IncrementDataStoreEntry (With Scope)
• ListDataStoreEntryRevisions (With Scope)

Magasins de mémoire :

• CreateMemoryStoreQueueItem
• DiscardMemoryStoreQueueItems
• ReadMemoryStoreQueueItems
• ListMemoryStoreSortedMapItems
• CreateMemoryStoreSortedMapItem
• GetMemoryStoreSortedMapItem
• DeleteMemoryStoreSortedMapItem
• UpdateMemoryStoreSortedMapItem
• FlushMemoryStore

Magasins de données ordonnés :

• ListOrderedDataStoreEntries
• CreateOrderedDataStoreEntry
• GetOrderedDataStoreEntry
• DeleteOrderedDataStoreEntry
• UpdateOrderedDataStoreEntry
• IncrementOrderedDataStoreEntry

Groupes

• GetGroup
• ListGroupJoinRequests
• AcceptGroupJoinRequest
• DeclineGroupJoinRequest
• ListGroupMemberships
• UpdateGroupMembership
• ListGroupRoles
• GetGroupRole
• GetGroupShout

Inventaires

• ListInventoryItems

Exécution Luau

• CreateLuauExecutionSessionTaskBinaryInput
• CreateLuauExecutionSessionTask
• CreateLuauExecutionSessionTask (avec version)
• GetLuauExecutionSessionTask
• ListLuauExecutionSessionTaskLogs

Notifications

• CreateUserNotification

Lieux

• GetPlace
• UpdatePlace
• GetInstance
• UpdateInstance

Univers

• UpdateUniverse
• GetUniverse
• PublishUniverseMessage
• RestartUniverseServers

Utilisateurs

• GetUser
• GenerateUserThumbnail

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 en dessous de 1024, sauf 80 et 443. Si vous essayez d'utiliser un port bloqué, vous recevez soit une erreur 403 Forbidden ou ERR_ACCESS_DENIED.

Limites de fréquence

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 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 appliquée à toutes les autres requêtes.
• Chaque point de terminaison 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.).

Pour des informations détaillées sur les limites de fréquence d'Open Cloud, le throttling basé sur l'authentification, et les meilleures pratiques, voir Limites de fréquence.

Meilleures pratiques

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

• Gérer les erreurs avec grâce. Les demandes Web peuvent échouer pour de nombreuses raisons. Utilisez pcall() et ayez un plan pour quand les demandes échouent. En outre, validez et assainissez strictement toutes les données reçues des API externes, en assurant des données correctes lorsque cela est possible.

• Utilisez un retrait exponentiel pour rester en dessous des limites.

  Si une demande retourne 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 demande réussie en laissant le point de terminaison le temps de "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 dans votre serveur, vérifiez si l'API a un point de terminaison de masse/lots et, si c'est le cas, collectez les informations de tous les joueurs et envoyez-les toutes dans une seule demande.

  Dans certains cas, vous devrez utiliser HttpService:RequestAsync() pour inclure des données dans le corps de la demande.

• Utilisez des 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 la multiplexion 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 insights et des analyses pour suivre et dépanner votre utilisation de HttpService. Le tableau de bord présente deux graphiques principaux : Nombre de demandes qui suit le volume des demandes 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 filtrer et décomposer sont définies comme suit :

Type de demande

• GET
• POST
• PUT
• PATCH
• DELETE
• Autre (pour les types de demande non spécifiés)

Statut

• Succès (codes de statut HTTP 1xx et 2xx)
• Redirection (codes de statut HTTP 3xx)
• 400 (Mauvaise demande)
• 401 (Non autorisé)
• 403 (Interdit)
• 404 (Non trouvé)
• 429 (Trop de demandes)
• 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 retourné par HttpService dans Roblox)

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

Considérations supplémentaires

• Les requêtes doivent fournir une forme sécurisée d'authentification, 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 générales de capacité et de limitation de fréquence des serveurs Web auxquels les requêtes sont envoyées.