Verwendungsanleitung für Assets

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

• Neue Assets hochladen.
• Aktualisierung bestehender Assets mit Versionskontrolle.
• Aktualisierung der Asset-Metadaten, einschließlich Beschreibungen, Display-Namen, Ikonen und Vorschauen.
• Verwaltung von Asset-Versionen, wie zum Beispiel das Zurückrollen auf eine bestimmte vorherige Version.
• Überprüfen der vorhandenen Informationen eines Objekt, einschließlich Metadaten, Versionen und aller aktuellen Aktualisierungsoperationen.

Unterstützte Asset-Typen und Grenzen

Für Endpunkte, die keine neue Ressource erstellen oder den Inhalt bestehender Ressourcen aktualisieren, gibt es keine Einschränkungen und Grenzen.Die Asset-Inhalts-Upload-Funktionalität, die von den Asset erstellen und Asset aktualisieren Endpunkten unterstützt wird, unterstützt jedoch nur begrenzte Arten von Assets mit Einschränkungen.Für jeden Anruf kannst du nur ein Asset mit der Dateigröße bis zu 20 MB erstellen oder aktualisieren, unter den folgenden Einschränkungen:

Sicherheitsberechtigungen

Die API unterstützt sowohl den Einsatz von Erstanbietern mit API-Schlüsselautorisierung als auch den Einsatz von Dritten in OAuth 2-Anwendungen.Jede Richtung erfordert unterschiedliche Sicherheitsberechtigungseinstellungen.

API-Schlüssel

Um die API in deinen eigenen Skripten oder Tools zu verwenden, musst du einen API-Schlüssel erstellen für die Autorisierung und Sicherheit.Um Assets zu verwalten, die du individuell besitzt, erstelle den API-Schlüssel unter deinem Konto.Um gruppeneigene Assets zu verwalten, erstelle den API-Schlüssel unter der Zielgruppe.Für weitere Informationen zu API-Schlüsseln, die einer Gruppe gehören, siehe Gruppenbesitzte API-Schlüsselberechtigungen.

Sobald du einen API-Schlüssel erstellt hast, kannst du seine Eigentümerschaft nicht zwischen Personen oder Gruppen wechseln, sodass du, wenn du einen API-Schlüssel unter deinem eigenen Konto erstellst, ihn nicht zur Verwaltung von Gruppenressourcen verwenden kannst.

Unabhängig davon, ob du den API-Schlüssel für dich selbst oder für deine Gruppe erstellst, stelle sicher, die folgenden Berechtigungen hinzuzufügen:

1. Füge Assets zu Zugriffsberechtigungen hinzu.
2. Füge Lesen und Schreiben Berechtigungen zu deiner ausgewählten Erlebnishinzu, abhängig von den erforderlichen Bereichen der Endpunkte, die du anrufen möchtest.

Sobald du den API-Schlüssel hast, kopiere ihn in den x-api-key Anforderungsheader. Alle Endpunkte benötigen den x-api-key Anforderungsheader.

Example API Request Header
--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 asset:read - und asset:write -Berechtigungsdomänen hinzu, wenn Sie Ihre App registrieren.Wählen Sie diese Bereiche basierend auf den Anforderungen der Endpunkte, die Sie verwenden möchten.

Erstelle ein neues Objekt

Um ein neues Asset per HTTP-Anfrage hochzuladen:

1. Kopiere den API-Schlüssel in den x-api-key Anforderungsheader der Asset erstellen Endpunkt.

2. In deiner Anfrage:

   1. Geben Sie den Ziel-Asset-Typ an.
   2. Füge deinen Asset-Namen und Beschreibunghinzu.
   3. Füge die Informationen zum Ersteller hinzu.

      • Wenn du das Asset auf eigene Faust erstellen möchtest , füge deine Benutzer-ID hinzu.Du kannst deine Benutzer-ID auf der URL deines Roblox-Profils finden.Zum Beispiel für https://www.roblox.com/users/1234567/profile ist deine Benutzer-ID 1234567.
      • Wenn du das Asset als Gruppen-Asset erstellen möchtest , füge die Gruppen-ID deiner Gruppe hinzu.Du kannst die Gruppen-ID auf der URL der Seite deiner Gruppe finden.Zum Beispiel für https://www.roblox.com/groups/7654321/example-group#!/ ist die Gruppen-ID 7654321 .
   4. Füge den Dateipfad und den Inhaltstyp deines Objekthinzu.

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

Ein vorhandenes Objektaktualisieren

Um ein vorhandenes Asset mit einer HTTP-Anfrage zu aktualisieren:

1. Kopiere den API-Schlüssel in den x-api-key Anforderungsheader der Update Asset Endpunkt.
2. Füge den Asset-Typ und die Asset-ID in deine Anfrage ein. Um deine Asset-ID zu kopieren:

   1. Navigiere zur Erstellungsseite des Creator-Dashboards .
   2. Wählen Sie die Kategorie Entwicklungsartikel .
   3. Wählen Sie die Kategorie Ihres Assets und finden Sie das zugeordnete Objekt.
   4. Bewegen Sie den Mauszeiger über die 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.

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

Abrufen des Status der Asset-Operation

Wenn deine Anfrage zur Erstellung eines neuen Assets oder zur Aktualisierung eines bestehenden Assets erfolgreich ist, gibt sie eine Betriebs-ID im Format von { "path": "operations/${operationId}" } zurück.Sie können es verwenden, um den Status und das Ergebnis Ihres Uploads mit den folgenden Schritten zu überprüfen:

1. Kopiere den API-Schlüssel in den x-api-key Anfragekopf der Methode Get Operation und sende die Anfrage, wie die folgende Code-Probe:

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

2. Wenn deine Anfrage erfolgreich ist, gibt sie ein Operation -Objekt zurück, entweder mit einer response -Repräsentation der hochgeladenen Asset-Informationen oder einem status -Objekt, das zeigt, warum der Asset-Upload als die folgende Code-Probe fehlschlägt:

   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. (Optional) Überprüfe das erstellte Asset auf deinem Roblox-Konto.

   1. Navigiere zur Inventar -Seite deines Roblox-Kontos.
   2. Wählen Sie die Kategorie des Assets aus, das Sie überprüfen möchten.
   3. Finde das Ziel-Asset und klicke auf seine Miniaturansicht, um das Objektanzuzeigen.

Füge Assets-API zu OAuth 2.0-Apps hinzu

Du kannst OAuth 2.0-Anwendungen erstellen, die Assets-API unterstützen, um deinen Benutzern zu ermöglichen, Assets auf Roblox hochzuladen und zu aktualisieren.

Um die Assets-API für Ihre Anwendung zu verwenden und Benutzerberechtigungen zu beantragen, führen Sie die folgenden Einstellungen aus:

1. Wenn du deine Anwendung registrierst, wähle unter Berechtigungen die Bereiche Objekt:read und Objekt:write.

2. Wenn du den Autorisierungsfluss implementierst, füge asset:read und asset:write als Bereichsparameter der Autorisierungs-URL hinzu, die Benutzer zurück zu deiner Anwendung umleitet, wie das folgende Beispiel:

   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. Wenn du die Anfrage sendest, füge das Zugriffstoken in den Autorisierungsheader und die Formdaten des Asset-Inhalts zum Erstellen oder Aktualisieren in der Anforderungs-URI ein.Das folgende Beispiel zeigt eine Probefrage für das Hochladen eines neuen Objekt:

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