รูปแบบ

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

เส้นทาง

เพื่อทำคำขอไปยัง Open Cloud APIs คุณต้องสร้าง URL ก่อน URL นี้เป็นการรวมกันของ base URL (เช่น https://apis.roblox.com), เส้นทาง Open Cloud API (ตัวอย่างเช่น /cloud/v2/universes/{universe_id}/places/{place_id}/user-restrictions) และพารามิเตอร์ค้นหา (ตัวอย่างเช่น ?maxPageSize=25) URL คำขอทั้งหมดอาจมีลักษณะดังนี้:

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

หลายเส้นทางรวมถึงตัวอย่างข้างต้นมี พารามิเตอร์เส้นทาง ซึ่งกำหนดโดยปีกกาในเอกสาร API พารามิเตอร์เส้นทางเป็นแค่ตัวแปรที่คุณแทรกก่อนทำคำขอและมักจะเป็น ID: user ID, group ID, place ID เป็นต้น IDs มักจะเป็นตัวเลข แต่ไม่จำเป็นต้องเป็นเช่นนั้น; ตัวอย่างเช่น ID ของ data store และ memory store สนับสนุนชุดตัวอักษรที่กว้างขึ้น

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

การเรียก API หลายรายการ โดยเฉพาะอย่างยิ่งที่สร้างหรืออัพเดต ต้องใช้ JSON request body หากคำขอของคุณมี body ให้แน่ใจว่าได้รวม Content-Length และ Content-Type headers ส่วนใหญ่ของ HTTP clients จะเพิ่ม headers เหล่านี้โดยอัตโนมัติ

การแบ่งหน้า

หากคุณระบุ maxPageSize ในคำขอของคุณ บางวิธีจะส่งคืนผลลัพธ์ที่แบ่งหน้า—เป็นการตอบสนองแบบบางส่วน:

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"
}

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

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": [
    ...
  ]
}

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

Open Cloud v2

เส้นทางหลายเส้น

ทรัพยากรบางอย่างมีรูปแบบเส้นทางหลายรูปแบบปรากฏอยู่ภายใต้หัวข้อ Resource Paths ในเอกสาร API สำหรับตัวอย่าง URL สำหรับ List User Restrictions สามารถเป็นหนึ่งในสองทางต่อไปนี้:

• 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 ต้องการเวลามากกว่าหลายวินาทีในการดำเนินการคำขอ มักจะส่งคืน operation แทนทรัพยากรหรือการตอบสนองเอง

การดำเนินการที่ใช้เวลานาน

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

• path - เส้นทางเอนด์พอยต์ที่จะเรียกเพื่อตรวจสอบสถานะการดำเนินการ ถอดรหัสเส้นทางไปยัง base URL ดั้งเดิมของวิธีทรัพยากร
• done - ค่า boolean ที่แสดงว่าออปเรชันได้เสร็จสิ้นหรือไม่
• response - วัตถุการตอบสนอง ฟิลด์นี้จะว่างเปล่าจนกว่าจะมีค่า true ในฟิลด์ done
• metadata - เมตาดาต้าส่วนบุคคลที่เฉพาะเจาะจงกับคำขอที่กำลังดำเนินการ

Example Operation Object
{
  "path": "v1/assets/12345/operation/xyz",
  "done": true,
  "response": {
    "value1": "myValue",
    "value2": 1234
  },
  "metadata": {
    "metadata1": "string",
    "metadata2": 5678
  }
}

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

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

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

การกรอง

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

รายการสมาชิกกลุ่ม

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

การกรองเป็นไปตาม Common Expression Language (CEL) โดยรองรับเพียงสองตัวดำเนินการ:

• ==
• in [...]

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

• User filter: filter=user == 'users/9876543210'
• Role filter: filter=role == 'groups/123/roles/7920705'

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

• User filter: filter=user in ['users/1', 'users/156', 'users/9876543210', ...]

รายการรายการสินค้าคงคลัง

คุณสามารถกรองตามสถานะของของสะสม ประเภทของรายการในคลัง และ ID ของรายการในคลัง หากคุณไม่ให้การกรอง จะคืนสินค้าคงคลังทั้งหมดของผู้ใช้

รูปแบบการกรองเป็นรายการที่คั่นด้วยเครื่องหมายเซมิโคลอน:

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

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

ฟิลด์ประเภท

ฟิลด์ ID

ตัวอย่าง

• คืนค่าทุกรายการสะสมที่ผู้ใช้เป็นเจ้าของ:

  filter=onlyCollectibles=true;inventoryItemAssetTypes=*

• คืนค่าทุก items ของประเภทที่ระบุ:

  filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY

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

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

• คืนค่าอสังหาริมทรัพย์ที่ตรงตาม ID ที่ระบุ:

  filter=assetIds=1,2,3,4

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

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