Guide d'utilisation des actifs

L'API des actifs de Open Cloud permet de télécharger et de mettre à jour des actifs avec une seule requête HTTP plutôt que de les importer manuellement dans Studio. Cette API prend en charge :

• Le téléchargement de nouveaux actifs.
• La mise à jour d'actifs existants avec le contrôle de version.
• La mise à jour des métadonnées des actifs, y compris les descriptions, les noms d'affichage, les icônes et les aperçus.
• La gestion des versions des actifs, comme le retour à une version précédente spécifiée.
• La vérification des informations existantes d'un actif, y compris les métadonnées, les versions et toute opération de mise à jour en cours.

Types d'actifs pris en charge et limites

Pour les points de terminaison qui ne créent pas un nouvel actif ou ne mettent pas à jour le contenu des actifs existants, il n'y a aucune restriction ni limite. Cependant, la fonctionnalité de téléchargement de contenu actif, alimentée par les points de terminaison Créer un actif et Mettre à jour un actif, ne prend en charge que des types d'actifs limités avec des restrictions. Pour chaque appel, vous ne pouvez créer ou mettre à jour qu'un seul actif avec une taille de fichier allant jusqu'à 20 Mo avec les limites suivantes :

Permissions de sécurité

L'API prend en charge à la fois l'utilisation interne avec l'autorisation par clé API et l'utilisation tierce dans des applications OAuth 2. Chaque méthode nécessite des paramètres de permissions de sécurité différents.

Clés API

Pour utiliser l'API dans vos propres scripts ou outils, vous devez créer une clé API pour l'autorisation et la sécurité.

Lors de la création d'une clé API, assurez-vous d'ajouter les permissions suivantes :

1. Ajoutez assets aux Permissions d'accès.
2. Ajoutez les permissions d'opération Lecture et Écriture à votre jeu sélectionné, en fonction des portées requises des points de terminaison que vous prévoyez d'appeler.

Une fois que vous avez la clé API, copiez-la dans l'en-tête de requête x-api-key. Tous les points de terminaison nécessitent l'en-tête de requête x-api-key.

Exemple d'en-tête de requête API
--header 'x-api-key: ${ApiKey}' \

Applications OAuth 2.0

Pour utiliser l'API pour une application tierce OAuth 2.0, ajoutez les permissions asset:read et asset:write lors de l'enregistrement de votre application. Choisissez ces portées en fonction des exigences des points de terminaison que vous prévoyez d'utiliser.

Créer un nouvel actif

Pour télécharger un nouvel actif par une requête HTTP :

1. Copiez la clé API dans l'en-tête de requête x-api-key du point de terminaison Créer un actif.

