Hướng dẫn sử dụng cho tài sản

API Tài sản của Open Cloud cho phép bạn tải lên và cập nhật tài sản chỉ với một yêu cầu HTTP thay vì nhập thủ công vào Studio. API này hỗ trợ:

• Tải lên tài sản mới.
• Cập nhật tài sản hiện có với kiểm soát phiên bản.
• Cập nhật siêu dữ liệu tài sản, bao gồm mô tả, tên hiển thị, biểu tượng và bản xem trước.
• Quản lý các phiên bản tài sản, chẳng hạn như quay lại phiên bản trước đó đã chỉ định.
• Kiểm tra thông tin hiện có của một tài sản, bao gồm siêu dữ liệu, phiên bản và bất kỳ hoạt động cập nhật nào đang diễn ra.

Các loại tài sản và giới hạn được hỗ trợ

Đối với các điểm cuối không tạo tài sản mới hoặc cập nhật nội dung của tài sản hiện có, không có hạn chế và giới hạn nào. Tuy nhiên, chức năng tải lên nội dung tài sản được cung cấp bởi các điểm cuối Tạo Tài sản và Cập nhật Tài sản chỉ hỗ trợ các loại tài sản hạn chế. Đối với mỗi cuộc gọi, bạn chỉ có thể tạo hoặc cập nhật một tài sản với kích thước tệp lên đến 20 MB với các giới hạn sau:

Quyền bảo mật

API hỗ trợ cả việc sử dụng của bên thứ nhất với ủy quyền khóa API và việc sử dụng của bên thứ ba trong ứng dụng OAuth 2. Mỗi cách yêu cầu các cài đặt quyền bảo mật khác nhau.

Khóa API

Để sử dụng API trong các kịch bản hoặc công cụ của riêng bạn, bạn cần tạo một khóa API để ủy quyền và bảo mật.

Khi tạo một khóa API, hãy đảm bảo thêm các quyền sau:

1. Thêm tài sản vào Quyền truy cập.
2. Thêm quyền hoạt động Đọc và Ghi cho trò chơi đã chọn của bạn, tùy thuộc vào các phạm vi yêu cầu của các điểm cuối mà bạn dự định gọi.

Khi bạn có khóa API, hãy sao chép nó vào tiêu đề yêu cầu x-api-key. Tất cả các điểm cuối đều yêu cầu tiêu đề yêu cầu x-api-key.

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

Ứng dụng OAuth 2.0

Để sử dụng API cho một ứng dụng OAuth 2.0 của bên thứ ba, hãy thêm các phạm vi quyền asset:read và asset:write khi đăng ký ứng dụng của bạn. Chọn các phạm vi này dựa trên các yêu cầu của các điểm cuối mà bạn dự định sử dụng.

Tạo một tài sản mới

Để tải lên một tài sản mới bằng yêu cầu HTTP:

1. Sao chép khóa API vào tiêu đề yêu cầu x-api-key của điểm cuối Tạo Tài sản.

2. Trong yêu cầu của bạn:

   1. Chỉ định loại tài sản mục tiêu.
   2. Thêm tên và mô tả tài sản của bạn.
   3. Thêm thông tin người tạo.

      • Nếu bạn muốn tạo tài sản thay mặt cho chính mình, hãy thêm ID người dùng của bạn. Bạn có thể tìm thấy ID người dùng của mình trên URL của hồ sơ Roblox của bạn. Ví dụ, đối với https://www.roblox.com/users/1234567/profile, ID người dùng của bạn là 1234567.
      • Nếu bạn muốn tạo tài sản như một tài sản nhóm, hãy thêm ID nhóm của bạn. Bạn có thể tìm thấy ID nhóm trên URL của trang nhóm của bạn. Ví dụ, đối với https://www.roblox.com/groups/7654321/example-group#!/, ID nhóm là 7654321.
   4. Thêm đường dẫn tệp và loại nội dung của tài sản của bạn.

   Ví dụ Yêu cầu cho Tạo Tài sản

   curl --location 'https://apis.roblox.com/assets/v1/assets' \
   --header 'x-api-key: ${ApiKey}' \
   --form 'request="{
     \"assetType\": \"Model\",
     \"displayName\": \"Name\",
     \"description\": \"Đây là một mô tả\",
     \"creationContext\": {
       \"creator\": {
         \"userId\": \"${userId}\" # Sử dụng groupId để tạo tài sản nhóm
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

