資產使用指南

Open Cloud 的 Assets API 允許您通過單個 HTTP 請求上傳和更新資產，而不是手動將它們導入到 Studio。此 API 支援：

• 上傳新資產。
• 使用版本控制更新現有資產。
• 更新資產元數據，包括描述、顯示名稱、圖標和預覽。
• 管理資產版本，例如回滾到指定的先前版本。
• 檢查資產的現有信息，包括元數據、版本和任何正在進行的更新操作。

支援的資產類型和限制

對於不創建新資產或更新現有資產內容的端點，沒有任何限制和限制。然而，由 Create Asset 和 Update Asset 端點提供的資產內容上傳功能僅支援有限類型的資產並有相應的限制。每次調用，您只能創建或更新一個資產，文件大小上限為 20 MB，具體限制如下：

安全權限

該 API 支援使用 API 金鑰授權 的第一方使用和在 OAuth 2 應用程序 中的第三方使用。每種方式需要不同的安全權限設置。

API 金鑰

要在您自己的腳本或工具中使用 API，您需要 創建 API 金鑰 以進行授權和安全。

創建 API 金鑰時，請確保添加以下權限：

1. 將 assets 添加到 訪問權限。
2. 根據您計劃調用的端點所需的範圍，將 讀取 和 寫入 操作權限添加到您選擇的遊戲中。

擁有 API 金鑰後，將其複製到 x-api-key 請求標頭中。所有端點都需要 x-api-key 請求標頭。

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

OAuth 2.0 應用

要在第三方 OAuth 2.0 應用中使用 API，請在 註冊應用 時添加 asset:read 和 asset:write 權限範圍。根據您計劃使用的端點的要求選擇這些範圍。

創建新資產

要通過 HTTP 請求上傳新資產：

1. 將 API 金鑰複製到 Create Asset 端點的 x-api-key 請求標頭中。

2. 在您的請求中：

   1. 指定目標 資產類型。
   2. 添加您的資產名稱和描述。
   3. 添加創建者信息。

      • 如果您想要 以您自己的名義 創建資產，請添加您的用戶 ID。您可以在您的 Roblox 個人資料的 URL 中找到您的用戶 ID。例如，對於 https://www.roblox.com/users/1234567/profile,，您的用戶 ID 是 1234567`。
      • 如果您想要 作為群組資產 創建資產，請添加您群組的群組 ID。您可以在您群組頁面的 URL 中找到群組 ID。例如，對於 https://www.roblox.com/groups/7654321/example-group#!/,，群組 ID 是 7654321`。
   4. 添加您的資產的文件路徑和內容類型。

   創建資產的示例請求

   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}\" # 使用 groupId 創建群組資產
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

更新現有資產

要通過 HTTP 請求更新現有資產：

1. 將 API 金鑰複製到 Update Asset 端點的 x-api-key 請求標頭中。
2. 在您的請求中添加資產類型和資產 ID。要複製您的資產 ID：

   1. 瀏覽到 創建者儀表板 的 Creation 頁面。
   2. 選擇 開發項目 類別。
   3. 選擇您的資產類別並找到目標資產。
   4. 將鼠標懸停在目標資產的縮略圖上，然後單擊 ⋯ 按鈕以顯示選項列表，然後從列表中選擇 複製資產 ID。

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

檢索資產操作狀態

如果您創建新資產或更新現有資產的請求成功，則會返回格式為 { "path": "operations/${operationId}" } 的 操作 ID。您可以使用它來檢查上傳的狀態和結果，步驟如下：

1. 將 API 金鑰複製到 Get Operation 方法的 x-api-key 請求標頭中，並發送請求，如以下代碼示例所示：

   獲取操作的示例請求

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

2. 如果您的請求成功，則會返回一個 Operation 對象，該對象可能包含一個 response，表示上傳的資產信息，或者一個 status，解釋為什麼資產上傳失敗，如以下代碼示例所示：

   獲取操作的示例響應

   {
     "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. 可選

   檢查您 Roblox 帳戶上的創建資產。

   1. 瀏覽到您的 Roblox 帳戶 的 庫存 頁面。
   2. 選擇您要檢查的資產的 類別。
   3. 找到目標資產並單擊其縮略圖以查看資產。

將資產 API 添加到 OAuth 2.0 應用

您可以創建支援資產 API 的 OAuth 2.0 應用程序，以允許您的用戶上傳和更新 Roblox 上的資產。

要在您的應用中使用資產 API 並請求用戶的權限，請執行以下設置：

1. 在 註冊應用 時，在 權限 下選擇 asset:read 和 asset:write 範圍。

2. 在 實現授權流程 時，將 asset:read 和 asset:write 包含為授權 URL 的範圍參數，該 URL 將用戶重定向回您的應用，如以下示例所示：

   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. 在發送請求時，將訪問令牌包含在授權標頭中，並將資產內容的表單數據包含在請求 URI 中。以下示例顯示了上傳新資產的示例請求：

   示例請求

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