การจัดการคำขอ API สำหรับที่เก็บข้อมูล

ก่อนส่งคำขอไปยัง Open Cloud APIs สําหรับ สตอเรจข้อมูลมาตรฐาน และ สตอเรจข้อมูลที่สั่งซื้อ คุณต้องเข้าใจวิธีจัดการพวกเขาอย่างถูกต้องสำหรับข้อมูลเกี่ยวกับการใช้งานของ API ดูคู่มือการใช้งาน

การอนุญาต

เช่นเดียวกับ API เปิดท้องถิ่นทั้งหมด จุดสิ้นสุดที่เก็บข้อมูลต้องการให้คำขอทั้งหมดรวมถึงหัวข้อ x-api-key ที่มีคีย์ API ร้านค้าและการดำเนินการเอนด์ทางจะได้รับอนุญาตหากกุญแจไม่ถูกต้อง, 403 Unauthorized จะถูกส่งคืนสำหรับข้อมูลเพิ่มเติมเกี่ยวกับคีย์ API ดู จัดการคีย์ API

การลดความเร็ว

ทุกจุดจบมีสองประเภทของการจำกัดระดับจักรวาล: การจำกัดคำขอต่อนาที และ การจำกัดผ่านทาง ด้วยประสบการณ์ทุกครั้ง การจํากัดคําขอต่อนาที ช่วยให้คุณสามารถส่งจํานวนคําขอต่อนาทีที่กําหนดได้ และ การจํากัดความเร็วในการส่งข้อมูลต่อนาที ช่วยให้คุณสามารถส่งจํานวนข้อมูลที่กําหนดได้ต่อนาที ไม่ว่าจะเป็นจํานวน API กุญแจเท่าใดก็ตาม

ไม่เหมือนกับ Luau API ข้อจํากัดเหล่านี้ไม่ได้เพิ่มขึ้นตามจํานวนผู้ใช้ในปัจจุบัน การเกินข้อจํากัดเหล่านี้ทําให้เอนด์พอยท์ต้อง返回 429 Too Many Requests

สตอร์เจอร์ข้อมูลมาตรฐานจำกัดการใช้งาน

คลังข้อมูลที่สั่งจองจำกัดการใช้งาน

การตรวจสอบการป้อนข้อมูล

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

ID จักรวาล

ID จักรวาล คือตัวระบุที่ไม่ซ้ำกันของประสบการณ์ที่คุณต้องการเข้าถึงที่เก็บข้อมูลของคุณ มูลค่าของ ID จักรวาลของประสบการณ์คือมูลค่าของ DataModel.GameId ของมัน, ไม่ เหมือนกับ ID จุดเริ่มต้นของประสบการณ์ ซึ่งระบุจุดเริ่มต้นของประสบการณ์แทนทั้งหมด

คุณสามารถรับ ID จักรวาล ของประสบการณ์ด้วยขั้นตอนต่อไปนี้:

1. นําทางไปยัง แดชบอร์ดผู้สร้าง
2. ค้นหาประสบการณ์ที่มีร้านข้อมูลที่คุณต้องการเข้าถึง
3. เลื่อนเมาส์ไปที่ภาพรวมของประสบการณ์, คลิกปุ่ม ⋯ และเลือก คัดลอก ID ภาพขนาดย่อ

ขอบเขต

คุณสามารถจัดระเบียบที่เก็บข้อมูลของคุณโดยการตั้งค่าสตริงที่ไม่ซ้ำกันเป็นขอบเขตที่ระบุชื่อโฟลเดอร์ย่อยสําหรับรายการเมื่อคุณกำหนดขอบเขตแล้ว มันจะเพิ่มโดยอัตโนมัติไปยังทุกคีย์ในการดำเนินการทั้งหมดที่ทำบนคลังข้อมูลขอบเขตเป็นตัวเลือกและโดยปกติเป็น global สำหรับร้านข้อมูลมาตรฐาน แต่จำเป็นสำหรับร้านข้อมูลที่สั่งซื้อ

ขอบของการจัดหมวดหมู่ข้อมูลของคุณด้วยสตริงและตัวแยกด้วย "/" เช่น:

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

นอกจากนี้หากคุณต้องการระบุทุกคีย์ที่เก็บไว้ในคลังข้อมูลที่มีหนึ่งหรือหลายสโคปที่ไม่ได้เป็นค่าเริ่มต้นคุณสามารถตั้งค่าพารามิเตอร์ ในวิธี ให้เป็น ซึ่งในกรณีนี้การโทรกลับจะส่งคืนทูปเดิลที่มีคีย์และสโคปในตัวอย่างก่อนหน้านี้ List Entries จะส่งคืนทั้งสอง ( 1234 , global ) และ ( 1234 , special ) ในคำตอบ

คุณไม่สามารถส่งพารามิเตอร์ Scope และ AllScopes ในคำขอเดียวกันได้ มิฉะนั้นการโทรจะส่งคืนข้อผิดพลาดการใช้ฟังก์ชันช่วยเหลือจาก Open Cloud APIs สําหรับโมดูลสตอเรจข้อมูล รหัสต่อไปนี้แสดงวิธีที่คุณสามารถอ่านทุกคีย์ในสตอเรจข้อมูลด้วยขอบเขตที่กําหนดเอง:

รายการกุญแจสำหรับขอบเขตที่แตกต่างกัน
# ตั้งค่า
import tutorialFunctions
DatastoresApi = tutorialFunctions.DataStores()
datastoreName = "PlayerInventory"

