Gebruiksgids voor assets

De Assets API van Open Cloud stelt je in staat om assets te uploaden en bij te werken met een enkele HTTP-aanroep in plaats van ze handmatig naar Studio te importeren. Deze API ondersteunt:

• Het uploaden van nieuwe assets.
• Het bijwerken van bestaande assets met versiebeheer.
• Het bijwerken van assetmetadata, inclusief beschrijvingen, weergavenamen, pictogrammen en previews.
• Het beheren van assetversies, zoals het terugdraaien naar een specifieke vorige versie.
• Het controleren van bestaande informatie van een asset, inclusief metadata, versies en eventuele lopende bijwerkingsoperaties.

Ondersteunde assettypes en limieten

Voor eindpunten die geen nieuwe asset creëren of de inhoud van bestaande assets bijwerken, zijn er geen beperkingen en limieten. De functionaliteit voor het uploaden van assetinhoud, aangedreven door de Create Asset en Update Asset eindpunten, ondersteunt echter alleen beperkte types assets met beperkingen. Voor elke aanroep kun je slechts één asset creëren of bijwerken met een bestandsgrootte tot 20 MB met de volgende limieten:

Beveiligingsmachtigingen

De API ondersteunt zowel gebruik door de eerste partij met API-sleutelautorisatie als gebruik door derden in OAuth 2-toepassingen. Elke manier vereist verschillende instellingen voor beveiligingsmachtigingen.

API-sleutels

Om de API in je eigen scripts of tools te gebruiken, moet je een API-sleutel maken voor autorisatie en beveiliging.

Bij het maken van een API-sleutel, zorg ervoor dat je de volgende machtigingen toevoegt:

1. Voeg assets toe aan Toegangsrechten.
2. Voeg Lezen en Schrijven operationele machtigingen toe aan je geselecteerde game, afhankelijk van de vereiste scopes van de eindpunten die je van plan bent aan te roepen.

Zodra je de API-sleutel hebt, kopieer je deze naar de x-api-key aanvraagheader. Alle eindpunten vereisen de x-api-key aanvraagheader.

--header 'x-api-key: ${ApiKey}' \

OAuth 2.0-apps

Om de API te gebruiken voor een derde partij OAuth 2.0-toepassing, voeg de asset:read en asset:write machtigingsscopes toe bij het registreren van je app. Kies deze scopes op basis van de vereisten van de eindpunten die je van plan bent te gebruiken.

Maak een nieuwe asset

Om een nieuwe asset te uploaden via een HTTP-aanroep:

1. Kopieer de API-sleutel naar de x-api-key aanvraagheader van het Create Asset eindpunt.

2. In je aanvraag:

   1. Geef het doel assettype op.
   2. Voeg je assetnaam en beschrijving toe.
   3. Voeg de informatie van de maker toe.

      • Als je de asset namens jezelf wilt maken, voeg dan je gebruikers-ID toe. Je kunt je gebruikers-ID vinden in de URL van je Roblox-profiel. Bijvoorbeeld, voor https://www.roblox.com/users/1234567/profile, is je gebruikers-ID 1234567.
      • Als je de asset als een groepsasset wilt maken, voeg dan de groeps-ID van je groep toe. Je kunt de groeps-ID vinden in de URL van de pagina van je groep. Bijvoorbeeld, voor https://www.roblox.com/groups/7654321/example-group#!/, is de groeps-ID 7654321.
   4. Voeg het bestandspad en het inhoudstype van je asset toe.

   Voorbeeldaanvraag voor het maken van een asset

   curl --location 'https://apis.roblox.com/assets/v1/assets' \
   --header 'x-api-key: ${ApiKey}' \
   --form 'request="{
     \"assetType\": \"Model\",
     \"displayName\": \"Naam\",
     \"description\": \"Dit is een beschrijving\",
     \"creationContext\": {
       \"creator\": {
         \"userId\": \"${userId}\" # Gebruik groupId voor het maken van een groepsasset
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

Update een bestaande asset

Om een bestaande asset bij te werken via een HTTP-aanroep:

