Guida all'uso degli asset

L'API degli Asset di Open Cloud consente di caricare e aggiornare asset con una singola richiesta HTTP anziché importarli manualmente in Studio. Questa API supporta:

• Caricamento di nuovi asset.
• Aggiornamento di asset esistenti con controllo di versione.
• Aggiornamento dei metadati degli asset, inclusi descrizioni, nomi visualizzati, icone e anteprime.
• Gestione delle versioni degli asset, come il ripristino a una versione precedente specificata.
• Controllo delle informazioni esistenti su un asset, inclusi metadati, versioni e eventuali operazioni di aggiornamento in corso.

Tipi di asset supportati e limiti

Per gli endpoint che non creano un nuovo asset o aggiornano il contenuto di asset esistenti, non ci sono restrizioni e limiti. Tuttavia, la funzionalità di caricamento dei contenuti degli asset, alimentata dagli endpoint Crea Asset e Aggiorna Asset, supporta solo tipi di asset limitati con restrizioni. Per ciascuna chiamata, puoi creare o aggiornare solo un asset con una dimensione del file fino a 20 MB con i seguenti limiti:

Permessi di sicurezza

L'API supporta sia l'uso di prima parte con autenticazione tramite chiave API sia l'uso di terza parte nelle applicazioni OAuth 2. Ogni metodo richiede diverse impostazioni di autorizzazione di sicurezza.

Chiavi API

Per utilizzare l'API nei tuoi script o strumenti, devi creare una chiave API per l'autenticazione e la sicurezza.

Quando crei una chiave API, assicurati di aggiungere i seguenti permessi:

1. Aggiungi assets a Permessi di accesso.
2. Aggiungi permessi per le operazioni Read e Write al tuo gioco selezionato, a seconda degli ambiti richiesti dagli endpoint che intendi chiamare.

Una volta che hai la chiave API, copiala nell'intestazione della richiesta x-api-key. Tutti gli endpoint richiedono l'intestazione di richiesta x-api-key.

Esempio di intestazione della richiesta API
--header 'x-api-key: ${ApiKey}' \

App OAuth 2.0

Per utilizzare l'API per un'applicazione OAuth 2.0 di terze parti, aggiungi gli ambiti di permesso asset:read e asset:write quando registri la tua app. Scegli questi ambiti in base ai requisiti degli endpoint che intendi utilizzare.

Crea un nuovo asset

Per caricare un nuovo asset tramite una richiesta HTTP:

1. Copia la chiave API nell'intestazione della richiesta x-api-key dell'endpoint Crea Asset.

2. Nella tua richiesta:

   1. Specifica il tipo di asset target.
   2. Aggiungi il nome e la descrizione del tuo asset.
   3. Aggiungi le informazioni sul creatore.

      • Se desideri creare l'asset a tuo nome, aggiungi il tuo ID utente. Puoi trovare il tuo ID utente nell'URL del tuo profilo Roblox. Ad esempio, per https://www.roblox.com/users/1234567/profile,il tuo ID utente è1234567`.
      • Se desideri creare l'asset come asset di gruppo, aggiungi l'ID del tuo gruppo. Puoi trovare l'ID del gruppo nell'URL della pagina del tuo gruppo. Ad esempio, per https://www.roblox.com/groups/7654321/example-group#!/,l'ID del gruppo è7654321`.
   4. Aggiungi il percorso del file e il tipo di contenuto del tuo asset.

   Esempio di richiesta per creare un asset
   curl --location 'https://apis.roblox.com/assets/v1/assets' \
   --header 'x-api-key: ${ApiKey}' \
   --form 'request="{
     \"assetType\": \"Model\",
     \"displayName\": \"Nome\",
     \"description\": \"Questa è una descrizione\",
     \"creationContext\": {
       \"creator\": {
         \"userId\": \"${userId}\" # Usa groupId per creare un asset di gruppo
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

Aggiorna un asset esistente

Per aggiornare un asset esistente attraverso una richiesta HTTP:

1. Copia la chiave API nell'intestazione della richiesta x-api-key dell'endpoint Aggiorna Asset.
2. Aggiungi il tipo di asset e l'ID dell'asset nella tua richiesta. Per copiare il tuo ID asset:

   1. Naviga alla pagina Creazione del Pannello di controllo Creatore.
   2. Seleziona la categoria Elementi di sviluppo.
   3. Seleziona la categoria del tuo asset e trova l'asset target.
   4. Passa sopra la miniatura dell'asset target e fai clic sul pulsante ⋯ per visualizzare un elenco di opzioni, quindi seleziona Copia ID asset dall'elenco.

Esempio di richiesta per aggiornare il contenuto dell'asset
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}"'

Recupera lo stato dell'operazione dell'asset

Se la tua richiesta per creare un nuovo asset o aggiornare un asset esistente ha successo, restituisce un ID Operazione nel formato { "path": "operations/${operationId}" }. Puoi usarlo per controllare lo stato e il risultato del tuo caricamento seguendo i seguenti passaggi:

1. Copia la chiave API nell'intestazione della richiesta x-api-key del metodo Ottieni Operazione e invia la richiesta, come nel seguente campione di codice:

   Esempio di richiesta per ottenere l'operazione
   curl --location 'https://apis.roblox.com/assets/v1/operations/{operationId}' \
   --header 'x-api-key: {$ApiKey}'

2. Se la tua richiesta ha successo, restituisce un oggetto Operazione, includendo o una response che rappresenta le informazioni sugli asset caricati o uno status che spiega il motivo per cui il caricamento dell'asset è fallito, come mostra il seguente esempio di codice:

   Esempio di risposta per ottenere l'operazione
   {
     "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": "Nome",
       "description": "Questa è una descrizione",
       "assetType": "ASSET_TYPE_DECAL",
       "creationContext": {
         "creator": {
           "userId": "11112938575"
         }
       },
       "moderationResult": {
         "moderationState": "MODERATION_STATE_APPROVED"
       }
     }
   }

3. (Opzionale) Controlla l'asset creato sul tuo account Roblox.

   1. Naviga alla pagina Inventario del tuo account Roblox.
   2. Seleziona la Categoria dell'asset che desideri controllare.
   3. Trova l'asset target e fai clic sulla sua miniatura per visualizzarlo.

Aggiungi l'API degli asset alle app OAuth 2.0

Puoi creare applicazioni OAuth 2.0 che supportano l'API degli asset per consentire ai tuoi utenti di caricare e aggiornare asset su Roblox.

Per utilizzare l'API degli asset per la tua applicazione e richiedere permessi ai tuoi utenti, esegui le seguenti impostazioni:

1. Quando registri la tua applicazione, sotto Permessi, seleziona gli ambiti asset:read e asset:write.

2. Quando implementi il flusso di autorizzazione, includi asset:read e asset:write come parametri di ambito dell'URL di autorizzazione che reindirizza gli utenti indietro alla tua applicazione, come nel seguente esempio:

   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. Quando invii la richiesta, includi il token di accesso nell'intestazione di autorizzazione e i dati del contenuto dell'asset da creare o aggiornare nell'URI della richiesta. Il seguente esempio mostra un campione di richiesta per caricare un nuovo asset:

   Esempio di richiesta
   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\": \"Questa è una descrizione\",
   
     \"creationContext\": {
   
       \"creator\": {
   
       \"userId\": \"<user_id>\"
   
       }
     }
   
   }"' \
   
   --form 'fileContent=@"/filepath/p1.png"'