Verwendungshinweis 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, wie z.B. das Zurücksetzen auf eine bestimmte vorherige Version.
• Überprüfen bestehender Informationen zu einem Asset, einschließlich Metadaten, Versionen und laufenden Aktualisierungsoperationen.

Unterstützte Asset-Typen und -Beschränkungen

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

Sicherheitsberechtigungen

Die API unterstützt sowohl die Nutzung durch die erste Partei mit API-Schlüsselautorisierung als auch die Nutzung durch Dritte in OAuth 2-Anwendungen. Jeder Weg 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 zur 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 je nach den erforderlichen Berechtigungen der Endpunkte, die Sie aufrufen möchten, Lese- und Schreibberechtigungen für Ihr ausgewähltes Spiel hinzu.

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

Beispiel API-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 beim Registrieren Ihrer App die Berechtigungsbereiche asset:read und asset:write hinzu. Wählen Sie diese Bereiche basierend auf den Anforderungen der Endpunkte aus, die Sie verwenden möchten.

Erstellen eines neuen Assets

Um ein neues Asset durch eine HTTP-Anfrage hochzuladen:

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

2. Fügen Sie in Ihrer Anfrage hinzu:

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

      • Wenn Sie das Asset in eigenem Namen erstellen möchten, fügen Sie Ihre Benutzer-ID hinzu. Sie finden Ihre Benutzer-ID in der URL Ihres Roblox-Profils. Zum Beispiel ist Ihre Benutzer-ID bei https://www.roblox.com/users/1234567/profile, 1234567`.
      • 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 ist bei https://www.roblox.com/groups/7654321/example-group#!/,die Gruppen-ID7654321`.
   4. Fügen Sie den Dateipfad und den Inhaltstyp Ihres Assets hinzu.

   Beispielanfrage für 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 für die Erstellung eines Gruppen-Assets
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

Aktualisieren eines vorhandenen Assets

Um ein vorhandenes Asset durch 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 Dashboard.
   2. Wählen Sie die Kategorie Development Items.
   3. Wählen Sie die Kategorie Ihres Assets aus und finden Sie das Ziel-Asset.
   4. Bewegen Sie den Mauszeiger über das Miniaturansicht 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.

Beispielanfrage zum Aktualisieren des Asset-Inhalts
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 einer Asset-Operation

Wenn Ihre Anfrage zum Erstellen eines neuen Assets oder Aktualisieren eines vorhandenen Assets erfolgreich ist, gibt das System eine Operation ID im Format { "path": "operations/${operationId}" } zurück. Sie können diese ID 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, ähnlich wie der folgende Code-Ausschnitt:

   Beispielanfrage für Abruf der Operation
   curl --location 'https://apis.roblox.com/assets/v1/operations/{operationId}' \
   --header 'x-api-key: {$ApiKey}'

2. Wenn Ihre Anfrage erfolgreich ist, gibt es ein Operation-Objekt zurück, das entweder eine response enthält, die die Informationen des hochgeladenen Assets repräsentiert, oder einen status, der erklärt, warum der Upload des Assets fehlschlägt, wie im folgenden Code-Ausschnitt gezeigt:

   Beispielantwort für Abruf der 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 auf 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.

API für Assets zu OAuth 2.0-Anwendungen 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 auf 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 aus:

1. Beim Registrieren Ihrer Anwendung wählen Sie unter Berechtigungen die Berechtigungsbereiche asset:read und asset:write aus.

2. Beim Implementieren des Autorisierungsflusses fügen Sie asset:read und asset:write als die Berechtigungsparameter der Autorisierungs-URL hinzu, 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. Beim Senden der Anfrage fügen Sie das Zugriffstoken im Autorisierungsheader und die Formdaten des zu erstellenden oder zu aktualisierenden Asset-Inhalts in der Anfrage-URI ein. Das folgende Beispiel zeigt ein Beispiel für eine Anfrage 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"'