รูปแบบ

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

เส้นทาง

เพื่อสร้างคำขอไปยัง API เมฆเปิด คุณต้องสร้าง URL ก่อนURL นี้เป็นการรวมของ URL เบื้องต้น ( https://apis.roblox.com/cloud/v2 ), เส้นทาง API เปิดคลาวด์ (ตัวอย่างเช่น, /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 เสมอ: รหัสผู้ใช้, รหัสกลุ่ม, รหัสสถานที่, ฯลฯรหัสประจำตัวมักจะเป็นตัวเลข แต่ไม่จำเป็นเสมอไป; ตัวอย่างเช่น ตั้งค่า

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

พิมพ์

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

การจัดหน้า

หากคุณระบุ 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

การดำเนินการที่ยาวนาน

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

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

ตัวอย่างวัตถุการดำเนินการ
{
  "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

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

การกรอง

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

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

ตัวละครไวด์การ์ด - สามารถใช้แทนรหัสกลุ่มเพื่อระบุสมาชิกในกลุ่มทั้งหมดได้: 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} สามารถเป็นฟิลด์ประเภทหรือฟิลด์รหัสที่กําหนดไว้ล่วงหน้าใดๆ ในตารางต่อไปนี้
• {value} สามารถเป็นสตริง บูลีน หรือเอนรูมได้ขึ้นอยู่กับประเภทฟิลด์นี้อาจเป็นค่าเดียว (ฟิลด์ boolean) หรือหลายค่า (ฟิลด์รายการ)

ชนิดฟิลด์

| กรอง | ประเภท | คําอธิบาย | | :------------------------ | :------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | badges | boolean | รวมเหรียญตราในคําตอบค่าเริ่มต้นคือเท็จ | | gamePasses | boolean | รวมผ่านเกมในคำตอบค่าเริ่มต้นคือเท็จ | | inventoryItemAssetTypes | ดู รายละเอียดสินทรัพย์ สำหรับรายการสินทรัพย์ทั้งหมด| รายการแยกกับจุลภาคของประเภทสินทรัพย์ที่จะรวมไว้ปกติคือไม่มีระบุ * สำหรับทุกประเภทสินทรัพย์ต้องมีขอบเขตการอ่านสินค้าคงคลังเพื่อกรองโดยสถานที่ที่ซื้อ | | onlyCollectibles | boolean | รวมรายการสะสม เท่านั้น ในคำตอบค่าเริ่มต้นคือเท็จฟิลด์นี้ต้องใช้กับฟิลด์ inventoryItemAssetTypes เพื่อคืนรายการและคืนรายการจํากัดเวลาที่ไม่ใช่ UGC เท่านั้น| | privateServers | boolean | รวมเซิร์ฟเวอร์ส่วนตัวในคำตอบค่าเริ่มต้นคือเท็จต้องมีขอบเขตการอ่านสินค้าคงคลังเพื่อกรองโดยฟิลด์นี้ |

ฟิลด์รหัส

| กรอง | ประเภท | คําอธิบาย | | :----------------- | :----- | :--------------------------------------------------------------------------------------------------------------------- | | assetIds | ข้อความ | รายการแยกกับจุลภาคของรหัสสินทรัพย์ที่จะรวม | | badgeIds | ข้อความ | รายการแยกกับจุลภาคของรหัสป้ายที่จะรวม | | gamePassIds | สตริง | รายการแยกกับจุลภาพของรหัสเกมที่จะรวม | | privateServerIds | ข้อความ | รายการแยกกับจุลภาคของไอดีเซิร์ฟเวอร์ส่วนตัวที่จะรวมต้องมีขอบเขตการอ่านคลังสินค้าเพื่อกรองโดยฟิลด์นี้ |

ตัวอย่าง

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

  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