Verwendungshinweise für Assets

Die Assets API von Open Cloud ermöglicht es Ihnen, Assets mit einer einzigen HTTP-Anfrage hochzuladen und zu aktualisieren, anstatt sie manuell in Studio zu importieren. Diese API unterstützt:

• Hochladen neuer Assets.
• Aktualisieren vorhandener Assets mit Versionskontrolle.
• Aktualisieren von Asset-Metadaten, einschließlich Beschreibungen, Anzeigenamen, Icons und Vorschauen.
• Verwalten von Asset-Versionen, z. B. das Zurücksetzen auf eine bestimmte vorherige Version.
• Überprüfen vorhandener Informationen eines Assets, einschließlich Metadaten, Versionen und laufenden Aktualisierungsoperationen.

Unterstützte Asset-Typen und -Grenzen

Für Endpunkte, die kein neues Asset erstellen oder den Inhalt vorhandener Assets aktualisieren, gibt es keine Einschränkungen und Grenzen. Die Funktionalität zum Hochladen von Asset-Inhalten, die von den Endpunkten Create Asset und Update Asset unterstützt wird, unterstützt jedoch nur eine begrenzte Anzahl von Asset-Typen mit Einschränkungen. Bei jedem Aufruf können Sie nur ein Asset mit einer Dateigröße von bis zu 20 MB mit den folgenden Grenzen erstellen oder aktualisieren:

Sicherheitsberechtigungen

Die API unterstützt sowohl die Nutzung durch Dritte mit API-Schlüsselautorisierung als auch die Nutzung in OAuth 2-Anwendungen. Jede Methode erfordert unterschiedliche Sicherheitseinstellungen.

API-Schlüssel

Um die API in Ihren eigenen Skripten oder Tools zu verwenden, müssen Sie einen API-Schlüssel erstellen für die Autorisierung und Sicherheit.

Beim Erstellen eines API-Schlüssels stellen Sie sicher, dass Sie die folgenden Berechtigungen hinzufügen:

1. Fügen Sie assets zu Zugriffsberechtigungen hinzu.
2. Fügen Sie die Berechtigungen für die Lesen- und Schreiben-Operationen zu Ihrem ausgewählten Spiel hinzu, abhängig von den erforderlichen Scopes der Endpunkte, die Sie aufrufen möchten.

Sobald Sie den API-Schlüssel haben, kopieren Sie ihn in den x-api-key-Anforderungsheader. Alle Endpunkte erfordern den x-api-key-Anforderungsheader.

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

OAuth 2.0-Apps

Um die API für eine Drittanbieter-OAuth 2.0-Anwendung zu verwenden, fügen Sie die Berechtigungsscope asset:read und asset:write hinzu, wenn Sie Ihre App registrieren. Wählen Sie diese Scopes basierend auf den Anforderungen der Endpunkte aus, die Sie verwenden möchten.

Erstellen eines neuen Assets

Um ein neues Asset über eine HTTP-Anfrage hochzuladen:

1. Kopieren Sie den API-Schlüssel in den x-api-key-Anforderungsheader des Create Asset Endpunkts.

2. In Ihrer Anfrage:

   1. Geben Sie den Ziel- Asset-Typ an.
   2. Fügen Sie den Namen und die Beschreibung Ihres Assets hinzu.
   3. Fügen Sie die Informationen des Erstellers hinzu.

      • Wenn Sie das Asset in Ihrem eigenen Namen erstellen möchten, fügen Sie Ihre Benutzer-ID hinzu. Sie finden Ihre Benutzer-ID in der URL Ihres Roblox-Profils. Zum Beispiel, für https://www.roblox.com/users/1234567/profile,ist Ihre Benutzer-ID1234567`.
      • Wenn Sie das Asset als Gruppen-Asset erstellen möchten, fügen Sie die Gruppen-ID Ihrer Gruppe hinzu. Sie finden die Gruppen-ID in der URL der Seite Ihrer Gruppe. Zum Beispiel, für https://www.roblox.com/groups/7654321/example-group#!/,ist die Gruppen-ID7654321`.
   4. Fügen Sie den Dateipfad und den Inhaltstyp Ihres Assets hinzu.

   Beispielanfrage zum Erstellen eines Assets

   curl --location 'https://apis.roblox.com/assets/v1/assets' \
   --header 'x-api-key: ${ApiKey}' \
   --form 'request="{
     \"assetType\": \"Model\",
     \"displayName\": \"Name\",
     \"description\": \"Dies ist eine Beschreibung\",
     \"creationContext\": {
       \"creator\": {
         \"userId\": \"${userId}\" # Verwenden Sie groupId, um ein Gruppen-Asset zu erstellen
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

