资产使用手册

Open Cloud 的 资产 API 允许您使用单个 HTTP 请求上传和更新资产，而不是手动将它们导入到 Studio。此 API 支持：

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

支持的资产类型和限制

对于不要创建新资产或更新现有资产的端点，没有限制和限制。 但是，通过 创建资产 和 更新资产 端点上的资产内容上传功能，只能支持限制类型的资产，并且只能在每个调用中创建或更新一个资产。 对于每个调用，您只能创建或更新一个资产，其文件大小最多为 20 MB，并且只能使用以下限

安全权限

API支持 both first-party use with API key authorization 和 third-party use in OAuth 2 applications . 每种方式都需要不同的安全权限设置。

API 钥匙

要使用 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 应用程序使用 API，请在注册您的应用程序时添加asset:read和asset:write权限范围。选择这些范围根据您的端点计划使用。

创建一个新资产

通过 HTTP 请求上传新资产：

1. 复制 API 钥匙到 x-api-key 请求头的 创建资产 端口。

2. 在您的请求中：

   1. 指定目标 资产类型。
   2. 添加你的资产名称和描述。
   3. 添加创建者信息。

      • 如果您想为资产 在您自己的名义 ，请添加您的用户ID。您可以在 Roblox 个人资料上找到您的用户ID。例如，对于https://www.roblox.com/users/1234567/profile，您的用户ID是1234567。
      • 如果您想要将资产创建为群组资产，请添加您群组的组 ID。您可以在群组页面上的 URL 上找到组 ID 。例如，对于 https://www.roblox.com/groups/7654321/example-group#!/ 的群组 ID，组 ID 是 https://www.roblox.com/groups/7654321/example-group#!/ 。
   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 对象或包含资源上传失败为下列代码示例所示：

   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. 找到目标资产，然后单击其缩略图以查看素材。

将 Assets API 添加到 OAuth 2.0 应用

您可以创建OAuth 2.0应用程序，支持资产API，允许您的用户上传和更新资产到Roblox。

要使用 Assets API 为您的应用程序和请求权限，请执行以下设置：

1. 在注册您的应用，在 权限 下，选择 素材:read 和1>素材:write1>范围。

2. 当 实现授权流程 时，包括 asset:read 和 asset:write 作为用户返回您的应用程序的授权 URL 的范围参数，例如以下示例：

   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. 在发送请求时，包括认证头中的访问代币和资产内容的表格数据，以在请求中的请求内创建或更新。以下示例显示了一个示例请求，用于上传新素材：

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