Muster

*Nội dung này được dịch bằng AI (Beta) và có thể có lỗi. Để xem trang này bằng tiếng Anh, hãy nhấp vào đây.

Trang này bao gồm các mẫu thông thường với Open Cloud APIs, đặc biệt là xung quanh việc tạo các yêu cầu và xử lý các phản hồi.

Con đường

Để gửi một yêu cầu đến Open Cloud APIs, bạn phải đầu tiên tạo một URL. URL này là một kombin của URL cơ sở ( https://apis.roblox.com/cloud/v2), con đường Open Cloud API (như ví dụ, <

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

Nhiều con đường, bao gồm ví dụ trên, có các tham số con đường , được xác định bằng các dấu chấm câu trong tham khảo API. Các tham số con đường là chỉ các biến mà bạn thêm trước khi thực hiện yêu cầu và thường là ID: ID ngư

Một số nguồn có nhiều mô hình đường đi, có thể thấy dưới Paths người chơi list trong API tham khảo. Ví dụ, URL cho Cấm chặn người chơi có thể là một trong những mô hình theo dõi:

  • 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ể có thể tính toán sự khác biệt giữa hai: một số hạn chế người dùng áp dụng cho toàn bộ một vũ trụ (kinh nghiệm), trong khi những người khác áp dụng cho các nơi cụ thể trong một vũ trụ. Ngoài sự thêm nhỏ về con đường và tham số con đường bên ngoài, các gọi là tương tự.

Nhiều API trả về một con đường như một phần của phản hồi của họ, which you can use to make further requests. If an API needs more than a few seconds to fulfill a yêu cầu, it often returns an hành động rather than the resource or response itself.

Độ 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 tài nguyên, yêu cầu một cơ thânyêu cầu JSON. Nếu yêu cầu của bạn có cơ thân, hãy đảm bảo bao gồm các đầu mối Content-Length và Content-Type. Hầu hết các máy chủ HTTP thêm các

Trang chủ

Nếu bạn đặt maxPageSize trong yêu cầu của mình, một số phương thức trả kết quả bằng các trang bị tách biệt - thực tế là các trả lời bị tách biệt:

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



{

  "inventoryItems": [

    ...

  ],

  "nextPageToken": "aaaBBB"

}

Nếu một câu trả lời bao gồm giá trị cho nextPageToken , hãy sử dụng giá trị đó trong pageToken参数 của yêu cầu tiếp theo để lấy trang tiếp theo. Khi nextPageToken là trống, bạn đã đến kết quả của kết quả của bạn:

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



{

  "inventoryItems": [

    ...

  ],

  "nextPageToken": ""

}

Ngoài ra khỏi pageToken ', bạn phải sử dụng cùng một truy vấn để đảm bảo hoạt động của trang bị. Thay đổi bất kỳ tham số lọc nào kết quả trong một lỗi 400.

Các hoạt động chạy dài

Một số phương thức trả một Operation đối tượng đại diện cho một yêu cầu chạy lâu dài được trả lại một câu trả lời asynchronous sau đó. Đối tượng bao gồm các trường sau:

  • path - Đường dẫn đến kết thúc cuộc yêu cầusát. Kết hợp đường dẫn với nguồn URL gốc của phương pháp nguồn.
  • done - Một giá trị true hoặc false để biểu thị ap liệu có đã hoàn thành hay không.
  • response - Objeto de respuesta. This field is empty until the done field has a value of true .
  • metadata - Tùy chỉnh dữ liệu mục để đáp ứng yêu cầu đang được thực hiện.
Vật phẩm Ví dụ
{

  "path": "v1/assets/12345/operation/xyz",

  "done": true,

  "response": {

    "value1": "myValue",

    "value2": 1234

  },

  "metadata": {

    "metadata1": "string",

    "metadata2": 5678

  }

}

Sử dụng con đường của Operation đối tượng để khảo sát khi nguồn lực sẵn sàng. Một chiến lược tốt là sử dụng chiến lược chất béo trở lại. Ví dụ, bạn có thể khảo sát ngay lập tức, sau đó 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ễ đầu kiểm tra

        if (currentRetries == 0):

            results = GetOperation(operationPath)

        # Tiến hành lại logic cho các lần kiểm tra tiếp theo

        else:

            time.sleep(retryPollingDelay)

            results = GetOperation(operationPath)

            # Tốc độ trở lại

            retryPollingDelay *= retryPollingMultiplier

        # Kiểm tra kết quả và trả kết quả nếu có

        if (results.status_code != 200 or results.json()[doneJSONKey]):

            return results

        # Nếu không, tăng số lần thử lại

        else:

           currentRetries += 1

Đối với một mẫu mã hoàn chỉnh hơn sử dụng một lịch trình thử lại cố định chứ không phải là một lịch trình thử lại theo phương tiện truyền thông logit, xem Polling for Results .

Lọc

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

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

Nhân vật hoang dã - có thể được sử dụng thay vì ID nhóm để liệt kê thành viên trong tất cả các nhóm: groups/-/memberships .

Lọc được thiết lập cho Ngôn ngữ biểu hiện thông thường (CEL). Chỉ hỗ trợ hai trình duyệt:

  • ==
  • in [...]

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

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

Nếu bạn chỉ định nhân vật hoang dã cho ID nhóm, bạn phải lọc thành viên bằng cách người dùng (lên đến 50) trong hình dạng sau đây:

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

Danh sách vật phẩm

Bạn có thể lọc bởi tình trạng thu thập được, đánh máytài nguyên thu nhập, và mã tài nguyên. Nếu bạn không cung cấp một bộ lọc, toàn bộ kho tài nguyên của người dùng được trả lại.

Định dạng lọc là một danh sách câu hỏi:

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

  • {field} có thể là bất kỳ loại trường hợp nào trong số các trường hợp hệ thống đã định hoặc ID trường hợp.
  • {value} có thể là một chuỗi, một giá trị hoặc một danh sách. Tùy thuộc vào đánh máytrường, đây có thể là một giá trị duy nhất (trường kiểu true) hoặc nhiều giá trị (trường kiểu list).

Các trường

| Lọc | Loại | Mô tả | | :---------------- | | In

Trường ID

| Lọc | Loại | Mô tả | | | | | | | | | | | | | | | | | | |

Ví dụ

  • Quay lại tất cả các vật phẩm thu thập mà người dùng sở hữu:

    filter=onlyCollectibles=true;inventoryItemAssetTypes=*

  • Quay lại tất cả các mặt hàng của các loại được xác định:

    filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY

  • Trả lại tất cả các mặt hàng của các loại đã list hoặc bất kỳ game passes. Bỏ qua các hạng từ kết quả (như cùng một hành vi nếu badges không được bao gồm trong bộ lọc):

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

  • Đem lại các tài nguyên phù hợp với các ID được xác định:

    filter=assetIds=1,2,3,4

  • Đổi lại tài sản, huy hiệu, game passes và private server khớp IDs đã định:

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