Guida all'uso per le risorse

L'Assets API di Open Cloud ti consente di caricare e aggiornare le risorse con una singola richiesta HTTP piuttosto che importarle manualmente in Studio.Questa API supporta:

• Caricamento di nuove risorse.
• Aggiornamento delle risorse esistenti con il controllo della versione.
• Aggiornamento dei metadati delle risorse, tra cui descrizioni, nomi di visualizzazione, icone e anteprime.
• Gestire le versioni delle risorse, come il ritorno a una versione precedente specificata.
• Controllo delle informazioni esistenti di una risorsa, incluse le metadati, le versioni e qualsiasi operazione di aggiornamento in corso.

Tipi di risorsa supportati e limiti

Per gli endpoint che non creano una nuova risorsa o aggiornano il contenuto delle risorse esistenti, non ci sono restrizioni o limiti.Tuttavia, la funzionalità di caricamento del contenuto delle risorse alimentata dai punti di estremità Crea risorsa e Aggiorna risorsa supporta solo tipi limitati di risorse con restrizioni.Per ogni chiamata, puoi creare o aggiornare solo una risorsa con la dimensione del file fino a 20 MB con i seguenti limiti:

Permessi di sicurezza

L'API supporta sia l'uso first-party con autorizzazione della chiave API e l'uso di terze parti in applicazioni OAuth 2.Ogni modo 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'autorizzazione e la sicurezza.Per gestire le risorse che possiedi individualmente, crea la chiave API sotto il tuo Account.Per gestire le risorse di proprietà del Gruppo, crea la chiave API sotto il gruppo target.Per ulteriori informazioni sulle chiavi API di proprietà del gruppo, vedi Permessi di chiave API di proprietà del gruppo.

Una volta creata una chiave API, non puoi cambiare la sua proprietà tra individui o gruppi, quindi se crei una chiave API sotto il tuo Account, non puoi usarla per gestire le risorse di gruppo.

Indipendentemente dal fatto che tu stia creando la chiave API per te o per il tuo Gruppo, assicurati di aggiungere i seguenti permessi:

1. Aggiungi risorse a Permessi di accesso .
2. Aggiungi Leggi e Scrivi le autorizzazioni di operazione alla tua esperienza selezionata, a seconda degli scopi richiesti degli 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 della richiesta x-api-key.

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

App di OAuth 2.0

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

Crea una nuova risorsa

Per caricare una nuova risorsa con una RichiestaHTTP:

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

2. Nella tua Richiesta:

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

      • Se vuoi creare l'asset a tuo nome , aggiungi il tuo ID utente.Puoi trovare l'ID utente sul URL del tuo ProfiloRoblox.Ad esempio, per https://www.roblox.com/users/1234567/profile , il tuo ID utente è 1234567 .
      • Se vuoi creare l'asset come risorsa di gruppo , aggiungi l'ID del gruppo 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 della tua risorsa.

   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}\" # Usa groupId per creare una risorsa di gruppo
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

Aggiorna una risorsa esistente

Per aggiornare una risorsa esistente con una RichiestaHTTP:

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

   1. Naviga alla pagina Creazione della Dashboard del creatore .
   2. Seleziona la categoria Oggetti di sviluppo .
   3. Seleziona la categoria della tua risorsa e trova la risorsa target.
   4. Passa il mouse sulla miniatura dell'asset target e fai clic sul pulsante ⋯ per visualizzare un elenco di opzioni, quindi seleziona Copia ID risorsa dall'elenco.

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

Recupera lo stato dell'operazione delle Stato

Se la richiesta di creazione di una nuova risorsa o di aggiornamento di una risorsa esistente ha successo, restituisce un ID operazione nel formato di { "path": "operations/${operationId}" } .Puoi usarlo per controllare lo stato e il risultato del tuo caricamento con i seguenti passaggi:

1. Copia la chiave API nell'intestazione della richiesta x-api-key del metodo Ottieni operazione e invia la Richiesta, come il seguente esempio di codice:

   Example Request for Get Operation
   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 Operation che include una response che rappresenta le informazioni sull'asset caricato o una status che spiega perché il caricamento dell'asset fallisce come mostra il seguente esempio di codice:

   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. (Opzionale) Controlla l'asset creato sul tuo AccountRoblox.

   1. Naviga alla pagina Inventario del tuo account Roblox.
   2. Seleziona la categoria dell'asset che vuoi Controllare /Verificare.
   3. Trova l'asset target e clicca sulla sua miniatura per visualizzare l'risorsa.

Aggiungi l'API delle risorse a app OAuth 2.0

Puoi creare applicazioni OAuth 2.0 che supportino l'API Assets per consentire ai tuoi utenti di caricare e aggiornare le risorse su Roblox.

Per utilizzare l'API Assets per la tua applicazione e richiedere autorizzazioni dai tuoi utenti, esegui le seguenti impostazioni:

1. Quando registri la tua applicazione, sotto Permessi , seleziona risorsa:read e risorsa:write scope.

2. Quando implementi il flusso di autorizzazione, includi asset:read e asset:write come parametri di scopo dell'URL di autorizzazione che reindirizza gli utenti al tuo applicativo, come l'esempio seguente:

   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. Quando si invia la Richiesta, includi il token di accesso nell'Header di autorizzazione e i dati della forma del contenuto della risorsa da creare o aggiornare nell' URI della richiesta.L'esempio seguente mostra una richiesta di esempio per il caricamento di una nuova risorsa:

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