GlobalDataStore
*เนื้อหานี้แปลโดยใช้ AI (เวอร์ชัน Beta) และอาจมีข้อผิดพลาด หากต้องการดูหน้านี้เป็นภาษาอังกฤษ ให้คลิกที่นี่
A GlobalDataStore เปิดเผยฟังก์ชันสำหรับการบันทึกและโหลดข้อมูลสำหรับ DataStoreService
ดู ร้านข้อมูล สำหรับคู่มือแบบละเอียดเกี่ยวกับโครงสร้างข้อมูลการจัดการการจัดการข้อผิดพลาดฯลฯ
ร้านข้อมูลที่สั่งซื้อไม่สนับสนุนการจัดเวอร์ชันและเมทาดาต้า ดังนั้น DataStoreKeyInfo จึงเป็นเสมอ nil สำหรับกุญแจใน OrderedDataStoreหากต้องการการสนับสนุนเวอร์ชันและข้อมูลคำอธิบาย, ให้ใช้ DataStore
สรุป
วิธีการ
ส่งค่าของกุญแจในคลังข้อมูลที่กำหนดและตัวอย่าง DataStoreKeyInfo อินสแตนซ์
- IncrementAsync(key : string,delta : number,userIds : Array,options : DataStoreIncrementOptions):Variant
เพิ่มมูลค่าของกุญแจโดยจำนวนที่กำหนด (ทั้งสองต้องเป็นตัวเลข)
ลบคีย์ที่ระบุโดยยังคงรักษารุ่นที่เข้าถึงได้
ตั้งค่าค่าของคลังข้อมูลสำหรับกุญแจที่กำหนดไว้
อัปเดตค่าของกุญแจด้วยค่าใหม่จากฟังก์ชันการโทรกลับที่กำหนดไว้
คุณสมบัติ
วิธีการ
GetAsync
ฟังก์ชันนี้ส่งค่าล่าสุดของกุญแจที่ให้มาและตัวอย่าง DataStoreKeyInfo กลับหากกุญแจไม่มีอยู่หรือหากเวอร์ชันล่าสุดถูกเครื่องหมายว่าถูกลบทั้งสองค่าการ返回จะเป็น nil
กุญแจจะถูกบันทึกไว้ท้องถิ่นเป็นเวลา 4 วินาทีหลังการอ่านครั้งแรกการโทร GlobalDataStore:GetAsync() ภายใน 4 วินาทีจะคืนค่าจากแคชการแก้ไขคีย์โดย GlobalDataStore:SetAsync() หรือ GlobalDataStore:UpdateAsync() ใช้กับแคชทันทีและรีสตาร์ทตัวจับเวลา 4 วินาที
เพื่อรับรุ่นเฉพาะ, เช่นรุ่นก่อนล่าสุดใช้ DataStore:GetVersionAsync()
พารามิเตอร์
ชื่อกุญแจที่มีค่าถูกร้องขอหาก DataStoreOptions.AllScopes ถูกตั้งค่าเป็นจริงเมื่อเข้าถึงคลังข้อมูลผ่าน DataStoreService:GetDataStore() ชื่อกุญแจนี้จะต้องถูกแทรกก่อนด้วยขอบเขตเดิมตามที่อยู่ใน "scope/key"
ส่งค่ากลับ
ค่าของรายการในคลังข้อมูลด้วยกุญแจที่กำหนดและตัวอย่าง DataStoreKeyInfo ที่รวมหมายเลขรุ่นวันที่และเวลาที่รุ่นถูกสร้าง และฟังก์ชันในการดึง UserIds และเมทาดาต้า
IncrementAsync
ฟังก์ชันนี้เพิ่มมูลค่าของกุญแจโดยจํานวนที่กำหนด (ทั้งสองต้องเป็นจํานวนเต็ม)
ค่าใน GlobalDataStores มี เวอร์ชัน ตามที่อธิบายไว้ใน การเผยแพร่เวอร์ชันOrderedDataStores ไม่สนับสนุนการจัดเวอร์ชัน ดังนั้นการเรียกวิธีนี้บนคีย์ของคลังข้อมูลที่สั่งซื้อจะเขียนค่าปัจจุบันด้วยค่าที่เพิ่มขึ้นและทำให้เวอร์ชันก่อนหน้าไม่สามารถเข้าถึงได้
พารามิเตอร์
ชื่อคีย์ที่มีค่าควรได้รับการอัปเดตหาก DataStoreOptions.AllScopes ถูกตั้งค่าเป็นจริงเมื่อเข้าถึงคลังข้อมูลผ่าน DataStoreService:GetDataStore() ชื่อกุญแจนี้จะต้องถูกแทรกก่อนด้วยขอบเขตเดิมตามที่อยู่ใน "scope/key"
จํานวนที่จะเพิ่มมูลค่าปัจจุบันโดย
(เลือกได้) DataStoreIncrementOptions ตัวอย่างที่รวมพารามิเตอร์เพิ่มเติมหลายรายการเป็นเมทริกซ์ข้อมูลที่กำหนดเองและอนุญาตให้ขยายในอนาคต
ส่งค่ากลับ
มูลค่าที่ปรับปรุงของรายการในคลังข้อมูลด้วยกุญแจที่กำหนด
RemoveAsync
ฟังก์ชันนี้ทำเครื่องหมายกุญแจที่ระบุว่าถูกลบโดยการสร้างรุ่น "tombstone" คีย์
หลังจากลบกุญแจผ่านฟังก์ชันนี้แล้ว GlobalDataStore:GetAsync() จะเรียกใช้กุญแจจะกลับมา nilเวอร์ชันก่อนหน้าของกุญแจยังคงเข้าถึงได้ผ่าน DataStore:ListVersionsAsync() และ DataStore:GetVersionAsync() โดยสมมติว่าพวกเขาไม่หมดอายุ
OrderedDataStore ไม่สนับสนุนการจัดเวอร์ชัน ดังนั้นการโทร RemoveAsync() บนคีย์ OrderedDataStore จะลบถาวร
วัตถุที่ถูกลบจะถูกลบอย่างถาวรหลังจาก 30 วัน
หากค่าก่อนหน้าถูกลบผ่าน GlobalDataStore:RemoveAsync() หรือ DataStore:RemoveVersionAsync() แล้วฟังก์ชันจะส่งคืน nil , nil สำหรับค่าและ DataStoreKeyInfo ตามลำดับ
พารามิเตอร์
ชื่อกุญแจที่จะถูกลบหาก DataStoreOptions.AllScopes ถูกตั้งค่าเป็นจริงเมื่อเข้าถึงคลังข้อมูลผ่าน DataStoreService:GetDataStore() ชื่อกุญแจนี้จะต้องถูกแทรกก่อนด้วยขอบเขตเดิมตามที่อยู่ใน "scope/key"
ส่งค่ากลับ
ค่าของคลังข้อมูลก่อนที่จะลบและตัวอย่าง DataStoreKeyInfo ที่รวมหมายเลขรุ่นวันที่และเวลาที่รุ่นถูกสร้างและฟังก์ชันในการดึงข้อมูล UserIds และเมทาดาตา
SetAsync
ฟังก์ชันนี้ตั้งค่าค่าล่าสุด, UserIds และเมทาดาต้าสำหรับกุญแจที่กำหนด
ค่าใน GlobalDataStores มี เวอร์ชัน ตามที่อธิบายไว้ใน การเผยแพร่เวอร์ชันOrderedDataStores ไม่สนับสนุนการจัดเวอร์ชัน ดังนั้นการเรียกวิธีนี้บนคีย์สโตร์ข้อมูลที่สั่งซื้อจะเขียนค่าปัจจุบันทับและทำให้เวอร์ชันก่อนหน้าไม่สามารถเข้าถึงได้
การนิยามเมทาดาต้าต้องอัปเดตเสมอด้วยค่า แม้ว่าจะไม่มีการเปลี่ยนแปลงในมูลค่าปัจจุบันก็ตาม; มิฉะนั้นมูลค่าปัจจุบันจะหายไป
สตริงใดๆ ที่ถูกเก็บไว้ในคลังข้อมูลต้องถูกต้อง UTF-8ใน UTF-8 ค่าที่มากกว่า 127 จะใช้สำหรับการเข้ารหัสจุดโค้ดหลายไบต์เท่านั้น ดังนั้นไบต์เดียวที่มากกว่า 127 จะไม่ถูกต้องตามมาตรฐาน UTF-8 และความพยายาม GlobalDataStore:SetAsync() จะล้มเหลว
ตั้งค่า vs. อัปเดต
GlobalDataStore:SetAsync() เหมาะสำหรับการอัปเดตอย่างรวดเร็วของกุญแจเฉพาะและจะนับเฉพาะกับขีดจํากัดการเขียนอย่างไรก็ตาม อาจทำให้เกิดความไม่สอดคล้องของข้อมูลหากเซิร์ฟเวอร์สองตัวพยายามตั้งคีย์เดียวกันในเวลาเดียวกันGlobalDataStore:UpdateAsync() ปลอดภัยกว่าในการจัดการการพยายามหลายเซิร์ฟเวอร์เพราะมันอ่านค่ากุญแจปัจจุบัน (จากเซิร์ฟเวอร์ที่อัปเดตล่าสุด) ก่อนที่จะทำการเปลี่ยนแปลงใดๆอย่างไรก็ตาม มันช้าลงเล็กน้อยเพราะมันอ่านก่อนที่จะเขียน และยังนับกับขีดจํากัดการอ่านและการเขียนทั้งสองด้วย
พารามิเตอร์
ชื่อคีย์ที่ค่าควรถูกตั้งค่าหาก DataStoreOptions.AllScopes ถูกตั้งค่าเป็นจริงเมื่อเข้าถึงคลังข้อมูลผ่าน DataStoreService:GetDataStore() ชื่อกุญแจนี้จะต้องถูกแทรกก่อนด้วยขอบเขตเดิมตามที่อยู่ใน "scope/key"
มูลค่าที่กุญแจคลังข้อมูลจะถูกตั้งค่าเป็น
ตารางของ UserIds , แนะนำอย่างยิ่งในการช่วยเหลือการติดตาม/ลบข้อมูลของ GDPR
(ตัวเลือก) ตัวอย่างที่อนุญาตให้มีการกำหนดค่าเมทาดาตาในกุญแจ
ส่งค่ากลับ
ตัวระบุเวอร์ชั่นของรุ่นใหม่ที่สร้างขึ้น สามารถใช้เพื่อดึงข้อมูลสําคัญโดยใช้ GetVersionAsync() หรือลบโดยใช้ RemoveVersionAsync()
UpdateAsync
ฟังก์ชันนี้ดึงค่าและเมทาดาต้าของกุญแจจากคลังข้อมูลและอัปเดตด้วยค่าใหม่ที่กำหนดโดยฟังก์ชัน callback ที่ระบุผ่านพารามิเตอร์ที่สองหากการโทรกลับส่งคืน nil การดำเนินการเขียนจะถูกยกเลิกและค่าจะไม่เปลี่ยนแปลง
ค่าใน GlobalDataStores มี เวอร์ชัน ตามที่อธิบายไว้ใน การเผยแพร่เวอร์ชันOrderedDataStores ไม่สนับสนุนการจัดเวอร์ชัน ดังนั้นการเรียกวิธีนี้บนคีย์สโตร์ข้อมูลที่สั่งซื้อจะเขียนค่าปัจจุบันทับและทำให้เวอร์ชันก่อนหน้าไม่สามารถเข้าถึงได้
ในกรณีที่เซิร์ฟเวอร์เกมอื่นอัปเดตกุญแจในช่วงเวลาสั้น ๆ คีย์GlobalDataStore:UpdateAsync() จะเรียกฟังก์ชันอีกครั้งโดยทิ้งผลลัพธ์ของการโทรครั้งก่อนฟังก์ชันจะถูกเรียกตามความจำเป็นจนกว่าข้อมูลจะถูกบันทึก หรือ จนกว่าฟังก์ชันการโทรกลับจะกลับมา nilสามารถใช้เพื่อให้แน่ใจว่าไม่มีข้อมูลถูกเขียนทับ
สตริงใดๆ ที่ถูกเก็บไว้ในคลังข้อมูลต้องถูกต้อง UTF-8ใน UTF-8 ค่าที่มากกว่า 127 จะใช้สำหรับการเข้ารหัสจุดโค้ดหลายไบต์เท่านั้น ดังนั้นไบต์เดียวที่มากกว่า 127 จะไม่ถูกต้องตามมาตรฐาน UTF-8 และความพยายาม GlobalDataStore:UpdateAsync() จะล้มเหลว
ตั้งค่า vs. อัปเดต
GlobalDataStore:SetAsync() เหมาะสำหรับการอัปเดตอย่างรวดเร็วของกุญแจเฉพาะและจะนับเฉพาะกับขีดจํากัดการเขียนอย่างไรก็ตาม อาจทำให้เกิดความไม่สอดคล้องของข้อมูลหากเซิร์ฟเวอร์สองตัวพยายามตั้งคีย์เดียวกันในเวลาเดียวกันGlobalDataStore:UpdateAsync() ปลอดภัยกว่าในการจัดการการพยายามหลายเซิร์ฟเวอร์เพราะมันอ่านค่ากุญแจปัจจุบัน (จากเซิร์ฟเวอร์ที่อัปเดตล่าสุด) ก่อนที่จะทำการเปลี่ยนแปลงใดๆอย่างไรก็ตาม มันช้าลงเล็กน้อยเพราะมันอ่านก่อนที่จะเขียน และยังนับกับขีดจํากัดการอ่านและการเขียนทั้งสองด้วย
ฟังก์ชันการโทรกลับ
ฟังก์ชัน callback ยอมรับสองอาร์กิวเมนต์:
- มูลค่าปัจจุบันของกุญแจก่อนการอัปเดต
- DataStoreKeyInfo ตัวอย่างที่มีข้อมูลเวอร์ชันล่าสุด (อาร์กิวเมนต์นี้สามารถถูกเพิกเฉยได้หากไม่มีการใช้เมทาดาต้า)
ในทางกลับกันฟังก์ชัน callback จะคืนมูลค่าสูงสุดถึงสาม:
- คีย์
- ชุดของ UserIds ที่จะเชื่อมโยงกับกุญแจDataStoreKeyInfo:GetUserIds() ควรจะส่งคืนไม่เว้นแต่ ID ที่มีอยู่จะถูกเปลี่ยน; มิฉะนั้น ID ทั้งหมดที่มีอยู่จะถูกล้าง
- โต๊ะ Luau ที่มีเมตาดาต้าที่จะเชื่อมโยงกับกุญแจDataStoreKeyInfo:GetMetadata() ควรจะส่งคืนเว้นแต่ข้อมูลเมทาดาต้าที่มีอยู่จะถูกเปลี่ยนแปลง; มิฉะนั้นข้อมูลเมทาดาทั้งหมดที่มีอยู่จะถูกล้าง
หากการโทรกลับส่งคืน nil แทน เซิร์ฟเวอร์ปัจจุบันจะหยุดพยายามอัปเดตกุญแจ
ฟังก์ชันการโทรกลับไม่สามารถให้ผลได้ ดังนั้นจึงไม่ควร ไม่ รวมการโทรเช่น task.wait()
พารามิเตอร์
ชื่อคีย์ที่มีค่าควรได้รับการอัปเดตหาก DataStoreOptions.AllScopes ถูกตั้งค่าเป็นจริงเมื่อเข้าถึงคลังข้อมูลผ่าน DataStoreService:GetDataStore() ชื่อกุญแจนี้จะต้องถูกแทรกก่อนด้วยขอบเขตเดิมตามที่อยู่ใน "scope/key"
เปลี่ยนฟังก์ชันที่ใช้ค่าปัจจุบันและ DataStoreKeyInfo เป็นพารามิเตอร์และส่งคืนค่าใหม่พร้อมกับตัวเลือก UserIds และเมทาดาต้า
ส่งค่ากลับ
ค่าที่ปรับปรุงของรายการในคลังข้อมูลด้วยกุญแจที่กำหนดและตัวอย่าง DataStoreKeyInfo ที่รวมหมายเลขเวอร์ชันวันที่และเวลาที่เวอร์ชันถูกสร้าง และฟังก์ชันในการดึง UserIds และเมทาดาต้า