Guide d'utilisation des ressources

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

• Téléchargement de nouvelles ressources.
• Mise à jour des ressources existantes avec le contrôle de version.
• Mise à jour des métadonnées des ressources, y compris les descriptions, les noms d'affichage, les icônes et les prévisualisations.
• Gérer les versions des ressources, telles que le retour en arrière vers une version précédente spécifiée.
• Vérification des informations existantes d'une contenu, y compris les métadonnées, les versions et toutes les opérations de mise à jour en cours.

Types de ressources et limites pris en charge

Pour les points de fin qui ne créent pas de nouvelle ressource ou n'actualisent pas le contenu des ressources existantes, il n'y a pas de restrictions ni de limites.Cependant, la fonction de téléchargement du contenu des ressources alimentée par les points de fin Créer des ressources et Mettre à jour les ressources ne prend en charge que des types de ressources limités avec des restrictions.Pour chaque appel, vous ne pouvez créer ou mettre à jour qu'un seul ressource avec une taille de fichier de jusqu'à 20 Mo avec les limites suivantes :

Permissions de sécurité

L'API prend en charge à la fois l'utilisation en première partie avec l'autorisation de clé API et l'utilisation tiers dans applications OAuth 2.Chaque manière nécessite des paramètres de permission 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é.Pour gérer les ressources que vous possédez individuellement, créez la clé API sous votre compte.Pour gérer les ressources appartenant au groupe, créez la clé API sous le groupe cible.Pour plus d'informations sur les clés API appartenant au groupe, voir permissions de clé API appartenant au groupe.

Une fois que vous créez une clé API, vous ne pouvez pas changer sa propriété entre des individus ou des groupes, donc si vous créez une clé API sous votre propre compte, vous ne pouvez pas l'utiliser pour gérer les ressources de groupe.

Indépendamment de savoir si vous créez la clé API pour vous-même ou pour votre groupe, assurez-vous d'ajouter les permissions suivantes :

1. Ajoutez ressources à permissions d'accès .
2. Ajoutez Lire et Écrire les permissions d'opération à votre expérience sélectionnée, en fonction des scopes requis des points de fin que vous prévoyez d'appeler.

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

Example API Request Header
--header 'x-api-key: ${ApiKey}' \

Applications d'OAuth 2.0

Pour utiliser l'API pour une application OAuth 2.0 tiers, ajoutez les scopes d'autorisation et lorsque vous enregistrez votre application .Choisissez ces scopes en fonction des exigences des points finaux que vous prévoyez d'utiliser.

Créer une nouvelle contenu

Pour télécharger une nouvelle ressource par une demande HTTP :

1. Copiez la clé API dans l'en-tête de requête x-api-key de l'API Créer une ressource de l'endpoint.

2. Dans votre demande :

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

      • Si vous souhaitez créer la ressource en votre propre nom , ajoutez votre ID utilisateur.Vous pouvez trouver votre ID utilisateur sur 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 la ressource en tant que ressource de groupe , ajoutez l'ID de groupe de votre groupe.Vous pouvez trouver l'ID du groupe sur l'URL de la page de votre groupe.Par exemple, pour https://www.roblox.com/groups/7654321/example-group#!/, l'ID du groupe est 7654321.
   4. Ajoutez le chemin du fichier et le type de contenu de votre ressource.

   Example Request for Create Asset
   curl --location 'https://apis.roblox.com/assets/v1/assets' \
   --header 'x-api-key: ${ApiKey}' \
   --form 'request="{
     \"assetType\": \"Model\",
     \"displayName\": \"Name\",
     \"description\": \"This is a description\",
     \"creationContext\": {
       \"creator\": {
         \"userId\": \"${userId}\" # Utiliser groupId pour créer une contenude groupe
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

Mettre à jour une contenu

Pour mettre à jour une ressource existante par une demande HTTP :

1. Copiez la clé API dans l'en-tête de requête x-api-key de l'endpoint mettre à jour la ressource.
2. Ajoutez le type de ressource et l'ID du ressource dans votre demande. Pour copier votre ID de ressource :

   1. Accédez à la page de création de la création du tableau de bord du créateur .
   2. Sélectionnez la catégorie objets de développement .
   3. Sélectionnez la catégorie de votre ressource et trouvez la contenucible.
   4. Passez la souris sur la vignette de la ressource cible et cliquez sur le bouton ⋯ pour afficher une liste d'options, puis sélectionnez Copier l'ID de la ressource dans la liste.

Example Request for Updating Asset Content
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 des statut

Si votre demande de création d'une nouvelle ressource ou de mise à jour d'une ressource existante réussit, elle renvoie un ID d'opération dans le format de .Vous pouvez l'utiliser pour vérifier le statut et le résultat de votre téléchargement avec les étapes suivantes :

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

   Example Request for Get Operation
   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 qui inclut une response représentant les informations sur les ressources téléchargées ou un status expliquant pourquoi le téléchargement des ressources échoue comme le montre l'exemple de code suivant :

   Example Response for Get Operation
   {
     "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": "Name",
       "description": "This is a description",
       "assetType": "ASSET_TYPE_DECAL",
       "creationContext": {
         "creator": {
           "userId": "11112938575"
         }
       },
       "moderationResult": {
         "moderationState": "MODERATION_STATE_APPROVED"
       }
     }
   }

3. (Facultatif) Vérifiez la ressource créée sur votre compte Roblox.

   1. Accédez à la page Inventaire de votre compte Roblox.
   2. Sélectionnez la catégorie de la ressource que vous voulez vérifier.
   3. Trouvez la ressource cible et cliquez sur sa vignette pour afficher la contenu.

Ajouter l'API des ressources à des applications OAuth 2.0

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

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

1. Lorsque vous enregistrez votre application , sous permissions , sélectionnez lecture de ressources et écriture de ressources scopes.

2. Lorsque vous mettez en œuvre le flux d'autorisation, incluez asset:read et asset:write comme paramètres de portée de l'URL d'autorisation qui redirige les utilisateurs vers votre application, comme l'exemple suivant :

   https://authorize.roblox.com?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 de l'actif à créer ou à mettre à jour dans l' URI de la demande.L'exemple suivant montre une demande d'échantillon pour le téléchargement d'une nouvelle ressource :

   Exemple de demande
   curl --location --request POST 'https://apis.roblox.com/assets/v1/assets' \
   
   --header 'Authorization: Bearer <access_token>' \
   
   --header 'Content-Type: application/json' \
   
   --form 'request="{
   
     \"assetType\": \"Decal\",
   
     \"displayName\": \"DecalDemo123\",
   
     \"description\": \"This is a description\",
   
     \"creationContext\": {
   
       \"creator\": {
   
       \"userId\": \"<user_id>\"
   
       }
     }
   
   }"' \
   
   --form 'fileContent=@"/filepath/p1.png"'