1. Kopieer de API-sleutel naar de x-api-key aanvraagheader van het Update Asset eindpunt.
2. Voeg het assettype en de asset-ID toe in je aanvraag. Om je asset-ID te kopiëren:

   1. Navigeer naar de Creatie pagina van het Creator Dashboard.
   2. Selecteer de categorie Ontwikkelingsitems.
   3. Selecteer de categorie van je asset en vind de doelasset.
   4. Beweeg met de muis over de miniatuur van de doelasset en klik op de ⋯ knop om een lijst met opties weer te geven, selecteer vervolgens Kopieer Asset-ID uit de lijst.

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}"'

Haal de status van de assetoperatie op

Als je aanvraag voor het creëren van een nieuwe asset of het bijwerken van een bestaande asset succesvol is, retourneert deze een Operation ID in het formaat van { "path": "operations/${operationId}" }. Je kunt het gebruiken om de status en het resultaat van je upload te controleren met de volgende stappen:

1. Kopieer de API-sleutel naar de x-api-key aanvraagheader van de Get Operation methode en stuur de aanvraag, zoals het volgende codevoorbeeld laat zien:

   Voorbeeldaanvraag voor het ophalen van de operatie

   curl --location 'https://apis.roblox.com/assets/v1/operations/{operationId}' \
   --header 'x-api-key: {$ApiKey}'

2. Als je aanvraag succesvol is, retourneert deze een Operation object, dat ofwel een response bevat die de informatie van de geüploade asset vertegenwoordigt of een status die uitlegt waarom de assetupload mislukt, zoals het volgende codevoorbeeld laat zien:

   Voorbeeldantwoord voor het ophalen van de operatie

   {
     "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": "Naam",
       "description": "Dit is een beschrijving",
       "assetType": "ASSET_TYPE_DECAL",
       "creationContext": {
         "creator": {
           "userId": "11112938575"
         }
       },
       "moderationResult": {
         "moderationState": "MODERATION_STATE_APPROVED"
       }
     }
   }

3. OPTIONEEL

   Controleer de gemaakte asset op je Roblox-account.

   1. Navigeer naar de Inventaris pagina van je Roblox-account.
   2. Selecteer de Categorie van de asset die je wilt controleren.
   3. Zoek de doelasset en klik op de miniatuur om de asset te bekijken.

Gebruik geüploade assets in Studio

Een asset die je uploadt, behoort tot de gebruiker of groep in de creationContext van je aanvraag, dus het is beschikbaar in Studio zoals elke andere asset die de maker bezit:

• Voeg het toe vanuit de Toolbox of de Asset Manager.
• Modellen worden geüpload als pakketten, dus controleer Inventaris ⟩ Mijn Pakketten in de Toolbox (of Creaties ⟩ Groepspakketten als een groep ze bezit).
• Om een asset in een eigenschap te gebruiken, voer rbxassetid:// in, gevolgd door de assetId uit de operatieantwoord in het Eigenschappen venster. In een script, wijs die string toe aan een stringeigenschap zoals AudioPlayer.Asset, of geef de assetId door aan Content.fromAssetId() voor een eigenschap van het type Content, zoals Decal.ColorMapContent. Voor meer informatie, zie rbxassetid.

Voeg assets API toe aan OAuth 2.0-apps

Je kunt OAuth 2.0-toepassingen maken die de Assets API ondersteunen om je gebruikers in staat te stellen assets naar Roblox te uploaden en bij te werken.

Om de Assets API voor je toepassing te gebruiken en machtigingen van je gebruikers aan te vragen, voer je de volgende instellingen uit:

1. Wanneer je je toepassing registreert, selecteer onder Machtigingen de scopes asset:read en asset:write.

2. Wanneer je de autorisatiestroom implementeert, voeg asset:read en asset:write toe als de scopeparameters van de autorisatie-URL die gebruikers terug naar je toepassing omleidt, zoals het volgende voorbeeld:

   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. Bij het verzenden van de aanvraag, voeg het toegangstoken toe in de autorisatieheader en de formuliergegevens van de assetinhoud die je wilt creëren of bijwerken in de aanvraag-URI. Het volgende voorbeeld toont een voorbeeldaanvraag voor het uploaden van een nieuwe asset:

   Voorbeeldaanvraag

   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\": \"Dit is een beschrijving\", 
   
     \"creationContext\": {
   
       \"creator\": {
   
       \"userId\": \"<user_id>\"
   
       }
   
     }
   
   }"' \
   
   --form 'fileContent=@"/filepath/p1.png"'