รูปแบบ

หน้านี้ให้คำอธิบายเกี่ยวกับรูปแบบทั่วไปของ Open Cloud API โดยเฉพาะเกี่ยวกับการสร้างคำขอและการจัดการการตอบกลับ

เส้นทาง

เพื่อสร้างคำขอให้กับ Open Cloud APIs คุณต้องมี URL ก่อน URL นี้คือการผสานรวมของ URL เบื้องต้น ( https://apis.roblox.com/cloud/v2 ) เส้นทาง Open

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

หลายเส้นทางรวมทั้งตัวอย่างด้านบนมี ตัวประกาศผู้ใช้ ที่กำหนดโดยเครื่องหมายกรอบเว้นวรรคในส่วนข้อมูลอ้างอิง API Path ประกาศผู้ใช้เป็นตัวแปรที่คุ

ทรัพยากรบางรายการมีรูปเส้นทางหลายเส้นทางที่มองเห็นได้ภายใต้ เส้นทางทรัพยากร หัวข้อใน API อ้างอิง โดยปกติ URL สำหรับ รายการการจํากัดผู้ใช้ กำลังติดตาม:

• 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

คุณอาจสามารถเดาความแตกต่างระหว่างสองสิ่งนี้ได้: ผู้ใช้บางคนมีข้อจำกัดบางอย่างสำหรับจักรวาลทั้งหมด (ประสบการณ์) ในขณะที่คนอื่นใช้กับสถานที่เฉพาะในจักรวาล

หลาย API ส่งเส้นทางเป็นส่วนหนึ่งของการตอบกลับของพวกเขาซึ่งคุณสามารถใช้เพื่อสร้างคำขอต่อไป หาก API ต้องใช้เวลามากกว่าสองวินาทีในการประมวลผลคำขอ มันจะส่งคืน การดำเนินการ แทนที่จะ

ความยาวและประเภทของเนื้อหา

การโทร API จำนวนมาก ร่างกายJSON หนึ่ง ร่างกายให้แน่ใจว่าจะรวม Content-Length และ Content-Type หัวข้อสูตรในส่วนหัวข้อของ HTTP ส่ว

การจัดหน้า

หากคุณระบุ maxPageSize ในคำขอของคุณบางวิธีจะกลับผลลัพธ์ที่ประกอบด้วยหน้าหลายหน้า:

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

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

หากคำตอบมีค่าสำหรับ nextPageToken ให้ใช้ค่านั้นในตัวแปร pageToken ของคำขอต่อไปเพื่อดึงหน้าต่อไป เมื่อ nextPageToken ว่างเปล่าคุณจะได้รับสิ้นสุดของผลลัพธ์ของคุณ:

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

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

นอกเหนือจาก pageToken คุณต้องใช้คำถามเดียวกันเพื่อให้การจัดเรียงหน้าเว็บทำงานได้อย่างถูกต้อง การเปลี่ยนแปลงตัวแปรใด ๆ จะส่งผลในข้อผิดพลาด 400

การปฏิบัติงานที่ยืดเยื้อ

วิธีบางวิธีกลับมาเป็นวัตถุ Operation ที่แทนที่คำขอที่ดำเนินอยู่เป็นระยะเวลานานที่จะกลับมาให้คำตอบแบบเร็วขึ้นในภายหลัง วิธีนี้มีสาขาต่อไปนี้:

• เส้นทาง - เส้นทางสิ้นสุดที่เรียกสำหรับการโหลดสำเร็จ แนบเส้นทางไปยังทรัพยากรเมื่อวิธีการร้องขอ
• เสร็จสิ้น - ค่าตัวละครที่แทนที่ว่าการดำเนินการนี้เสร็จสิ้นหรือไม่
• ตอบสนอง - ตัวตอบสนอง ฟิลด์นี้ว่างจนกว่าฟิลด์ done จะมีค่าของ true
• ข้อมูลอ้างอิง - ข้อมูลอ้างอิงที่กำหนดเฉพาะต่อคำขอที่กำลังทำ

ตัวอย่างวัตถุการปฏิบัติการ
{
  "path": "v1/assets/12345/operation/xyz",
  "done": true,
  "response": {
    "value1": "myValue",
    "value2": 1234
  },
  "metadata": {
    "metadata1": "string",
    "metadata2": 5678
  }
}

ใช้เส้นทางของวัตถุ Operation เพื่อสำรวจเมื่อทรัพยากรพร้อม กลยุทธ์ที่ดีคือใช้ exponential backoff ตัวอย่างเช่นคุณอาจสำรวจได้ทันทีแล้วหลังจากนั้นสองวินาทีสองวินาทีสี่วินาทีเป็นต้น

def PollForResults(operationPath):
    currentRetries = 0
    maxRetries = 10
    retryPollingDelay = 1
    retryPollingMultiplier = 2
    while (currentRetries < maxRetries):
        # ไม่มีความล่าช้าในการตรวจสอบครั้งแรก
        if (currentRetries == 0):
            results = GetOperation(operationPath)
        # ทดสอบโลกิตติอีกครั้งสำหรับการตรวจสอบต่อไป
        else:
            time.sleep(retryPollingDelay)
            results = GetOperation(operationPath)
            # การลดลงอย่างเชิญชวน
            retryPollingDelay *= retryPollingMultiplier
        # ตรวจสอบผลลัพธ์และกลับมาหากพบ
        if (results.status_code != 200 or results.json()[doneJSONKey]):
            return results
        # ในกรณีอื่น เพิ่มจำนวนการลองใหม่
        else:
           currentRetries += 1

สำหรับตัวอย่างโค้ดที่สมบูรณ์แบบที่ใช้ระยะเวลาการทดลองที่แน่นอนมากขึ้นแทนที่จะเป็นของเชิญเพื่อผลลัพธ์ ดู การโพลลิ่งสำหรับผลลัพธ์

การกรอง

บางวิธีช่วยให้คุณกรองการตอบกลับด้วยการรวมปารามิเตอร์ filter ในคำขอ ส่วนต่อไปนี้อธิบายวิธีการใช้ภาษาการกรองและแนวทางสำหรับเวลาที่กำหนด

รายชื่อการเป็นสมาชิกกลุ่ม

ตัวละคร wildcard - สามารถใช้แทนรหัสกลุ่มเพื่อรวบรวมสมาชิกในกลุ่มทั้งหมด: groups/-/memberships

การกรองสอดคล้องกับภาษาทั่วไป (CEL) เท่านั้น มีเพียงสองตัวผู้ประกอบการที่สนับสนุน:

• ==
• in [...]

หากคุณระบุรหัสกลุ่มในเส้นทางทรัพยากรคุณสามารถกรองสมาชิกโดยผู้ใช้หรือบทบาทในรูปแบบต่อไปนี้:

• กรองผู้ใช้ : filter="user == 'users/9876543210'"
• กรองบทบาท : filter="role == 'groups/123/roles/7920705'"

หากคุณระบุตัวละครดาวเหนือกลุ่มสำหรับรหัสกลุ่ม คุณต้องกรองสมาชิกโดยผู้ใช้ (ได้ถึง 50) ในรูปแบบต่อไปนี้:

• กรองผู้ใช้ : filter="user in ['users/1', 'users/156', 'users/9876543210', ...]"

รายการรายการ

คุณสามารถกรองโดยสถานะที่เก็บได้ พิมพ์และรหัสไอเท็มสินค้าคงคลัง หากคุณไม่ให้กรอง ตัวกรอง

รูปแบบตัวกรองเป็นรายการที่แยกกับจุลภาค:

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

• {field} สามารถเป็นหนึ่งในสามาตรประเภทหรือสามารถเป็น ID ในตารางต่อไปนี้
• {value} สามารถเป็นสตริง บูเครามต์ หรือรายการ พิมพ์นี่สามารถเป็นค่าเดียว (ฟิลด์บูเครามต์) หรือหลายค่า (รายการฟิลด์)

ประเภทข้อมูล

| กรอง | ประเภท | คำอธิบาย | ค่าเริ่มต้น | เท่านั้น | เท่านั้น | เท่านั้น | เท่านั้น | เท่านั้น | เท่านั้น | เท่านั้น | เท่

ตัวตรรจุรหัส

| กรอง | ประเภท | คำอธิบาย | | |

ตัวอย่าง

• คืนค่ารายการที่เก็บทั้งหมดที่ผู้ใช้เป็นเจ้าของ:

  filter=onlyCollectibles=true;inventoryItemAssetTypes=*

• คืนค่ารายการทั้งหมดของชนิดที่กำหนด:

  filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY

• กลับรายการทุกรายการของรายการชนิดหรือบัตรผ่านเกมใด ๆ รวมถึงเหรียญจากผลลัพธ์ (พฤติกรรมเดียวกันเมื่อ badges ไม่ได้รวมอยู่ในตัวกรอง):

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

• ส่งคืนสินทรัพย์ที่ตรงกับรหัสที่กำหนด:

  filter=assetIds=1,2,3,4

• ส่งคืนสินทรัพย์ เหรียญตรา บัตรผ่านเกม และเซิร์ฟเวอร์ส่วนตัวที่ตรงกับรหัสที่ระบุไว้:

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