资产使用指南

开放云的 资产API 允许您通过单个HTTP请求上传和更新资产，而不是手动将其导入到Studio中。此API支持：

• 上传新资产。
• 使用版本控制更新现有资产。
• 更新资产元数据，包括描述、显示名称、图标和预览。
• 管理资产版本，例如回滚到指定的先前版本。
• 检查资产的现有信息，包括元数据、版本和任何正在进行的更新操作。

支持的资产类型和限制

对于不创建新资产或更新现有资产内容的端点，没有限制和限制。然而，由 创建资产 和 更新资产 端点提供的资产内容上传功能仅支持有限类型的资产，并有一些限制。每次调用，您只能创建或更新一个资产，文件大小上限为20 MB，具体限制如下：

安全权限

该API支持通过 API密钥授权 的第一方使用和在 OAuth 2应用程序 中的第三方使用。每种方式需要不同的安全权限设置。

API密钥

要在您自己的脚本或工具中使用API，您需要为授权和安全 创建API密钥。

创建API密钥时，请确保添加以下权限：

1. 将 资产 添加到 访问权限。
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密钥复制到 创建资产 端点的 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\": \"名称\",
     \"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。

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密钥复制到 获取操作 方法的 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": "名称",
       "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的范围参数，重定向用户回到您的应用，如以下示例所示：

   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\": \"这是一个描述\", 
   
     \"creationContext\": {
   
       \"creator\": {
   
       \"userId\": \"<user_id>\"
   
       }
   
     }
   
   }"' \
   
   --form 'fileContent=@"/filepath/p1.png"'