Mô hình

Trang này đề cập đến các mô hình phổ biến với các API Open Cloud, đặc biệt là xung quanh việc thực hiện các yêu cầu và xử lý các phản hồi.

Đường dẫn

Để thực hiện một yêu cầu đến các API Open Cloud, bạn phải trước tiên tạo một URL. URL này là sự kết hợp của URL cơ sở (ví dụ: https://apis.roblox.com), đường dẫn API Open Cloud (ví dụ: /cloud/v2/universes/{universe_id}/places/{place_id}/user-restrictions), và bất kỳ tham số truy vấn nào (ví dụ: ?maxPageSize=25). Một URL yêu cầu đầy đủ có thể trông như thế này:

https://apis.roblox.com/cloud/v2/users/4687549151/inventory-items?maxPageSize=100

Nhiều đường dẫn, bao gồm ví dụ ở trên, có các tham số đường dẫn, được chỉ định bằng dấu ngoặc nhọn trong tài liệu API. Các tham số đường dẫn chỉ là các biến mà bạn chèn vào trước khi thực hiện yêu cầu và gần như luôn luôn là các ID: ID người dùng, ID nhóm, ID địa điểm, v.v. ID thường là số, nhưng không nhất thiết; ví dụ, ID cửa hàng dữ liệu và cửa hàng bộ nhớ hỗ trợ một tập hợp ký tự rộng hơn.

Độ dài và loại nội dung

Nhiều cuộc gọi API, đặc biệt là những cuộc gọi tạo hoặc cập nhật, yêu cầu một thân yêu cầu JSON. Nếu yêu cầu của bạn có một thân, hãy chắc chắn bao gồm các tiêu đề Content-Length và Content-Type. Hầu hết các máy khách HTTP tự động thêm những tiêu đề này.

Phân trang

Nếu bạn chỉ định maxPageSize trong yêu cầu của bạn, một số phương thức sẽ trả về các kết quả phân trang - về cơ bản là các phản hồi một phần:

GET /cloud/v2/users/{user_id}/inventory-items?maxPageSize=25

{
  "inventoryItems": [
    ...
  ],
  "nextPageToken": "aaaBBB"
}

GET /cloud/v2/universes/{universe_id}/data-stores?maxPageSize=25

{
  "dataStores": [
    ...
  ],
  "nextPageToken": "datastore1"
}

Nếu một phản hồi bao gồm giá trị cho nextPageToken, hãy sử dụng giá trị đó trong tham số pageToken của yêu cầu tiếp theo để lấy trang tiếp theo. Khi nextPageToken trống hoặc hoàn toàn bị bỏ qua, bạn đã đến cuối các kết quả của mình:

GET /cloud/v2/users/{user_id}/inventory-items?maxPageSize=25&pageToken=aaaBBB

{
  "inventoryItems": [
    ...
  ],
  "nextPageToken": ""
}

GET /cloud/v2/universes/{universe_id}/data-stores?maxPageSize=25&pageToken=datastore1

{
  "dataStores": [
    ...
  ]
}

Ngoài tham số pageToken, bạn phải sử dụng cùng một truy vấn để phân trang hoạt động đúng cách. Việc thay đổi bất kỳ tham số bộ lọc nào cũng dẫn đến lỗi 400.

Open Cloud v2

Nhiều đường dẫn

Một số tài nguyên có nhiều mẫu đường dẫn, có thể thấy dưới tiêu đề Đường Dẫn Tài Nguyên trong tài liệu API. Ví dụ, URL cho Danh sách Các Giới Hạn Người Dùng có thể là một trong hai:

• https://apis.roblox.com/cloud/cloud/v2/universes/{universe_id}/user-restrictions
• https://apis.roblox.com/cloud/cloud/v2/universes/{universe_id}/places/{place_id}/user-restrictions

Bạn có thể suy ra sự khác biệt giữa hai cái này: một số giới hạn người dùng áp dụng cho toàn bộ vũ trụ (trò chơi), trong khi những cái khác áp dụng cho các địa điểm cụ thể trong một vũ trụ. Ngoài sự bổ sung nhỏ vào đường dẫn và tham số đường dẫn bổ sung, các cuộc gọi là giống hệt nhau.

Nhiều điểm cuối trả về một đường dẫn như một phần của phản hồi của chúng, mà bạn có thể sử dụng để thực hiện các yêu cầu tiếp theo. Nếu một API cần hơn vài giây để hoàn thành một yêu cầu, nó thường trả về một hoạt động thay vì tài nguyên hoặc phản hồi chính nó.

Các hoạt động dài hạn

Một số phương thức trả về một đối tượng Operation đại diện cho một yêu cầu dài hạn mà trả về một phản hồi không đồng bộ sau. Đối tượng chứa các trường sau:

• path - Đường dẫn điểm cuối cần gọi để kiểm tra xem yêu cầu đã hoàn thành hay chưa. Ghi đính đường dẫn vào URL cơ sở ban đầu của phương thức tài nguyên.
• done - Một giá trị boolean cho biết liệu hoạt động đã hoàn thành hay chưa.
• response - Đối tượng phản hồi. Trường này trống cho đến khi trường done có giá trị là true.
• metadata - Siêu dữ liệu tùy chỉnh đặc trưng cho yêu cầu đang được thực hiện.

Ví dụ Đối Tượng Hoạt Động
{
  "path": "v1/assets/12345/operation/xyz",
  "done": true,
  "response": {
    "value1": "myValue",
    "value2": 1234
  },
  "metadata": {
    "metadata1": "string",
    "metadata2": 5678
  }
}

Sử dụng đường dẫn của đối tượng Operation để kiểm tra khi tài nguyên đã sẵn sàng. Một chiến lược tốt là sử dụng hồi tiếp mũ. Ví dụ, bạn có thể kiểm tra ngay lập tức, rồi sau một giây, hai giây, bốn giây, v.v.

def PollForResults(operationPath):
    currentRetries = 0
    maxRetries = 10
    retryPollingDelay = 1
    retryPollingMultiplier = 2
    while (currentRetries < maxRetries):
        # Không có độ trễ trong lần kiểm tra đầu tiên
        if (currentRetries == 0):
            results = GetOperation(operationPath)
        # Logic thử lại cho các kiểm tra sau
        else:
            time.sleep(retryPollingDelay)
            results = GetOperation(operationPath)
            # Hồi tiếp mũ
            retryPollingDelay *= retryPollingMultiplier
        # Kiểm tra kết quả và trả về nếu nó tồn tại
        if (results.status_code != 200 or results.json()[doneJSONKey]):
            return results
        # Nếu không, tăng số lần thử
        else:
            currentRetries += 1

Để xem một mẫu mã hoàn chỉnh hơn sử dụng một khoảng thời gian thử lại cố định thay vì hồi tiếp mũ, hãy xem Kiểm Tra Kết Quả.

Lọc

Một số phương thức cho phép bạn lọc phản hồi bằng cách bao gồm tham số filter trong yêu cầu. Các phần sau mô tả cú pháp và hướng dẫn bộ lọc cho các điểm cuối đã chỉ định.

Danh sách tư cách thành viên nhóm

Ký tự đại diện - có thể được sử dụng thay cho ID nhóm để liệt kê các tư cách thành viên qua tất cả các nhóm: groups/-/memberships.

Việc lọc tuân theo Ngôn ngữ Biểu thức Chung (CEL). Chỉ có hai toán tử được hỗ trợ:

• ==
• in [...]

Nếu bạn chỉ định một ID nhóm trong đường dẫn tài nguyên, bạn có thể lọc tư cách thành viên bằng cách sử dụng người dùng hoặc vai trò theo các định dạng sau:

• Bộ lọc người dùng: filter=user == 'users/9876543210'
• Bộ lọc vai trò: filter=role == 'groups/123/roles/7920705'

Nếu bạn chỉ định ký tự đại diện cho ID nhóm, bạn phải lọc tư cách thành viên theo người dùng (tối đa 50) theo định dạng sau:

• Bộ lọc người dùng: filter=user in ['users/1', 'users/156', 'users/9876543210', ...]

Danh sách mục hàng tồn kho

Bạn có thể lọc theo trạng thái thu thập, loại mục hàng tồn kho, và ID mục hàng tồn kho. Nếu bạn không cung cấp bộ lọc, toàn bộ hàng tồn kho của người dùng sẽ được trả về.

Định dạng bộ lọc là danh sách phân cách bằng dấu chấm phẩy:

filter={field}={value};{field}={value},{value},...;{field}=...

• {field} có thể là bất kỳ trường loại định nghĩa trước nào hoặc trường ID trong các bảng sau.
• {value} có thể là một chuỗi, boolean, hoặc enum. Tùy thuộc vào loại trường, điều này có thể là một giá trị duy nhất (các trường boolean) hoặc nhiều giá trị (các trường danh sách).

Các trường loại

Các trường ID

Ví dụ

• Trả về tất cả các mục thu thập mà người dùng sở hữu:

  filter=onlyCollectibles=true;inventoryItemAssetTypes=*

• Trả về tất cả các mục của các loại đã chỉ định:

  filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY

• Trả về tất cả các mục của các loại đã liệt kê hoặc bất kỳ thẻ trò chơi nào. Loại trừ huy hiệu khỏi các kết quả (hành vi tương tự như nếu badges không được bao gồm trong bộ lọc):

  filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY;gamePasses=true;badges=false

• Trả về các tài sản khớp với các ID đã chỉ định:

  filter=assetIds=1,2,3,4

• Trả về các tài sản, huy hiệu, thẻ trò chơi và máy chủ riêng khớp với các ID đã chỉ định:

  filter=assetIds=1,2,3,4;badgeIds=1,2,3,4;gamePassIds=1,2,3,4;privateServerIds=1,2,3,4