Gestion des demandes API pour les magasins de données

Avant d'envoyer des demandes aux API Open Cloud pour les magasins de données standard et les magasins de données commandés, vous devez comprendre comment les gérer correctement.Pour obtenir des informations sur l'utilisation de l'API, voir le guide d'utilisation.

Autorisation

Comme toutes les API Open Cloud, les points d'extrémité du stockage de données nécessitent que toutes les demandes incluent l'en-tête x-api-key, qui contient une clé API avec suffisamment de permissions pour la demande.Cela vous oblige à appliquer la clé à l'expérience et au boutiquede données, et l'opération d'extrémité est autorisée.Si la clé n'est invalide, 403 Unauthorized est retournée.Pour plus d'informations sur les clés API, voir gérer les clés API .

Accélération

Tous les points de fin ont deux types de ralentissement au niveau de l'univers : ralentissement par minute de requête et ralentissement du débit .Avec chaque expérience, la limitation de la demande par minute vous permet d'envoyer un certain nombre de demandes par minute, et la limitation du débit vous permet d'envoyer une certaine quantité de données par minute, indépendamment du nombre de clés API.

Contrairement à l'API Luau, ces limites ne sont pas échelonnées en fonction du nombre d'utilisateurs. Le dépassement de ces limites provoque le retour de l'extrémité 429 Too Many Requests .

Les magasins de données standard fixent les limites de ralentissement

Limites de ralentissement des magasins de données ordonnées

Validation d'entrée

Avant d'envoyer votre demande, assurez-vous de valider les paramètres d'extrémité en fonction des exigences de formatage et des contraintes basées sur le tableau suivant.Les points de fin individuels peuvent avoir des exigences supplémentaires en dehors de ces.Si un paramètre ne satisfait pas les restrictions suivantes, l'extrémité renvoie un 400 Bad Request .

ID de l'univers

L'ID Univers est l'identifiant unique de l'expérience dans laquelle vous souhaitez accéder à vos magasins de données.La valeur de l'ID d'univers d'une expérience est la valeur de son , pas la même que l'ID du lieu de départ d'une expérience, qui identifie le lieu de départ d'une expérience plutôt que l'ensemble de l'expérience.

Vous pouvez obtenir l'ID de l'univers d'une expérience avec les étapes suivantes :

1. Accédez à la tableau de bord du créateur.

2. Trouvez l'expérience avec les magasins de données que vous souhaitez accès.

3. Passez la souris sur la miniaturede l'expérience, cliquez sur le bouton ⋯ et sélectionnez Copier l'ID de l'univers .

   

Portées

Vous pouvez organiser vos magasins de données en définissant une chaîne unique comme scope qui spécifie un sous-dossier pour l'entrée.Une fois que vous avez défini une portée, elle s'ajoute automatiquement à toutes les clés dans toutes les opérations effectuées sur le boutiquede données.Les scopes sont optionnels et par défaut comme global pour les magasins de données standard, mais nécessaires pour les magasins de données commandés.

La portée catégorise vos données avec une chaîne et un séparateur avec "/", comme par exemple :

Toutes les méthodes d'entrée du magasin de données ont un paramètre Scope lorsque vous devez accéder aux entrées stockées sous un scope non par défaut.Par exemple, vous pourriez avoir une clé 1234 sous le scope par défaut global et la même clé sous le scope special.Vous pouvez accéder à l'ancien sans utiliser le paramètre scope, mais pour accéder au dernier, vous devez spécifier le paramètre scope comme special dans Get Entry ou Increment Entry appels API.

En outre, si vous souhaitez énumérer toutes les clés stockées dans un magasin de données qui a une ou plusieurs portées non par défaut, vous pouvez définir le paramètre AllScopes dans la méthode List Entries pour être true, dans lequel le appel renvoie une tuple avec une chaîne de clé et un scope.Dans l'exemple précédent, le List Entries retournerait les deux ( 1234 , global ), et ( 1234 , special ) dans la réponse.

Vous ne pouvez pas passer les paramètres Scope et AllScopes sur la même demande, sinon l'appel renvoie une erreur.En utilisant les fonctions d'aide des API Open Cloud pour le module de stockage de données, le code suivant illustre comment vous pouvez lire chaque clé dans un stockage de données avec une portée personnalisée :

Listez les clés pour différents domaines
# Mettre en place
import tutorialFunctions
DatastoresApi = tutorialFunctions.DataStores()
datastoreName = "PlayerInventory"