2. Dans votre requête :

   1. Spécifiez le type d'actif cible.
   2. Ajoutez le nom et la description de votre actif.
   3. Ajoutez les informations sur le créateur.

      • Si vous souhaitez créer l'actif en votre propre nom, ajoutez votre ID utilisateur. Vous pouvez trouver votre ID utilisateur dans l'URL de votre profil Roblox. Par exemple, pour https://www.roblox.com/users/1234567/profile,, votre ID utilisateur est 1234567`.
      • Si vous souhaitez créer l'actif en tant qu'actif de groupe, ajoutez l'ID de groupe de votre groupe. Vous pouvez trouver l'ID de groupe dans l'URL de la page de votre groupe. Par exemple, pour https://www.roblox.com/groups/7654321/example-group#!/,, l'ID de groupe est 7654321`.
   4. Ajoutez le chemin du fichier et le type de contenu de votre actif.

   Exemple de requête pour créer un actif
   curl --location 'https://apis.roblox.com/assets/v1/assets' \
   --header 'x-api-key: ${ApiKey}' \
   --form 'request="{
     \"assetType\": \"Model\",
     \"displayName\": \"Nom\",
     \"description\": \"Ceci est une description\",
     \"creationContext\": {
       \"creator\": {
         \"userId\": \"${userId}\" # Utiliser groupId pour créer un actif de groupe
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

Mettre à jour un actif existant

Pour mettre à jour un actif existant par une requête HTTP :

1. Copiez la clé API dans l'en-tête de requête x-api-key du point de terminaison Mettre à jour un actif.
2. Ajoutez le type d'actif et l'ID de l'actif dans votre requête. Pour copier votre ID d'actif :

   1. Accédez à la page Création du Tableau de bord Créateur.
   2. Sélectionnez la catégorie des Éléments de développement.
   3. Sélectionnez la catégorie de votre actif et trouvez l'actif cible.
   4. Survolez la vignette de l'actif cible et cliquez sur le bouton ⋯ pour afficher une liste d'options, puis sélectionnez Copier l'ID de l'actif dans la liste.

Exemple de requête pour mettre à jour le contenu de l'actif
curl --location --request PATCH 'https://apis.roblox.com/assets/v1/assets/{assetId}' \
--header 'x-api-key: {apiKey}' \
--form 'request={
    \"assetType\": \"{assetType}\",
    \"assetId\": \"{assetId}\",
    \"creationContext\": {
        \"creator\": {
            \"userId\": {userId}
        },
        \"expectedPrice\":{expectedPrice}
    },
}' \
--form 'fileContent=@"{file-path}"'

Récupérer l'état de l'opération d'actif

Si votre demande de création d'un nouvel actif ou de mise à jour d'un actif existant réussit, elle renvoie un ID d'opération au format { "path": "operations/${operationId}" }. Vous pouvez l'utiliser pour vérifier l'état et le résultat de votre téléchargement avec les étapes suivantes :

1. Copiez la clé API dans l'en-tête de requête x-api-key de la méthode Obtenir l'opération et envoyez la demande, comme l'exemple de code suivant :

   Exemple de requête pour obtenir l'opération
   curl --location 'https://apis.roblox.com/assets/v1/operations/{operationId}' \
   --header 'x-api-key: {$ApiKey}'

2. Si votre demande réussit, elle renvoie un objet Operation, incluant soit une response représentant les informations de l'actif téléchargé, soit un status expliquant pourquoi le téléchargement de l'actif échoue, comme le montre l'exemple de code suivant :

   Exemple de réponse pour obtenir l'opération
   {
     "path": "operations/{operationId}",
     "done": true,
     "response": {
       "@type": "type.googleapis.com/roblox.open_cloud.assets.v1.Asset",
       "path": "assets/2205400862",
       "revisionId": "1",
       "revisionCreateTime": "2023-03-02T22:27:04.062164400Z",
       "assetId": "2205400862",
       "displayName": "Nom",
       "description": "Ceci est une description",
       "assetType": "ASSET_TYPE_DECAL",
       "creationContext": {
         "creator": {
           "userId": "11112938575"
         }
       },
       "moderationResult": {
         "moderationState": "MODERATION_STATE_APPROVED"
       }
     }
   }

3. (Facultatif) Vérifiez l'actif créé sur votre compte Roblox.

   1. Accédez à la page Inventaire de votre compte Roblox.
   2. Sélectionnez la Catégorie de l'actif que vous souhaitez vérifier.
   3. Trouvez l'actif cible et cliquez sur sa vignette pour voir l'actif.

Ajouter l'API des actifs aux applications OAuth 2.0

Vous pouvez créer des applications OAuth 2.0 prenant en charge l'API des actifs pour permettre à vos utilisateurs de télécharger et de mettre à jour des actifs sur Roblox.

Pour utiliser l'API des actifs pour votre application et demander des permissions à vos utilisateurs, effectuez les paramètres suivants :

1. Lors de l'enregistrement de votre application, sous Permissions, sélectionnez les portées asset:read et asset:write.

2. Lors de l'implémentation du flux d'autorisation, incluez asset:read et asset:write en tant que paramètres de portée de l'URL d'autorisation qui redirige les utilisateurs vers votre application, comme l'exemple suivant :

   https://apis.roblox.com/oauth/v1/authorize?client_id=819547628404595165403873012&redirect_uri=https://my-app.com/redirect&scope=asset:read+asset:write&response_type=Code&prompts=login+consent&nonce=12345&state=6789

3. Lors de l'envoi de la demande, incluez le jeton d'accès dans l'en-tête d'autorisation et les données de formulaire du contenu d'actif à créer ou mettre à jour dans l'URI de la requête. L'exemple suivant montre un échantillon de demande pour télécharger un nouvel actif :

   Exemple de requête
   curl --location --request POST 'https://apis.roblox.com/assets/v1/assets' \
   
   --header 'Authorization: Bearer <access_token>' \
   
   --header 'Content-Type: application/json' \
   
   --form 'request="{
   
     \"assetType\": \"Décalque\", 
   
     \"displayName\": \"DémoDécalque123\", 
   
     \"description\": \"Ceci est une description\", 
   
     \"creationContext\": { 
   
       \"creator\": { 
   
       \"userId\": \"<user_id>\"
   
       } 
     }
   
   }"' \
   
   --form 'fileContent=@"/filepath/p1.png"'