# รายการคีย์สำหรับขอบเขตทั่วโลก
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "global", allScopes = False)
print(keys.content)
# รายการคีย์สำหรับขอบเขตพิเศษ
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "special", allScopes = False)
print(keys.content)
# รายการคีย์สําหรับ allScope ตั้งค่าเป็นจริง
specialScopeKeys = DatastoresApi.list_entries(datastoreName, allScopes = True)
print(specialScopeKeys.content)

กุญแจที่มีขอบเขตตามมาจะถูกส่งคืนในคำตอบ:

ตัวอย่างคำตอบสำหรับขอบเขตที่แตกต่างกัน
// คำตอบสำหรับขอบเขตระดับโลก
{ "keys": [{ "scope": "global", "key": "User_2" }], "nextPageCursor": "" }

// คำตอบสำหรับขอบเขตพิเศษ
{"keys":[{"scope":"special","key":"User_6"},{"scope":"special","key":"User_7"}],"nextPageCursor":""}

// คําตอบสําหรับ AllScopes
{"keys":[{"scope":"global","key":"User_3"},{"scope":"global","key":"User_4"},{"scope":"global","key":"User_5"},{"scope":"special","key":"User_6"},{"scope":"special","key":"User_7"}],"nextPageCursor":""}

เนื้อหา-MD5

Content-MD5 คือ เบส-64 เข้ารหัส MD5 สรุปข้อมูล ของเนื้อหาเป็นหัวข้อคำขอทางเลือกสำหรับเอนด์พอยท์ ตั้งค่าเอนทรี ที่ตรวจสอบความถูกต้องของข้อมูลและตรวจจับปัญหาที่อาจเกิดขึ้น

คุณสามารถใช้ภาษาที่คุณเลือกเพื่อคำนวณมูลค่าของหัวข้อ content-md5ตัวอย่างต่อไปนี้ใช้ Pythonฟังก์ชัน hashlib.md5() และ base64.b64encode() มีอยู่ในไลบรารีมาตรฐานของ Python (2.7, 3+)

สร้างเนื้อหา-MD5
# พร้อมด้วยคำแนะนำ
$ python -c "import base64, hashlib; print('content-md5: ' + str(base64.b64encode(hashlib.md5(bytes(input('content: '), encoding='utf8')).digest()), encoding='utf8'))"
content: 750
content-md5: sTf90fedVsft8zZf6nUg8g==
# ใช้เพียง stdin และ stdout
$ echo "750" | python -c "import base64, hashlib; print(str(base64.b64encode(hashlib.md5(bytes(input(), encoding='utf8')).digest()), encoding='utf8'))"
sTf90fedVsft8zZf6nUg8g==

หากคุณพบปัญหาในการสร้างค่า content-md5 ที่ถูกต้องคุณอาจต้องเข้ารหัสร่างคำขอของคุณในรูปแบบไบนารี UTF-8 ก่อนที่จะคำนวณเช็คสัมมาณ

เคอร์เซอร์

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

รูปแบบของสตริงเคอร์เซอร์ไม่ได้ถูกกำหนด ไม่ได้ คุณไม่ควรตีความหรือแยกวิเคราะห์พวกเขาเนื่องจากอาจมีการเปลี่ยนแปลงได้ตลอดเวลา

ตัวกรอง

เมื่อส่งคำขอไปยังวิธี List สำหรับร้านข้อมูลที่สั่งซื้อคุณสามารถเพิ่มพารามิเตอร์คำถามที่เลือกได้ filter เพื่อส่งรายการที่มีค่าในช่วงที่กำหนดกลับ

พารามิเตอร์ filter สนับสนุนตัวเลือกการคิดเชิงเหตุผลหนึ่งตัว, && , และสองตัวเลือกการเปรียบเทียบ, <= สำหรับการตั้งค่าค่าสูงสุด และ >= สำหรับการตั้งค่าค่าต่ำสุดหากต้องการตั้งช่วงที่มีทั้งค่าสูงสุดและค่าต่ำสุด ให้เพิ่ม && ระหว่างสองลำดับ

ตัวอย่างเช่น เพื่อคืนค่าเข้าที่มีค่าน้อยกว่าหรือเท่ากับ 10 คุณต้องใส่ entry <= 10 เป็นค่า filterเพื่อคืนค่าเข้าที่มีค่าระหว่าง 10 และ 50 ให้ใส่ entry <= 50 && entry >= 10

ตัวอย่างต่อไปนี้เป็นค่าที่ไม่ถูกต้อง filter ที่อาจทำให้คำขอของคุณล้มเหลว:

• entry <= 10 - ไม่มีช่องว่างระหว่างแต่ละส่วนของลำดับ
• 10 <= entry - entry และค่าการเปรียบเทียบอยู่ที่ด้านผิด
• entry <= 10 && entry <= 50 - && สามารถใช้เพื่อกำหนดช่วงที่มีทั้งสองตัวเลือกเปรียบเทียบสำหรับค่าต่ำสุดและสูงสุดเท่านั้น

อนุญาตธงที่หายไป

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

เมื่อคุณตั้งธง allow_missing เป็น True :

• หากรายการไม่มีอยู่ คำตอบจะส่งรายการใหม่

• หากรายการมีอยู่ แต่เนื้อหาตรงกับมูลค่าที่มีอยู่ของรายการ รายการที่มีอยู่จะยังคงไม่เปลี่ยนแปลง

• หากรายการมีอยู่และเนื้อหาไม่ตรงกับค่ารายการที่มีอยู่แล้ว คำตอบจะส่งรายการพร้อมค่าเนื้อหาใหม่ที่อัปเดต