Mẫu

*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 gửi yêu cầu và xử lý phản hồi.

Con đường

Để gửi yêu cầu đến Open Cloud APIs, bạn phải trước tiên tạo một URL.Địa chỉ URL này là sự kết hợp của URL cơ bản ( https://apis.roblox.com/cloud/v2 ), con đường API Mở đám mây ( ví dụ, /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 con đường, bao gồm ví dụ trên, có tham số con đường , được chỉ định bởi dấu ngoặc tròn trong tham chiếu API.Tham số đường dẫn chỉ là các biến mà bạn chèn trước khi thực hiện yêu cầu và hầu như luôn là ID: ID người dùng, ID nhóm, ID địa điểm, v.v.Các ID thường là số, nhưng không nhất thiết; ví dụ, ID của kho dữ liệu và kho bộ nhớ hỗ trợ một bộ nhân cài đặtrộng hơn.

Một số tài nguyên có nhiều mẫu đường dẫn, có thể nhìn thấy dưới tiêu đề Con đường tài nguyên trong API tham khảo.Ví dụ, URL cho Giới hạn người dùng danh sách có thể là một trong những 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ể suy ra 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ộ vũ trụ (trải nghiệm), trong khi những người khác áp dụng cho các địa điểm cụ thể trong vũ trụ.Ngoài việc thêm nhỏ vào con đường và tham số con đường bổ sung, các cuộc gọi giống nhau.

Nhiều API trả về một con đường như một phần của phản hồi của họ, mà bạn có thể sử dụng để đưa ra các yêu cầu tiếp theo.Nếu một API cần nhiều hơn vài giây để hoàn thành 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.

Chiều dài và đánh máynộ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ó 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 khách hàng HTTP thêm các tiêu đề này tự động.

Trang số hóa

Nếu bạn xác định maxPageSize trong yêu cầu của bạn, một số phương pháp trả về kết quả được phân trang - về cơ bản là 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 một 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 bị bỏ hoàn toàn, bạn đã đến hết kết quả của bạn:

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 pageToken , bạn phải sử dụng cùng một truy vấn cho việc phân trang hoạt động đúng. Thay đổi bất kỳ tham số bộ lọc nào dẫn đến lỗi 400.

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

Một số phương pháp trả về một đối tượng Operation đại diện cho một yêu cầu dài chạy mà trả lời đồng bộ sau này.Vật phẩm bao gồm các trường sau:

  • con đường - Con đường cuối cùng để gọi để bỏ phiếu cho hoàn thành yêu cầu. Thêm con đường vào URL nguyên bản của phương pháp tài nguyên.
  • hoàn thành - Giá trị boolean đại diện cho việc có hay không có hoạt động đã hoàn thành.
  • phản hồi - Đố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 - metadata tùy chỉnh cho yêu cầu đang được thực hiện.
Ví dụ vật phẩm hoạt động
{

  "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 đối tượng Operation để thu thập khi nguồn lực sẵn sàng.Một chiến lược tốt là sử dụng quay lại exponential.Ví dụ, bạn có thể bỏ phiếu ngay lập tức, 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)

        # Thử lại logic cho các kiểm tra tiếp theo

        else:

            time.sleep(retryPollingDelay)

            results = GetOperation(operationPath)

            # Quay lại nhân lũy

            retryPollingDelay *= retryPollingMultiplier

        # Kiểm tra kết quả và trả về nếu chúng 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ử lại

        else:

           currentRetries += 1

Đối với một ví dụ mã hoàn chỉnh hơn sử dụng khoảng thời gian thử lại cố định thay vì quay lại theo cấp số nhân, xem Khảo sát kết quả.

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 tham số filter trong yêu cầu.Các phần sau đây mô tả ngữ pháp lọc và hướng dẫn cho các điểm cuối được chỉ định.

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

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

Lọc phù hợp với Ngôn ngữ Biểu hiện Chung (CEL). Chỉ hai operator được hỗ trợ:

  • ==
  • in [...]

Nếu bạn xác định một ID nhóm trong đường dẫn tài nguyên, bạn có thể lọc thành viên bằ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 xác định nhân vật hoang dã cho ID nhóm, bạn phải lọc thành viên bởi người dùng (lên đến 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 vật phẩm kho hàng

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

Định dạng bộ lọc là một danh sách tách bởi dấu phân cách:

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

  • {field} có thể là bất kỳ trường loại hoặc trường ID được định trước nào 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).

Loại trường

| Lọc | Loại | Mô tả | | :------------------------ | :------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | badges | boolean | Bao gồm thẻ trong phản hồi.Mặc định là false. | | gamePasses | boolean | Bao gồm game passes trong phản hồi.Mặc định là false. | | inventoryItemAssetTypes | Xem chi tiết tài sản để có toàn bộ danh sách các loại tài sản.| Danh sách phân tách bằng phím của các loại tài sản cần bao gồm.Default là không có.Xác định * cho tất cả các loại tài sản.Phải có phạm vi đọc kho hàng để lọc bởi nơi đã mua. | | onlyCollectibles | boolean | Bao gồm chỉ các món đồ sưu tầm trong phản hồi.Mặc định là false.Trường này phải được sử dụng với trường inventoryItemAssetTypes để trả về các mục và chỉ trả về các mục giới hạn không phải UGC.| | privateServers | boolean | Bao gồm máy chủ riêng trong phản hồi.Mặc định là false.Phải có phạm vi đọc kho hàng để lọc bởi trường này. |

Các trường ID

| Lọc | Loại | Mô tả | | :----------------- | :----- | :--------------------------------------------------------------------------------------------------------------------- | | assetIds | chuỗi | Danh sách chia cách bằng dấu phân cách các ID tài sản số để bao gồm. | | badgeIds | chuỗi | Danh sách chia cách bằng dấu phân cách các ID nhãn số cần bao gồm. | | gamePassIds | chuỗi | Danh sách tách bởi dấu phân cách các ID trò chơi số cần bao gồm. | | privateServerIds | chuỗi | Danh sách tách bởi dấu phân cách các ID máy chủ riêng tư có chứa.Phải có phạm vi đọc kho hàng để lọc bởi trường này. |

Ví dụ

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

    filter=onlyCollectibles=true;inventoryItemAssetTypes=*

  • Trả lại tất cả các mục của loại được chỉ định:

    filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY

  • Trả lại tất cả các mục của các loại được liệt kê hoặc bất kỳ thẻ trò chơi nào.Bỏ danh hiệu khỏi kết quả (cùng hành vi 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ả lại các tài sản phù hợp với các ID được chỉ định:

    filter=assetIds=1,2,3,4

  • Trả lại tài sản, huy hiệu, vé trò chơi và máy chủ riêng phù hợp với các ID được đặc trưng:

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