Guida all'uso per le risorse

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

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

Tipi e limiti di risorse supportati

Per i punti finali che non creano una nuova risorsa o aggiornano il contenuto di risorse esistenti, non ci sono restrizioni e limiti. Tuttavia, la funzione di caricamento dei contenuti delle risorse alimentata dal Crea una risorsa e Aggiorna una risorsa supporta solo i tipi di risorse con restrizioni. Per ogni chiamata, puoi creare o aggiornare una sola risorsa con la dimensione del file fino a

Permessi di sicurezza

L'API supporta l'uso sia di prima parte con autorizzazione chiave API che l'uso di terze parti in 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'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 di destinazione. Per ulteriori informazioni su le chiavi API di proprietà del gruppo, vedi autorizzazioni API.

Una volta creata una chiave API, non puoi cambiare la sua proprietà tra gli individui o i gruppi, quindi se crei una chiave API sotto il tuo Account, non puoi usarlo per la gestione delle risorse del gruppo.

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

1. Aggiungi risorse a Permessi di accesso .
2. Aggiungi Leggi e Scrivi autorizzazioni operative alla tua esperienza, a seconda degli scopi richiesti dai punti di fine punti che vuoi chiamare.

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

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

App OAuth 2.0

Per utilizzare l'API per un'applicazione OAuth 2.0 di terze parti, aggiungi i asset:read e asset:write scala di autorizzazione quando registri la tua app. Scegli queste scala in base ai requisiti dei punti di destinazione che hai in programma di utilizzare.

Creazione di una nuova risorsa

Per caricare una nuova risorsa con una RichiestaHTTP:

1. Copia la chiave API alla richiesta x-api-key della端口 Crea risorsa .

2. Nella tua Richiesta:

   1. Specificare il tipo di risorsa asset type .
   2. Aggiungi il tuo nome e la Descrizionedell'asset.
   3. Aggiungi le informazioni sul creatore.

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

Aggiornamento di una risorsa esistente

Per aggiornare una risorsa esistente con una RichiestaHTTP:

1. Copia la chiave API alla richiesta x-api-key del header della richiesta Update Asset .
2. Aggiungi il tipo di risorsa e l'ID della risorsa nella tua Richiesta. Per copiare il tuo ID della risorsa:

   1. Vai 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 della risorsa target e fai clic sul pulsante ⋯ per visualizzare una lista di opzioni, quindi seleziona Copia ID risorsa dalla lista.

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

Recupero dello stato dell'operazione dell'asset

Se la tua richiesta per la creazione di una nuova risorsa o l'aggiornamento di una risorsa esistente ha successo, restituisce un ID dell'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 nella richiesta di x-api-key del metodo Get Operation 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 , incluso un response rappresentante le informazioni sull'asset caricate o un status che spiega perché il caricamento delle risorse non funziona 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. (Facoltativo) Controlla la risorsa creata sul tuo AccountRoblox.

   1. Vai alla pagina Inventario del tuo account Roblox.
   2. Seleziona la categoria della risorsa che vuoi Controllare /Verificare.
   3. Trova la risorsa target e fai clic sulla sua miniatura per visualizzare la risorsa.

Aggiungere API delle risorse agli app OAuth 2.0

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

Per utilizzare l'API delle risorse per la tua applicazione e richiedere autorizzazioni ai tuoi utenti, esegui i seguenti impostazioni:

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

2. Quando implementare il flusso di autorizzazione , includere asset:read e asset:write come parametri di scala della URL di autorizzazione che reindirizza gli utenti alla tua applicazione, come il seguente esempio:

   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. Quando si invia la Richiesta, includere il token di accesso nell'autorizzazione header e i dati di forma della risorsa contenuta nella richiesta per creare o aggiornare nell'URL della richiesta. Il seguente esempio mostra un esempio di richiesta per l'invio di una nuova risorsa:

   Richesta di esempio
   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"'