Motifs

Cette page couvre les modèles communs avec les API Open Cloud, en particulier autour de la création de demandes et du traitement des réponses.

Chemins

Pour faire une demande aux API du cloud, vous devez d'abord former une URL. Cette URL est une combinaison de l'URL de base ( https://apis.roblox.com/cloud/v2), du chemin de l'API du cloud (par exemple, /universes/{universe-id}/places/{place-id}/user-restrictions et de tous les param


https://apis.roblox.com/cloud/v2/users/4687549151/inventory-items?maxPageSize=100

De nombreux chemins, y compris l'exemple ci-dessus, ont des paramètres de chemin , désignés par des crochets curly dans la référence de l'API. Les paramètres de chemin sont simplement des variables que vous insérez avant de faire la demande et sont presque toujours des ID : les ID de l'utilisateur, les groupes ID, les lieux ID, etc. Les ID sont souvent des numéros, mais pas nécessairement ; par exemple, les données de stockage et les mémoires stockent des configurerde caract

Certaines ressources ont plusieurs modèles de chemin, visibles sous l'en-tête ressources chemin dans la référence API. Par exemple, l'URL pour List User Restrictions peut être l'un des suivre:

https://apis.roblox.com/cloud/cloud/v2/universes/{universe-id}/user-restrictions
https://apis.roblox.com/cloud/cloud/v2/universes/{universe-id}/places/{place-id}/user-restrictions

Vous pouvez probablement inférer la différence entre les deux : certaines restrictions d'utilisateur s'appliquent à un univers entier (expérience), tandis que d'autres s'appliquent à des lieux spécifiques dans un univers. En dehors de la petite ajout à la valeur de chemin et de la valeur de chemin supplémentaire, les appels sont identiques.

Beaucoup d'API restituent un chemin comme partie de leur réponse, ce que vous pouvez utiliser pour faire d'autres demandes. Si une API a besoin de plus de quelques secondes pour exécuter une demande, elle renvoie généralement une opération opération plutôt que la ressource ou la réponse elle-même.

Longueur et type du contenu

De nombreux appels d'API, en particulier ceux qui créent ou mettent à jour des ressources, nécessitent un corps de demande JSON. Si votre demande a un corps, assurez-vous d'inclure les en-têtes Content-Length et Content-Type. La plupart des clients HTTP ajoutent automatiquement ces en-têtes.

Pagination

Si vous spécifiez maxPageSize dans votre demande, certains méthodes retournent des résultats paginés : c'est essentiellement des réponses partielles.


GET /cloud/v2/users/{userId}/inventory-items?maxPageSize=25

{
  "inventoryItems": [
    ...
  ],
  "nextPageToken": "aaaBBB"
}

Si une réponse inclut une valeur pour nextPageToken , utilisez cette valeur dans le pageToken paramètre de la demande suivante pour récupérer la prochaine page. Lorsque nextPageToken est vide, vous avez atteint la fin de vos résultats :


GET /cloud/v2/users/{userId}/inventory-items?maxPageSize=25&pageToken=aaaBBB

{
  "inventoryItems": [
    ...
  ],
  "nextPageToken": ""
}

En dehors de la pageToken , vous devez utiliser la même requête pour que la pagination fonctionne correctement. Modifier n'importe quel paramètre de filtre entraîne une erreur 400.

Opérations de longue durée

Certains méthodes retournent un objet Operation qui représente une demande en cours d'exécution qui retourne une réponse asynchrone plus tard. L'objet contient les champs suivants :

chemin - Le chemin de l'extrémité à appeler pour le chargement de la demande. Ajoutez le chemin à l'URL de base originale de la méthode de ressource.
terminé - une valeur booléenne qui représente si oui ou non l'opération a été terminée.
réponse - l'objet de réponse. Ce champ est vide jusqu'à ce que le champ done ait une valeur de true.
métadonnées - Métadonnées personnalisées spécifiques à la demande qui est faite.

Objet d'opération d'exemple
{
  "path": "v1/assets/12345/operation/xyz",
  "done": true,
  "response": {
    "value1": "myValue",
    "value2": 1234
  },
  "metadata": {
    "metadata1": "string",
    "metadata2": 5678
  }
}

Utilisez le chemin de l'objet Operation pour voter pour quand la ressource est prête. Une bonne stratégie est d'utiliser l'expérience de régression. Par exemple, vous pourriez voter immédiatement, puis après un seul second, deux secondes, quatre secondes, etc.


def PollForResults(operationPath):
    currentRetries = 0
    maxRetries = 10
    retryPollingDelay = 1
    retryPollingMultiplier = 2
    while (currentRetries < maxRetries):
        # Pas de délai pour le premier vérifier
        if (currentRetries == 0):
            results = GetOperation(operationPath)
        # Réessayer la logique pour les vérifications suivantes
        else:
            time.sleep(retryPollingDelay)
            results = GetOperation(operationPath)
            # Revenir exponentiel
            retryPollingDelay *= retryPollingMultiplier
        # Vérifier les résultats et revenir s'ils existent
        if (results.status_code != 200 or results.json()[doneJSONKey]):
            return results
        # Autrement, augmenter le nombre de tentatives
        else:
           currentRetries += 1

Pour un échantillon de code plus complet qui utilise uneIntervalle de réessayer fixe plutôt que l'exposition exponentielle, voir Polling for Results.

Filtrage

Certains méthodes vous permettent de filtrer la réponse en incluant un filter paramètre dans la demande. Les sections suivantes décrivent laSyntaxe de filtre et les lignes directrices pour les points d'extrémité spécifiés.

Liste des membres du groupe

Le caractère joker - peut être utilisé à la place de l'ID de groupe pour lister les membres dans tous les groupes : groups/-/memberships.

La filtration respecte la langue de description commune (CEL). Seuls deux opérateurs sont pris en charge :

==
in [...]

Si vous spécifiez un ID de groupe dans le chemin de ressource, vous pouvez filtrer les membres par utilisateur ou rôle dans les formats suivants :

Filtre d'utilisateur : filter="user == 'users/9876543210'"
Filtre de rôle : filter="role == 'groups/123/roles/7920705'"

Si vous spécifiez le caractère joker pour l'ID de groupe, vous devez filtrer les membres par utilisateur (jusqu'à 50) dans le format suivant :

