Guida all'uso per le risorse

L'API delle Risorse di Open Cloud consente di caricare e aggiornare risorse con una singola richiesta HTTP anziché importarle manualmente in Studio. Questa API supporta:

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

Tipi di risorse supportati e limiti

Per gli endpoint che non creano una nuova risorsa o aggiornano il contenuto di risorse esistenti, non ci sono restrizioni e limiti. Tuttavia, la funzionalità di caricamento del contenuto delle risorse supportata dagli endpoint Crea Risorsa e Aggiorna Risorsa supporta solo tipi limitati di risorse con restrizioni. Per ogni chiamata, puoi creare o aggiornare solo una risorsa 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 in applicazioni OAuth 2. Ogni modalità richiede diverse impostazioni di permesso 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 risorse a Permessi di accesso.
2. Aggiungi i permessi di operazione Leggi e Scrivi 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 della richiesta x-api-key.

--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 una nuova risorsa

Per caricare una nuova risorsa tramite una richiesta HTTP:

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

2. Nella tua richiesta:

   1. Specifica il tipo di risorsa target.
   2. Aggiungi il nome e la descrizione della tua risorsa.
   3. Aggiungi le informazioni sul creatore.

      • Se desideri creare la risorsa 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 la risorsa 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.

   Esempio di richiesta per creare una risorsa

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

Aggiorna una risorsa esistente

Per aggiornare una risorsa esistente tramite una richiesta HTTP:

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

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

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 della risorsa

Se la tua richiesta per creare una nuova risorsa o aggiornare una risorsa esistente ha successo, restituisce un ID Operazione nel formato { "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 nel seguente esempio 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, che include un response che rappresenta le informazioni sulla risorsa caricata o uno status che spiega perché il caricamento della risorsa è 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 la risorsa creata sul tuo account Roblox.

   1. Naviga alla pagina Inventario del tuo account Roblox.
   2. Seleziona la Categoria della risorsa che desideri controllare.
   3. Trova la risorsa target e fai clic sulla sua miniatura per visualizzare la risorsa.

Aggiungi l'API delle risorse alle 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 risorse su Roblox.

Per utilizzare l'API delle risorse per la tua applicazione e richiedere permessi dai 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 di nuovo 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 modulo del contenuto della risorsa da creare o aggiornare nell'URI della richiesta. Il seguente esempio mostra un esempio di richiesta per caricare 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\": \"Questa è una descrizione\",
   
     \"creationContext\": {
   
       \"creator\": {
   
       \"userId\": \"<user_id>\"
   
       }
     }
   
   }"' \
   
   --form 'fileContent=@"/filepath/p1.png"'