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

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

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

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

Đối với các điểm cuối không tạo một tài nguyên mới hoặc cập nhật nội dung của tài nguyên hiện tại, không có hạn chế và giới hạn. Tuy nhiên, chức năng tải nội dung tài nguyên bằng các điểm tạ

Cài đặt an toàn

API hỗ trợ cả sử dụng bên thứ ba với API key authorization và sử dụng bên thứ ba trong OAuth 2 applications . Mỗi cách yêu cầu các cài đặt quyền truy cập khác nhau.

Chìa khóa API

Để sử dụng API trong các tập lệnh hoặc công cụ của riêng nhóm, bạn cần phải Tạo một chìa khóa API cho phép bạn quản lý tài nguyên và bảo mật. Để quản lý tài nguyên mà bạn sở hữu riêng tư, bạn cần phải Tạ

Một khi bạn tạo một chìa khóa API, bạn không thể chuyể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 nguyên nhóm.

Bất kể bạn có tạo API Key cho chính mình hay cho nhóm của mình, hãy chắc chắn để thêm các quyền của sau:

1. Thêm tài sản vào quyền truy cập Permissions .
2. Thêm Đọc và Viết quyền truy cập cho mô tả trải nghiệm của bạn, tùy thuộc vào các khoảng cách yêu cầu của các đầu mối bạn chọn.

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

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

OAuth 2.0 ứng dụng

Để 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 asset:read và asset:write cho phép khi đăng nhập ứng dụng của bạn. Chọn các phạm based on the requirements of the endpoints bạn kế hoạch sử dụng.

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

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

1. Bản sao chìa khóa API lên đầu tiêu đề x-api-key của điểm 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à miêu tảtả tài sản của bạn.
   3. Thêm thông tin người sáng tạo.

      • Nếu bạn muốn tạo tài sản trên behalf của riêng bạn , 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 hồ sơ Roblox của bạn. Ví dụ, cho https://www.roblox.com/users/1234567/profile
      • Nếu bạn muốn tạo tài nguyên như tài nguyên nhóm , hãy thêm ID nhóm của nhóm của bạn. Bạn có thể tìm thấy ID nhóm trên trang web của nhóm của bạn. Ví dụ, cho https://www.roblox.com/groups/7654321/Example
   4. Thêm con đường dữ liệu và loại nội dung của tài sản của bạ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 nguyên nhóm
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

Cập Nhật Tài Sản Hiện Tồn

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

1. Bạn bèCopy the API key to the x-api-key request header of the Update Asset endpoint.
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. Chuyển đến trang Tạo hình của Bảng điều khiển của người 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 của bạn và tìm tài sản mục tiêu.
   4. Bỏ chuột lên bản xem trước của tài nguyên mục tiêu và nhấp vào nút ⋯ để hiển thị một danh sách lựa chọn, sau đó chọn Nhân bản ID 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 tình trạng hoạt động của tài nguyên

Nếu yêu cầu của bạn để tạo một tài nguyên mới hoặc cập nhật tài nguyên hiện tại thành công, nó sẽ trả lại một mã hành động trong 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 bản tải của bạ

1. Bắt chìa khóa API lên đầu tiêu đề yêu cầu của x-api-key yêu cầu API và gửi yêu cầu, như mẫu mã sau đây:

   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ó sẽ trả một Operation đối tượng, bao gồm một response đại diện cho thông tin tải tài sản đã tải hoặc một status để giải thích tại sao tải tài sản không thành công như mẫu mã 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. (Tùy chọn) Kiểm tra tài nguyên đã tạo trên tài khoản Roblox của bạn.

   1. Chuyển đến trang Inventory của Roblox account của bạn.
   2. Chọn Thể loại của tài sản bạn muốn kiểm tra.
   3. Tìm tài nguyên mục tiêu và nhấp vào hình ảnh thumbnail để xem tài nguyê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 nguyên để cho phép người dùng tải và cập nhật tài nguyê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 truy cập từ người dùng của bạn, thực hiện các cài đặt sau đây:

1. Khi đăng nhập ứng dụng của bạn , dưới quyền truy cập , hãy chọn tài sản:đọc và 1> tài sản:ghi쓰1> scope.

2. Khi thực hiện dòng chảy ủy quyền , bao gồm asset:read và asset:write như mục tiêu của phần 1>ứng dụng1> đó là chuyển người dùng trở lại ứng dụng của bạn, như ví dụ sau:

   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. Khi gửi yêu cầu, bao gồm token truy cập trong trụ cấp quyền của yêu cầu và dữ liệu biểu tượng trong trụ tài sản để tạo hoặc cập nhật trong yêu cầu UI. Các ví dụ sau đây cho thấy một mẫu yêu cầu cho việc tải 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"'