Guide d'utilisation pour les ressources

La API des ressources de l'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 la version.
• Mise à jour des métadonnées des ressources, y compris les décrire, les noms d'affichage, les icônes et les aperçus.
• Gérer les versions des ressources, telles que le retour à une version spécifiée auparavant.
• Vérification de l'information existante d'une contenu, y compris les métadonnées, les versions et toutes les opérations de mise à jour en cours.

Type de ressources et limites pris en charge

Pour les points d'extrémité qui ne créent pas de nouvelles ressources ou ne mettent pas à jour le contenu des ressources existantes, il n'y a pas de restrictions et de limites. Cependant, la fonctionnalité de mise à jour du contenu des ressources par le biais de l'écraser la ressource et télécharger la ressource points ne prend en charge que les types d'actifs limités avec des restrictions. Pour chaque appel, vous ne pouvez créer ou mettre

Permissions de sécurité

L'API prend en charge à la fois l'utilisation première partie avec l'autorisation de clé API et l'utilisation tiers dans applications OAuth 2. Chaque mode 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 à un groupe, créez la clé API sous le groupe cible. Pour plus d'informations sur les clés API appartenant à un groupe, voir autorisations de groupe de ressources.

Une fois que vous avez créé 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.

Que vous créiez la clé API pour vous-même ou pour votre groupe, assurez-vous d'ajouter les permissions suivantes :

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

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

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

OAuth 2.0 Applis

Pour utiliser l'API pour une application tierce OAuth 2.0, ajoutez les asset:read et asset:write permissions de scope lorsque vous enregistrez votre application. Choisissez ces scopes en fonction des exigences des endpoints que vous prévoyez utiliser.

Créer une nouvelle ressource

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

1. Copiez la clé API dans la x-api-key requête du en-tête de la Créer une ressource 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 voulez créer la ressource au nom de votre propre personne , 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 voulez créer la ressource comme une ressource de groupe , ajoutez l'ID de groupe de votre groupe. Vous pouvez trouver l'ID de groupe sur l'URL de la page de votre groupe. Par exemple, pour https://www.roblox.com/groups/7654321/example-group#!/ , le groupe ID est 7654321 .
   4. Ajoutez le chemin de dossier 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}\" # Utilisez groupId pour créer une contenude groupe
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

Mise à jour d'une ressource existante

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

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

   1. Accédez à la page 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. Survolez 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ération du statut de l'opération de la ressource

Si votre demande de création d'une nouvelle ressource ou de mise à jour d'une ressource existante réussit, il renvoie un ID d'opération dans le format { "path": "operations/${operationId}" } . 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é API dans la x-api-key requête du en-tête de la méthode Get Operation et envoyez la demande, comme le 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, il renvoie un objet Operation, y compris un response représentant les informations de l'actif téléchargé ou un status expliquant pourquoi le téléchargement de l'actif échoue comme le montre le code d'exemple 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 des ressources API à des applications OAuth 2.0

Vous pouvez créer des applications OAuth 2.0 qui supportent 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 l'objet de lecture et l'objet d'écriture.

2. Lors de l'implémentation du flux d'autorisation, incluez contenu:read et asset:read comme paramètres de scope de l'URL d'autorisation qui redirige les utilisateurs dans votre application, comme l'exemple suivant :

   https://www.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 le champ d'autorisation et les données de forme du contenu de l'actif pour créer ou mettre à jour dans la demande URL dans. L'exemple suivant montre un exemple de demande pour télécharger un nouveau contenu :

   Demande d'exemple
   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"'