Verwendungsrichtlinie für Assets

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

• Neue Assets hochladen.
• Aktualisieren von bestehenden Assets mit Versionen.
• Aktualisieren von Asset-Metadaten, einschließlich Beschreibungen, Anzeigename, Icons und Vorschau.
• Verwaltung der Versionen von Assets, z. B. zur Rückkehr zu einer bestimmten früheren Version.
• Überprüfen Sie bestehende Informationen eines Objekt, einschließlich Metadaten, Versionen und alle In-Process-Updating-Operationen.

Unterstützte Asset-Typen und Limit

Für Endpunkte, die keine neuen Assets erstellen oder den Inhalt bestehender Assets aktualisieren, gibt es keine Einschränkungen und Limits. Die Asset-Inhalts-Upload-Funktion, die von den Create Asset und Update Asset Endpunkten angetrieben wird, unterstützt nur begrenzte Arten von Assets mit Einschränkungen. Für jeden Aufruf kannst du nur ein Asset mit der Größe bis zu 20 MB mit den folgenden

Sicherheitsberechtigungen

Die API unterstützt sowohl den ersten-Party- als auch den Dritt-Party-Use mit API-Schlüssel-Autorisierung und Dritt-Party-Use in OAuth 2-Anwendungen. Jeder Weg erfordert verschiedene Berechtigungseinstellungen.

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, die du individuell besitzt, zu verwalten, musst du den API-Schlüssel unter deinem Konto erstellen. Um Assets, die du über die Gruppeverfügst, zu verwalten, musst du den API-Schlüssel unter der Zielgruppe erstellen. Weitere Informationen

Sobald du einen API-Schlüssel erstellt hast, kannst du den Besitz nicht zwischen einzelnen oder Gruppen wechseln, so dass, wenn du einen API-Schlüssel unter deinem eigenen Konto erstellst, kannst du es nicht verwenden, um Gruppen-Assets zu verwalten.

Unabhängig davon, ob du den API-Schlüssel für dich selbst oder deine Gruppe erstellen möchtest, stelle sicher, dass du die folgenden Berechtigungen hinzufügst:

1. Füge Assets zu Zugriffsberechtigungen hinzu.
2. Fügen Sie Lesen und Schreiben Operationen Berechtigungen zu Ihrem ausgewählten Erlebnis hinzu, abhängig von den erforderlichen Schuppen der Endpunkte, die Sie planen, zu rufen.

Sobald Sie den Schlüsselhaben, kopieren Sie ihn in die x-api-key Anfrage-Header. Alle Endpunkte erfordern die x-api-key Anfrage-Header.

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

OAuth 2.0-Apps

Um die API für eine Drittsoftware-OAuth 2.0-Anwendung zu verwenden, fügen Sie die Berechtigungsskope asset:read und asset:write hinzu, wenn Sie Ihre App registrieren. Wählen Sie diese Skripte basierend auf den Anforderungen der Endpunkte, die Sie verwenden planen.

Erstellen eines neuen Assets

Um ein neues Asset per HTTP-Anfrage hochzuladen:

1. Kopiere den API-Key in den x-api-key Request-Header des Create Asset Endpoints.

2. In deiner Anfrage:

   1. Geben Sie das Ziel Asset-Typ an.
   2. Füge deinen Asset-Namen und deine Beschreibung hinzu.
   3. Füge die Erstellerinformationen hinzu.

      • Wenn Sie das Asset im Namen eines Drittes erstellen , fügen Sie Ihre Benutzer-ID hinzu. Sie finden Ihre Benutzer-ID auf der URL Ihres Roblox-Profils. Zum Beispiel für https://www.roblox.com/users/1234567/profile ist Ihre Benutzer-ID 1234567 .
      • Wenn Sie das Asset als Gruppen-Asset erstellen möchten, fügen Sie die Gruppen-ID Ihrer Gruppe hinzu. Sie können die Gruppen-ID auf der URL der Seite Ihrer Gruppe finden. Zum Beispiel für https://www.roblox.com/groups/7654321/example-group#!/ ist die Gruppen-ID https://www.roblox.com/groups/7654321/example-group#!/ .
   4. Fügen Sie dem Objektden Dateipfad und den Inhaltstyp hinzu.

   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}\" # Verwenden Sie groupId, um eine Objektzu erstellen
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

Aktualisieren eines bestehenden Assets

Um ein bestehendes Asset per HTTP-Anfrage zu aktualisieren:

1. Kopiere den API-Key in den x-api-key Request-Header des Update Asset Endpoints.
2. Fügen Sie dem Asset-Typ und der Asset-ID in Ihrer Anfrage hinzu. Um Ihre Asset-ID zu kopieren:

   1. Navigiere zur Erstellungs- Seite des Creator-Dashboards ".
   2. Wähle die Entwicklung-Items Kategorie.
   3. Wählen Sie die Kategorie Ihres Assets und finden Sie das Objekt.
   4. Bewegen Sie den Mauszeiger über die Miniaturansicht des Ziels und klicken Sie auf die Schaltfläche ⋯ , um eine Liste von Optionen anzuzeigen, und wählen Sie dann Kopieren Asset-ID 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}"'

Asset-Operation-Status abrufen

Wenn deine Anfrage zum Erstellen eines neuen Assets oder zur Aktualisierung eines bestehenden Assets erfolgreich ist, gibt es eine Operation ID im Format "Path": "Operations$operationId" zurück. Du kannst sie verwenden, um den Status und das Ergebnis deines Uploads mit den folgenden Schritten zu überprüfen:

1. Kopiere den API-Key in die x-api-key Request-Header der GET OPERATION Methode und sende die Anfrage, wie in dem folgenden Codebeispiel:

   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 es ein Operation -Objekt zurück, das entweder ein response enthält, das die hochgeladenen Asset-Informationen repräsentiert, oder ein status , das erklärt, warum die Asset-Upload-Funktion als das folgende Codebeispiel 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üfen Sie das erstellte Asset auf Ihrem Roblox-Konto.

   1. Navigiere zur Inventar-Seite deines Roblox-Kontos.
   2. Wähle die Kategorie des Assets, das du überprüfen möchtest.
   3. Finden Sie das Ziel-Asset und klicken Sie auf sein Miniaturbild, um das Objektanzuzeigen.

Assets-API zu OAuth 2.0-Apps hinzufügen

Du kannst OAuth 2.0-Anwendungen erstellen, die Assets-API unterstützen, damit deine Benutzer Assets auf Roblox hochladen und aktualisieren können.

Um die Assets-API für Ihre Anwendung und die Erteilung von Berechtigungen an Ihre Benutzer zu verwenden, führen Sie die folgenden Einstellungen aus:

1. Wenn registrieren Sie Ihre Anwendung , unter Berechtigungen , wählen Sie Objekt:Read und Objekt:Write1> Skalierungen.

2. Wenn die Berechtigung-Flow-구현 , einschließen Sie asset:read und asset:write als Ziel参数 der Berechtigung URL, die Benutzer auf Ihre Anwendung zurückleitet, wie das folgende Beispiel zeigt:

   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. Wenn Sie die Anfrage senden, enthalten Sie den Zugang Token in der Autorisations头line und die Formdaten des Asset-Inhalts, um in der Anfrage-URL zu erstellen oder zu aktualisieren. Das folgende Beispiel zeigt ein Beispielanfrage 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"'