Aktualisieren eines vorhandenen Assets

Um ein vorhandenes Asset über eine HTTP-Anfrage zu aktualisieren:

1. Kopieren Sie den API-Schlüssel in den x-api-key-Anforderungsheader des Update Asset Endpunkts.
2. Fügen Sie den Asset-Typ und die Asset-ID in Ihrer Anfrage hinzu. Um Ihre Asset-ID zu kopieren:

   1. Navigieren Sie zur Erstellungs Seite des Creator Dashboards.
   2. Wählen Sie die Kategorie Entwicklungsartikel.
   3. Wählen Sie die Kategorie Ihres Assets und finden Sie das Ziel-Asset.
   4. Fahren Sie mit der Maus über das Thumbnail des Ziel-Assets und klicken Sie auf die ⋯-Schaltfläche, um eine Liste von Optionen anzuzeigen, und wählen Sie dann Asset-ID kopieren aus der Liste.

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

Abrufen des Status der Asset-Operation

Wenn Ihre Anfrage zum Erstellen eines neuen Assets oder zum Aktualisieren eines vorhandenen Assets erfolgreich ist, wird eine Operation-ID im Format { "path": "operations/${operationId}" } zurückgegeben. Sie können diese verwenden, um den Status und das Ergebnis Ihres Uploads mit den folgenden Schritten zu überprüfen:

1. Kopieren Sie den API-Schlüssel in den x-api-key-Anforderungsheader der Get Operation Methode und senden Sie die Anfrage, wie im folgenden Codebeispiel:

   Beispielanfrage für Get Operation

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

2. Wenn Ihre Anfrage erfolgreich ist, wird ein Operation-Objekt zurückgegeben, das entweder eine response enthält, die die Informationen des hochgeladenen Assets darstellt, oder einen status, der erklärt, warum der Asset-Upload fehlgeschlagen ist, wie im folgenden Codebeispiel gezeigt:

   Beispielantwort für 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": "Dies ist eine Beschreibung",
       "assetType": "ASSET_TYPE_DECAL",
       "creationContext": {
         "creator": {
           "userId": "11112938575"
         }
       },
       "moderationResult": {
         "moderationState": "MODERATION_STATE_APPROVED"
       }
     }
   }

3. OPTIONAL

   Überprüfen Sie das erstellte Asset in Ihrem Roblox-Konto.

   1. Navigieren Sie zur Inventar-Seite Ihres Roblox-Kontos.
   2. Wählen Sie die Kategorie des Assets aus, das Sie überprüfen möchten.
   3. Finden Sie das Ziel-Asset und klicken Sie auf das Thumbnail, um das Asset anzuzeigen.

Assets API zu OAuth 2.0-Apps hinzufügen

Sie können OAuth 2.0-Anwendungen erstellen, die die Assets API unterstützen, um Ihren Benutzern das Hochladen und Aktualisieren von Assets in Roblox zu ermöglichen.

Um die Assets API für Ihre Anwendung zu verwenden und Berechtigungen von Ihren Benutzern anzufordern, führen Sie die folgenden Einstellungen durch:

1. Wählen Sie beim Registrieren Ihrer Anwendung unter Berechtigungen die Scopes asset:read und asset:write aus.

2. Fügen Sie beim Implementieren des Autorisierungsflusses asset:read und asset:write als die Scope-Parameter der Autorisierungs-URL hinzu, die die Benutzer zurück zu Ihrer Anwendung umleitet, wie im folgenden Beispiel:

   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. Fügen Sie beim Senden der Anfrage das Zugriffstoken im Autorisierungsheader und die Formulardaten des Asset-Inhalts, die erstellt oder aktualisiert werden sollen, in der Anforderungs-URI hinzu. Das folgende Beispiel zeigt eine Beispielanfrage zum Hochladen eines neuen Assets:

   Beispielanfrage

   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\": \"Dies ist eine Beschreibung\", 
   
     \"creationContext\": {
   
       \"creator\": {
   
       \"userId\": \"<user_id>\"
   
       }
   
     }
   
   }"' \
   
   --form 'fileContent=@"/filepath/p1.png"'