資產使用指南

開放雲端的資產API讓您可以使用單一HTTP請求上傳和更新資產，而不是手動匯入到Studio。此 API 支持：

• 上傳新資產。
• 使用版本控制更新現有資產。
• 更新資產元數據，包括說明、顯示名稱、圖示和預覽。
• 管理資產版本，例如回到指定的舊版本。
• 檢查素材的現有資訊，包括元數據、版本和任何正在進行的更新操作。

支持的資產類型和限制

對於不創建新資產或更新現有資產內容的終端，沒有限制和限制。然而，由 創建資產 和 更新資產 端點提供的資產內容上傳功能只支持有限類型的資產，並受到限制。對於每個呼叫，您只能創建或更新一個資產，檔案大小不超過 20 MB，並受到以下限制：

安全權限

API 支持第一方使用與 API 鑰匙授權 以及第三方使用在 OAuth 2 應用程式 中。每種方式都需要不同的安全許可設定。

API 密鑰

若要在自己的腳本或工具中使用 API，您需要 創建 API 鑰匙 以進行授權和安全。若要管理個人擁有的資產，請在帳號戶下創建 API 鑰匙。要管理團體所有資產，請在目標群組體下創建 API 鑰匙。有關群擁有API鑰匙的更多信息，請參閱群擁有API鑰匙權限。

一旦您創建 API 鑰鍵,您無法在個人或群組之間切換其所有權,因此如果您在自己的帳號戶下創建 API 鑰匙,您無法使用它來管理群組資產。

無論您是為自己或您的群組創建 API 鑰匙，請務必添加以下權限：

1. 將 資產 添加到 存取權限 。
2. 將 閱讀 和 寫入 操作權限添加到您選擇的體驗，取決於您計劃呼叫的終端所需的範圍。

一旦您擁有 API 鑰鍵，將其複製到 x-api-key 請求頭。所有終端點都需要 x-api-key 請求頭。

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

OAuth 2.0 應用程式

若要使用 API 於第三方 OAuth 2.0 應用程式，請在 asset:read 時添加 asset:write 和 權限範圍。根據您計劃使用的終端的需求來選擇這些範圍。

創建新素材

要透過 HTTP 邀請求上傳新資產：

1. 複製 API 鑰匙到 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. 添加您資產的檔案路徑和內容類型。

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

更新現有素材

使用 HTTP 邀請求更新現有資產：

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

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

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

取得資產操作狀態

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

1. 複製 API 鑰匙到 x-api-key 請求頭的 獲取操作 方法，並傳送請邀請，如下代碼示例：

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

2. 如果您的請求成功，它將返回 Operation 個對物件，包括代表上傳的資產信息的 response 或為什麼資產上傳失敗的 status 解釋以下代碼示例所示的原因：

   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. (可選) 檢查你在 Roblox 帳號戶上創建的資產。

   1. 導航到您的 Roblox 帳戶 的 庫存 頁面。
   2. 選擇你想要檢查的資產的 類別 。
   3. 尋找目標資產，然後單擊其縮略圖以查看素材。

將資產 API 添加到 OAuth 2.0 應用

您可以創建 OAuth 2.0 應用程式 支持資產 API，以允許使用者上傳和更新 Roblox 的資產。

若要使用資產 API 為應用程式提供服務並向使用者請求權限，請執行以下設定：

1. 當 註冊您的應用程式 時，在 權限 下，選擇 素材：閱讀 和 素材：寫入 範圍。

2. 當 執行授權流程 時，包括 asset:read 和 asset:write 作為授權 URL 重定向用戶返回您的應用程式的範圍參數，如下示例：

   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. 當傳送請邀請時，包括在授權頭中的存取代碼和資產內容的表單數據，以在請求 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"'