Motifs

Cette page couvre les modèles communs avec les API du cloud ouvert, notamment autour de la formulation de demandes et du traitement des réponses.

Cheminements

Pour faire une demande aux API du cloud ouvert, 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 Open Cloud API (par exemple, /universes/{universe_id}/places/{place_id}/user-restrictions), et de tous les paramètres de requête (par exemple, ?maxPageSize=25).Une URL de demande complète pourrait ressembler à ceci :


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 courbes 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 identifiants : les identifiants d'utilisateur, les identifiants de groupe, les identifiants de lieu, etc.Les identifiants sont souvent numériques, mais pas nécessairement ; par exemple, les identifiants de stockage de données et de stockage de mémoire supportent un configurerde caractères plus large.

Certaines ressources ont plusieurs modèles de chemin visible sous l'en-tête chemins de ressources dans la référence de l'API.Par exemple, l'URL pour restreindre les utilisateurs de la liste peut être l'une 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 endroits spécifiques dans un univers.En dehors de l'ajout mineur au chemin et du paramètre de chemin supplémentaire, les appels sont identiques.

De nombreuses API renvoient un chemin comme partie de leur réponse, que vous pouvez utiliser pour faire d'autres demandes.Si une API a besoin de plus de quelques secondes pour remplir une demande, elle renvoie souvent une opération plutôt que la ressource ou la réponse elle-même.

Longueur et taperdu contenu

De nombreuses appels d'API, notamment ceux qui créent ou mettent à jour des ressources, nécessitent un corps de requête 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.

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


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

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


GET /cloud/v2/universes/{universe_id}/data-stores?maxPageSize=25

{
  "dataStores": [
    ...
  ],
  "nextPageToken": "datastore1"
}

Si une réponse inclut une valeur pour nextPageToken , utilisez cette valeur dans le paramètre pageToken de la requête suivante pour récupérer la page suivante.Lorsque nextPageToken est vide ou entièrement omis, vous avez atteint la fin de vos résultats :


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

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


GET /cloud/v2/universes/{universe_id}/data-stores?maxPageSize=25&pageToken=datastore1

{
  "dataStores": [
    ...
  ]
}

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

Opérations de longue exécution

Certains méthodes retournent un objet Operation qui représente une demande de longue durée qui renvoie une réponse asynchrone plus tard.L'objet contient les champs suivants :

chemin - Le chemin d'extrémité à appeler pour demander la fin de la requête. Ajoutez le chemin à l'URL de base originale de la méthode de ressource.
terminé - Une valeur booléenne qui représente si l'opération est terminée ou non.
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 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 lorsque la ressource est prête.Une bonne stratégie consiste à utiliser un recul exponentiel.Par exemple, vous pouvez voter immédiatement, puis après une seconde, deux secondes, quatre secondes, etc.


def PollForResults(operationPath):
    currentRetries = 0
    maxRetries = 10
    retryPollingDelay = 1
    retryPollingMultiplier = 2
    while (currentRetries < maxRetries):
        # Pas de retard sur 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)
            # Décalage exponentiel
            retryPollingDelay *= retryPollingMultiplier
        # Vérifier les résultats et revenir s'ils existent
        if (results.status_code != 200 or results.json()[doneJSONKey]):
            return results
        # Sinon, augmentez le nombre de rechargement
        else:
           currentRetries += 1

Pour un échantillon de code plus complet qui utilise une période de réessai fixe plutôt qu'un retour progressif exponentiel, voir Poll for results.

Filtrage

Certains méthodes vous permettent de filtrer la réponse en incluant un paramètre filter dans la demande.Les sections suivantes décrivent la syntaxe de filtre et les directives pour les points finaux spécifiés.

Liste des adhésions de groupe

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

Le filtrage se conforme au langage d'expression commun (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 adhésions par utilisateur ou rôle dans les formats suivants :

Filtrage 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 du groupe, vous devez filtrer les adhésions par utilisateur (jusqu'à 50) dans le format suivant :

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

Liste des articles d'inventaire

Vous pouvez filtrer par statut de collection, taperd'article d'inventaire et ID d'article d'inventaire.Si vous ne fournissez pas de filtres, l'ensemble de l'inventaire de l'utilisateur est retourné.

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

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

{field} peut être l'un des champs de type prédéfinis ou des champs d'ID des tables suivantes.
{value} peut être une chaîne, un booléen ou un ensemble.Selon le taperde champ, cela peut être une valeur unique (champs booléens) ou plusieurs valeurs (champs de liste).

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

Champs de type

| Filtrer | Type | Description | | :------------------------ | :------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | badges | boolean | Inclure des badges dans la réponseLa valeur par défaut est fausse. | | gamePasses | boolean | Inclure des passes de jeu dans la réponse.La valeur par défaut est fausse. | | inventoryItemAssetTypes | Voir détails des ressources pour la liste complète des types de ressources.| Liste séparée par des virgules des types de ressources à inclure.La valeur par défaut est aucune.Spécifiez * pour tous les types de ressources.Doit avoir une portée de lecture d'inventaire pour filtrer par les endroits achetés. | | onlyCollectibles | boolean | Inclure seulement des collectibles dans la réponse.La valeur par défaut est fausse.Ce champ doit être utilisé avec le champ inventoryItemAssetTypes pour retourner des articles et ne retourne que des articles limités non UGC.| | privateServers | boolean | Inclure des serveurs privés dans la réponse.La valeur par défaut est fausse.Doit avoir une portée de lecture d'inventaire pour filtrer par ce champ. |

Champs d'ID

Exemples

Renvoie tous les objets de collection 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 articles des types listés ou tout autre passe 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 des 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