资产使用指南

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

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

支持的资产类型和限制

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

安全权限

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

API 密钥

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

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

1. 将 assets 添加到 访问权限。
2. 根据您计划调用的端点的所需范围，为您选择的游戏添加 读取 和 写入 操作权限。

获得 API 密钥后，将其复制到 x-api-key 请求头中。所有端点都需要 x-api-key 请求头。

API 请求头示例
--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}"'

检索资产操作状态

如果您创建新资产或更新现有资产的请求成功，则会返回 操作 ID，格式为 { "path": "operations/${operationId}" }。您可以使用它来检查您的上传状态和结果，步骤如下：

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. 在 实施授权流程 时，在重定向用户回到您的应用的授权 URL 的范围参数中包括 asset:read 和 asset:write，如下例所示：

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