Modèles

Cette page couvre les modèles courants avec les API Open Cloud, en particulier en ce qui concerne les demandes et le traitement des réponses.

Chemins

Pour faire une demande aux API Open Cloud, vous devez d'abord former une URL. Cette URL est une combinaison de l'URL de base (par exemple, https://apis.roblox.com), le chemin de l'API Open Cloud (par exemple, /cloud/v2/universes/{universe_id}/places/{place_id}/user-restrictions), et tous les paramètres de requête (par exemple, ?maxPageSize=25). Une URL de requête 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 accolades dans la référence API. Les paramètres de chemin ne sont que des variables que vous insérez avant de faire la demande et sont presque toujours des identifiants : identifiants d'utilisateur, identifiants de groupe, 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 ensemble de caractères plus large.

Longueur et type de contenu

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

Pagination

Si vous spécifiez maxPageSize dans votre requête, certaines méthodes renvoient 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 demande suivante pour récupérer la page suivante. Lorsque nextPageToken est vide ou complètement 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": [
    ...
  ]
}

À part le pageToken, vous devez utiliser la même requête pour que la pagination fonctionne correctement. Modifier un paramètre de filtre entraîne une erreur 400.

Open Cloud v2

Plusieurs chemins

Certaines ressources ont plusieurs modèles de chemin, visibles sous l'en-tête Chemins de Ressources dans la référence API. Par exemple, l'URL pour Lister les Restrictions d'Utilisateurs peut être l'une des suivantes :

• 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'utilisateurs s'appliquent à un univers entier (jeu), tandis que d'autres s'appliquent à des lieux spécifiques au sein d'un univers. Mis à part le petit ajout au chemin et le paramètre de chemin supplémentaire, les appels sont identiques.

De nombreux points d'extrémité renvoient un chemin comme partie de leur réponse, que vous pouvez utiliser pour faire d'autres requêtes. Si une API nécessite plus de quelques secondes pour traiter une requête, elle retourne souvent une opération plutôt que la ressource ou la réponse elle-même.

Opérations de longue durée

Certaines méthodes renvoient un objet Operation qui représente une requête de longue durée qui renvoie une réponse asynchrone plus tard. L'objet contient les champs suivants :

• path - Le chemin du point de terminaison à appeler pour interroger l'achèvement de la requête. Ajoutez le chemin à l'URL de base d'origine de la méthode de ressource.
• done - Une valeur booléenne qui représente si l'opération est terminée ou non.
• response - L'objet de réponse. Ce champ est vide jusqu'à ce que le champ done ait une valeur de true.
• metadata - Métadonnées personnalisées spécifiques à la requête en cours.

Exemple d'objet Operation
{
  "path": "v1/assets/12345/operation/xyz",
  "done": true,
  "response": {
    "value1": "maValeur",
    "value2": 1234
  },
  "metadata": {
    "metadata1": "chaîne",
    "metadata2": 5678
  }
}

Utilisez le chemin de l'objet Operation pour interroger le moment où la ressource est prête. Une bonne stratégie consiste à utiliser le "backoff exponentiel". Par exemple, vous pourriez interroger 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 délai lors du premier contrôle
        if (currentRetries == 0):
            results = GetOperation(operationPath)
        # Logique de répétition pour les checks suivants
        else:
            time.sleep(retryPollingDelay)
            results = GetOperation(operationPath)
            # Backoff exponentiel
            retryPollingDelay *= retryPollingMultiplier
        # Vérifiez les résultats et retournez s'ils existent
        if (results.status_code != 200 or results.json()[doneJSONKey]):
            return results
        # Sinon, incrémentez le compteur de reprise
        else:
           currentRetries += 1

Pour un exemple de code plus complet qui utilise un intervalle de nouvelle tentative fixe plutôt qu'un backoff exponentiel, voir Poll for results.

Filtrage

Certaines méthodes vous permettent de filtrer la réponse en incluant un paramètre filter dans la requête. Les sections suivantes décrivent la syntaxe de filtrage et les directives pour les points de terminaison spécifiés.

Lister les adhésions de groupe

Le caractère générique - peut être utilisé à la place de l'identifiant de groupe afin de lister les adhésions à tous les groupes : groups/-/memberships.

Le filtrage est conforme au Common Expression Language (CEL). Seules deux opérateurs sont supportés :

• ==
• in [...]

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

• Filtre Utilisateur : filter=user == 'users/9876543210'
• Filtre Rôle : filter=role == 'groups/123/roles/7920705'

Si vous spécifiez le caractère générique pour l'identifiant de groupe, vous devez filtrer les adhésions par utilisateur (jusqu'à 50) dans le format suivant :

• Filtre Utilisateur : filter=user in ['users/1', 'users/156', 'users/9876543210', ...]

Lister les éléments d'inventaire

Vous pouvez filtrer par statut de collection, type d'élément d'inventaire, et identifiant d'élément d'inventaire. Si vous ne fournissez pas de filtre, l'ensemble de l'inventaire de l'utilisateur est renvoyé.

Le format de filtre est une liste séparée par des points-virgules :

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

• {field} peut être l'un des champs de type prédéfinis ou des champs d'identifiant dans les tableaux suivants.
• {value} peut être une chaîne, un booléen ou un énum. Selon le type de champ, cela peut être une seule valeur (champs booléens) ou plusieurs valeurs (champs de liste).

Champs de type

Champs d'identifiant

Exemples

• Renvoie tous les éléments collectables 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 tout passe de jeu. Exclut les badges des résultats (le même comportement que si badges n'était pas inclus dans le filtre) :

  filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY;gamePasses=true;badges=false

• Renvoie des actifs qui correspondent aux identifiants spécifiés :

  filter=assetIds=1,2,3,4

• Renvoie des actifs, badges, passes de jeu, et serveurs privés qui correspondent aux identifiants spécifiés :

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