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 và cập nhật tài sản với một yêu cầu HTTP duy nhất thay vì nhập chúng thủ công vào Studio.API này hỗ trợ:

• Tải lên các 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 metadata tài sản, bao gồm các mô tả, tên hiển thị, biểu tượng và bản xem trước.
• Quản lý phiên bản tài sản, chẳng hạn như quay lại phiên bản trước định.
• Kiểm tra thông tin hiện có của một tài sản, bao gồm metadata, phiên bản và bất kỳ hoạt động cập nhật nào đang diễn ra.

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

Đối với các điểm cuối không tạo một 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ó giới hạn và hạn chế.Tuy nhiên, chức năng tải nội dung tài sản được cung cấp bởi Tạo tài sản và Cập nhật tài sản kết thúc chỉ hỗ trợ các loại tài sản giới hạn với các hạn chế.Cho 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ả sử dụng nội bộ với quyền xác nhận chìa khóa API và sử dụng 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 chìa khóa API để xác nhận và bảo mật.Để quản lý tài sản mà bạn sở hữu riêng lẻ, tạo chìa khóa API dưới tài khoản của bạn.Để quản lý tài sản thuộc sở hữu nhóm, tạo chìa khóa API dưới nhóm mục tiêu.Để biết thêm thông tin về chìa khóa API thuộc sở hữu nhóm, hãy xem Quyền truy cập chìa khóa API thuộc sở hữu nhóm.

Một khi bạn tạo một chìa khóa API, bạn không thể chuyển đổi quyền sở hữu giữa các cá nhân hoặc nhóm, vì vậy nếu bạn tạo một chìa khóa API dưới tài khoản của riêng bạn, bạn không thể sử dụng nó để quản lý tài sản nhóm.

Bất kể bạn đang tạo chìa khóa API cho bản thân hay nhóm của mình, 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 Đọc và Viết quyền hoạt động cho trải nghiệm được chọn của bạn, tùy thuộc vào phạm vi cần thiết của các điểm cuối bạn dự định gọi.

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

Example API Request Header
--header 'x-api-key: ${ApiKey}' \

Ứng dụng OAuth 2.0

Để sử dụng API cho ứng dụng OAuth 2.0 bên thứ ba, thêm 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 bạn dự định sử dụng.

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

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

1. Sao chép chìa 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 và miêu tả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 riêng mình , thêm ID người dùng của bạn.Bạn có thể tìm ID người dùng của mình trên URL của hồ sơ Roblox của bạn.Ví dụ, cho 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 , thêm ID nhóm của nhóm của bạn.Bạn có thể tìm ID nhóm trên URL của trang nhóm của bạn.Ví dụ, cho https://www.roblox.com/groups/7654321/example-group#!/ , ID nhóm là 7654321 .
   4. Thêm đường dẫn tập tin và loại nội dung của tài sản.

   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}\" # 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 chìa 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. Di chuyển đến trang Tạo của Bảng điều khiển Nhà sáng tạo .
   2. Chọn danh thể loại Vật phẩm Phát triển .
   3. Chọn danh mục của tài sản và tìm tài sản mục tiêu.
   4. Chuyển qua hình ả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 các tùy chọn, sau đó chọn Sao chép ID tài sản từ danh sách.

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

Lấy lại tình trạng hoạt động của tài trạng thái

Nếu yêu cầu 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 trong định dạng { "path": "operations/${operationId}" } .Bạn có thể sử dụng nó để kiểm tra tình trạng 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 chìa khóa API vào tiêu đề yêu cầu x-api-key của phương pháp Nhận hoạt động và gửi yêu cầu, giống như mẫu mã sau:

   Example Request for Get Operation
   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 đã tải lên hoặc một status giải thích lý do tài sản tải lên thất bại như ví dụ mã code sau đây cho thấy:

   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. (Opcional) Kiểm tra tài sản được tạo trên tài khoản Roblox của bạn.

   1. Điều hướng đến trang Kho hàng 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 ảnh thumbnail để 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 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 cấp , chọn tài sản:đọc và tài sản:viết phạm vi.

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

   https://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. Khi gửi yêu cầu, bao gồm token truy cập trong tiêu đề xác nhậ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 đây cho thấy một yêu cầu mẫu để tải lên một tài sản mới:

   Yêu cầu ví dụ
   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"'