# Listez les clés pour la portée globale
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "global", allScopes = False)
print(keys.content)
# Listez les clés pour un domaine spécial
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "special", allScopes = False)
print(keys.content)
# Listez les clés pour tous les paramètres de scope définis sur vrai
specialScopeKeys = DatastoresApi.list_entries(datastoreName, allScopes = True)
print(specialScopeKeys.content)

Les clés avec la portée correspondante sont renvoyées dans la réponse :

Exemples de réponses pour différents domaines
// Réponse pour la portée globale
{ "keys": [{ "scope": "global", "key": "User_2" }], "nextPageCursor": "" }

// Réponse pour un domaine spécial
{"keys":[{"scope":"special","key":"User_6"},{"scope":"special","key":"User_7"}],"nextPageCursor":""}

// Réponse pour AllScopes
{"keys":[{"scope":"global","key":"User_3"},{"scope":"global","key":"User_4"},{"scope":"global","key":"User_5"},{"scope":"special","key":"User_6"},{"scope":"special","key":"User_7"}],"nextPageCursor":""}

Contenus-MD5

Content-MD5 est le somme de contrôle MD5 encodée en base-64 du contenu.C'est une tête de requête facultative pour le point final Set Entry qui vérifie l'intégrité des données et détecte les problèmes potentiels.

Vous pouvez utiliser la langue de votre choix pour calculer la valeur de l'en-tête content-md5.L'exemple suivant utilise Python.Les fonctions hashlib.md5() et base64.b64encode() sont disponibles dans les bibliothèques standard de Python (2.7, 3+).

Génération de contenu-MD5
# Avec des invitations
$ python -c "import base64, hashlib; print('content-md5: ' + str(base64.b64encode(hashlib.md5(bytes(input('content: '), encoding='utf8')).digest()), encoding='utf8'))"
content: 750
content-md5: sTf90fedVsft8zZf6nUg8g==
# Utiliser seulement stdin et stdout
$ echo "750" | python -c "import base64, hashlib; print(str(base64.b64encode(hashlib.md5(bytes(input(), encoding='utf8')).digest()), encoding='utf8'))"
sTf90fedVsft8zZf6nUg8g==

Si vous rencontrez des problèmes générant une valeur valide content-md5 valide, vous devrez peut-être encoder votre corps de requête en binaire UTF-8 avant de calculer le somme de contrôle.

Curseurs

Les points de fin qui renvoient des listes de données peuvent également renvoyer une chaîne nextPageCursor.Cela indique qu'il y a plus de données disponibles dans le jeu de résultats configurer.Pour le recevoir, fournissez cette chaîne dans le paramètre de requête cursor sur une demande suivante.Si le paramètre curseur est fourni mais invalide, l'extrémité de retour renvoie 400 Bad Request .

Le format des chaînes de curseur n'est pas défini . Vous ne devez pas les interpréter ou les analyser car elles peuvent changer à tout moment.

Filtres

Lors de l'envoi de demandes à la méthode List pour les magasins de données commandés, vous pouvez ajouter un paramètre de requête facultatif filter pour retourner des entrées avec des valeurs dans une plage spécifiée.

Le paramètre filter prend en charge un opérateur logique, && , et deux opérateurs de comparaison, <= pour définir la valeur maximale et >= pour définir la valeur minimale.Si vous souhaitez définir une plage avec une valeur maximale et minimale, ajoutez && entre les deux séquences.

Par exemple, pour retourner des entrées avec des valeurs inférieures ou égales à 10, vous devez saisir entry <= 10 comme valeur filter.Pour retourner des entrées avec des valeurs entre 10 et 50, entrez entry <= 50 && entry >= 10 .

Les exemples suivants sont des valeurs incorrectes filter qui peuvent échouer vos demandes :

• entry <= 10 - pas d'espace blanc entre chaque partie de la séquence.
• 10 <= entry - entry et la valeur de comparaison est du mauvais côté.
• entry <= 10 && entry <= 50 - && ne peut être utilisé que pour spécifier une plage avec les deux opérateurs de comparaison pour la valeur minimale et maximale.

Autoriser les drapeaux manquants

Lors de l'envoi de demandes à la méthode Update pour mettre à jour une entrée de données commandée existante, vous pouvez ajouter un drapeau allow_missing facultatif pour permettre la création d'une entrée même si l'entrée n'existe pas.

Lorsque vous définissez le drapeau allow_missing à True :

• Si l'entrée n'existe pas, la réponse renvoie une nouvelle entrée.

• Si l'entrée existe mais que le contenu correspond à la valeur existante de l'entrée, l'entrée existante reste inchangée.

• Si l'entrée existe et que le contenu ne correspond pas à la valeur existante de l'entrée, la réponse renvoie l'entrée avec la nouvelle valeur de contenu mise à jour.