Cập nhật một tài sản hiện có

Để cập nhật một tài sản hiện có bằng yêu cầu HTTP:

1. Sao chép khóa API vào tiêu đề yêu cầu x-api-key của điểm cuối Cập nhật Tài sản.
2. Thêm loại tài sản và ID tài sản trong yêu cầu của bạn. Để sao chép ID tài sản của bạn:

   1. Điều hướng đến trang Tạo của Bảng điều khiển Người tạo.
   2. Chọn danh mục Mục phát triển.
   3. Chọn danh mục của tài sản của bạn và tìm tài sản mục tiêu.
   4. Di chuột qua hình thu nhỏ của tài sản mục tiêu và nhấp vào nút ⋯ để hiển thị danh sách tùy chọn, sau đó chọn Sao chép ID Tài sản từ danh sách.

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

Lấy trạng thái hoạt động tài sản

Nếu yêu cầu của bạn để tạo một tài sản mới hoặc cập nhật một tài sản hiện có thành công, nó sẽ trả về một ID Hoạt động theo định dạng { "path": "operations/${operationId}" }. Bạn có thể sử dụng nó để kiểm tra trạng thái và kết quả của việc tải lên của bạn với các bước sau:

1. Sao chép khóa API vào tiêu đề yêu cầu x-api-key của phương thức Lấy Hoạt động và gửi yêu cầu, như mẫu mã sau:

   Ví dụ Yêu cầu cho Lấy Hoạt động

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

2. Nếu yêu cầu của bạn thành công, nó sẽ trả về một đối tượng Operation, bao gồm một response đại diện cho thông tin tài sản đã tải lên hoặc một status giải thích lý do tại sao việc tải lên tài sản thất bại như mẫu mã sau:

   Ví dụ Phản hồi cho Lấy Hoạt động

   {
     "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": "Đây là một mô tả",
       "assetType": "ASSET_TYPE_DECAL",
       "creationContext": {
         "creator": {
           "userId": "11112938575"
         }
       },
       "moderationResult": {
         "moderationState": "MODERATION_STATE_APPROVED"
       }
     }
   }

3. TÙY CHỌN

   Kiểm tra tài sản đã tạo trên tài khoản Roblox của bạn.

   1. Điều hướng đến trang Kho của tài khoản Roblox của bạn.
   2. Chọn Danh mục của tài sản mà bạn muốn kiểm tra.
   3. Tìm tài sản mục tiêu và nhấp vào hình thu nhỏ của nó để xem tài sản.

Thêm API tài sản vào ứng dụng OAuth 2.0

Bạn có thể tạo ứng dụng OAuth 2.0 hỗ trợ API Tài sản để cho phép người dùng của bạn tải lên và cập nhật tài sản lên Roblox.

Để sử dụng API Tài sản cho ứng dụng của bạn và yêu cầu quyền từ người dùng của bạn, thực hiện các cài đặt sau:

1. Khi đăng ký ứng dụng của bạn, dưới Quyền, chọn các phạm vi asset:read và asset:write.

2. Khi triển khai luồng ủy quyền, bao gồm asset:read và asset:write như các tham số phạm vi của URL ủy quyền mà chuyển hướng người dùng trở lại ứng dụng của bạn, như ví dụ sau:

   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. Khi gửi yêu cầu, bao gồm mã thông báo truy cập trong tiêu đề ủy quyền và dữ liệu biểu mẫu của nội dung tài sản để tạo hoặc cập nhật trong URI yêu cầu. Ví dụ sau cho thấy một yêu cầu mẫu để tải lên một tài sản mới:

   Ví dụ Yêu cầu

   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\": \"Đây là một mô tả\", 
   
     \"creationContext\": {
   
       \"creator\": {
   
       \"userId\": \"<user_id>\"
   
       }
   
     }
   
   }"' \
   
   --form 'fileContent=@"/filepath/p1.png"'