Filtrer l'utilisateur : filter="user in ['users/1', 'users/156', 'users/9876543210', ...]"

Rechercher des objets dans l'inventaire

Vous pouvez filtrer par statut de collection, taperd'article d'inventaire et ID de l'article d'inventaire. Si vous n'êtes pas fournisseur de filtres, l'inventaire de l'utilisateur est entièrement renvoyé.

Le format de filtre est une liste séparée par un semicolon :

filter={field}={value};{field}={value},{value},...;{field}=...

{field} peut être l'un des champs de type ou des champs d'identifiant prédéfinis dans les tableaux suivants.
{value} peut être une chaîne, un bouton ou un ensemble. Selon le taperde champ, cela peut être une valeur unique (champs de bouton) ou plusieurs valeurs (listes de champs).

Vous ne pouvez pas combiner les champs de type et d'identifiant dans le même filtres.

Renvoie tous les éléments collectibles que l'utilisateur possède :

filter=onlyCollectibles=true;inventoryItemAssetTypes=*
Renvoie tous les éléments des types spécifiés :

filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY
Renvoie tous les éléments des types listés ou des passes de jeu. Exclut les badges des résultats (le même comportement que si badges n'était pas inclus dans le filtres) :

filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY;gamePasses=true;badges=false
Renvoie les ressources qui correspondent aux ID spécifiés :

filter=assetIds=1,2,3,4
Renvoie des ressources, des badges, des passes de jeu et des serveurs privés qui correspondent aux ID spécifiés :

filter=assetIds=1,2,3,4;badgeIds=1,2,3,4;gamePassIds=1,2,3,4;privateServerIds=1,2,3,4

Chemins

Longueur et type du contenu

Opérations de longue durée

Filtrage

Liste des membres du groupe

Rechercher des objets dans l'inventaire

Type Fields

Champs d'identifie

Exemples