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 bằng một yêu cầu HTTP duy nhất thay vì nhập chúng vào Studio một cách thủ công. 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 ngược về một phiên bản trước đó đượ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 một tài sản mới hoặc không cập nhật nội dung của các tài sản hiện có, không có bất kỳ hạn chế và giới hạn nào. Tuy nhiên, chức năng tải nội dung tài sản được hỗ trợ 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ợ một số loại tài sản hạn chế với những điều kiện. Đối với mỗi yêu cầu, 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 từ bên thứ nhất với tự động xác thực API và sử dụng từ 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 script hoặc công cụ của riêng bạn, bạn cần tạo một khóa API cho việc xác thực và bảo mật.

Khi tạo một khóa API, hãy chắc chắn 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 mà bạn đã chọn, tùy thuộc vào 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 yêu cầu tiêu đề yêu cầu x-api-key.

Ví dụ về tiêu đề yêu cầu API
--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 một 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. Xác định loại tài sản mục tiêu.
   2. Thêm tên tài sản và mô tả của bạn.
   3. Thêm thông tin về người tạo.

      • Nếu bạn muốn tạo tài sản thay mặt cho chính bạn, 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 bạn trên URL của trang hồ sơ Roblox của bạn. Ví dụ, 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ụ, 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 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\": \"Tên\",
     \"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 một 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 vào 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 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.

Ví dụ yêu cầu cho việc cập nhật nội dung tài sản
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 cho việc 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ó trả về một ID Hoạt động có đị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 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 đây:

   Ví dụ yêu cầu cho việc 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ó 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 đã được 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 đây:

   Ví dụ phản hồi cho việc 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": "Tên",
       "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 đế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, hãy 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 thực hiện quy trình xác thực, bao gồm asset:read và asset:write như các tham số phạm vi của URL xác thực chuyển hướng người dùng quay 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 token truy cập trong tiêu đề xác thực và dữ liệu biểu mẫu nội dung tài sản để tạo hoặc cập nhật trong URI yêu cầu. Ví dụ sau đây 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"'