GlobalDataStore
*Nội dung này được dịch bằng AI (Beta) và có thể có lỗi. Để xem trang này bằng tiếng Anh, hãy nhấp vào đây.
Một Kho lưu trữ dữ liệu toàn cầu tiết lộ chức năng để lưu và tải dữ liệu cho DataStoreService .
Xem Kho dữ liệu để có hướng dẫn chi tiết về cấu trúc dữ liệu, quản lý, xử lý lỗi, v.v.
Các cửa hàng dữ liệu được xếp hạng không hỗ trợ phiên bản và dữ liệu khai thác, vì vậy DataStoreKeyInfo luôn là nil cho các chìa khóa trong một OrderedDataStore .Nếu bạn cần hỗ trợ phiên bản và dữ liệu khai thác, hãy sử dụng một DataStore .
Tóm Tắt
Phương Pháp
Trả giá trị của một chìa khóa trong một cửa hàng dữ liệu được định và một ví ví dụ / trường hợpDataStoreKeyInfo .
- IncrementAsync(key : string,delta : number,userIds : Array,options : DataStoreIncrementOptions):Variant
Tăng giá trị của một chìa khóa bằng số tiền cung cấp (cả hai phải là số lẻ).
Loại bỏ chìa khóa được chỉ định trong khi vẫn giữ một phiên bản có thể truy cập.
Đặt giá trị của kho dữ liệu cho chìa khóa đã cho.
Cập nhật giá trị của một chìa khóa với một giá trị mới từ chức năng gọi lại được chỉ định.
Thuộc Tính
Phương Pháp
GetAsync
Chức năng này trả về giá trị mới nhất của chìa khóa được cung cấp và một ví ví dụ / trường hợpDataStoreKeyInfo .Nếu chìa khóa không tồn tại hoặc nếu phiên bản mới nhất đã được đánh dấu là bị xóa, cả hai giá trị trả về sẽ là nil .
Chìa khóa được lưu trữ địa phương trong 4 giây sau khi đã xemđầu tiên.Một cuộc gọi GlobalDataStore:GetAsync() trong 4 giây này trả về giá trị từ bộ nhớ đệm.Các thay đổi đối với chìa khóa bởi GlobalDataStore:SetAsync() hoặc GlobalDataStore:UpdateAsync() áp dụng ngay lập tức cho bộ nhớ và khởi động lại đồng hồ bấm 4 giây.
Để có được phiên bản cụ thể, chẳng hạn như phiên bản trước phiên bản mới nhất, hãy sử dụng DataStore:GetVersionAsync() .
Tham Số
Tên chìa khóa mà giá trị được yêu cầu.Nếu DataStoreOptions.AllScopes được đặt thành true khi truy cập vào kho dữ liệu thông qua DataStoreService:GetDataStore(), tên chìa khóa này phải được gán với phạm vi ban đầu như trong "scope/key".
Lợi Nhuận
Giá trị của mục trong kho dữ liệu với chìa khóa được cung cấp và một DataStoreKeyInfo bao gồm số phiên bản, ngày và thời gian phiên bản được tạo và các chức năng để lấy lại UserIds.
IncrementAsync
Chức năng này tăng giá trị của một chìa khóa bằng số tiền cung cấp (cả hai phải là số lẻ).
Giá trị trong GlobalDataStores được phiên bản hóa như được mô tả trong phiên bản. OrderedDataStores không hỗ trợ phiên bản, vì vậy gọi phương pháp này trên một chìa khóa cửa hàng dữ liệu được xếp hạng sẽ ghi đè giá trị hiện tại bằng giá trị tăng và làm cho các phiên bản trước không truy cập được.
Tham Số
Tên chìa khóa mà giá trị nên được cập nhật.Nếu DataStoreOptions.AllScopes được đặt thành true khi truy cập vào kho dữ liệu thông qua DataStoreService:GetDataStore(), tên chìa khóa này phải được gán với phạm vi ban đầu như trong "scope/key".
Số tiền để tăng giá trị hiện tại bằng.
(Tùy chọn) instance kết hợp nhiều tham số bổ sung như dữ liệu bổ sung và cho phép mở rộng trong tương lai.
Lợi Nhuận
Giá trị được cập nhật của mục trong kho dữ liệu với chìa khóa đã cho.
RemoveAsync
Chức năng này đánh dấu chìa khóa được chỉ định là đã bị xóa bằng cách tạo phiên bản "mộ phần" mới của chìa khóa.Trước khi điều này, nó trả về phiên bản mới nhất trước khi gọi xóa.
Sau khi một chìa khóa được xóa bằng chức năng này, GlobalDataStore:GetAsync() các cuộc gọi cho chìa khóa sẽ trả về nil .Các phiên bản cũ hơn của chìa khóa vẫn có thể truy cập thông qua DataStore:ListVersionsAsync() và DataStore:GetVersionAsync() , cho rằng chúng chưa hết hạn.
OrderedDataStore không hỗ trợ phiên bản, vì vậy gọi RemoveAsync() trên một chìa khóa OrderedDataStore sẽ xóa vĩnh viễn nó.
Các đối tượng bị xóa sẽ bị xóa vĩnh viễn sau 30 ngày.
Nếu các giá trị trước đã được xóa bằng cách GlobalDataStore:RemoveAsync() hoặc DataStore:RemoveVersionAsync() , chức năng sẽ trả về nil , nil đối với giá trị và DataStoreKeyInfo lần lượt.
Tham Số
Tên chìa khóa cần được xóa.Nếu DataStoreOptions.AllScopes được đặt thành true khi truy cập vào kho dữ liệu thông qua DataStoreService:GetDataStore(), tên chìa khóa này phải được gán với phạm vi ban đầu như trong "scope/key".
Lợi Nhuận
Giá trị của kho dữ liệu trước khi xóa và một ví dụ DataStoreKeyInfo bao gồm số phiên bản, ngày và thời gian phiên bản được tạo và các chức năng để lấy lại UserIds và dữ liệu không gian.
SetAsync
Chức năng này đặt giá trị mới nhất, UserIds , và metadata cho chìa khóa đã cho.
Giá trị trong GlobalDataStores được phiên bản hóa như được mô tả trong phiên bản. OrderedDataStores không hỗ trợ phiên bản, vì vậy việc gọi phương pháp này trên một chìa khóa cửa hàng dữ liệu được xếp hạng sẽ ghi đè giá trị hiện tại và làm cho các phiên bản trước không truy cập được.
Các định nghĩa metadata luôn phải được cập nhật với một giá trị, ngay cả khi không có thay đổi nào về giá trị hiện tại; nếu không, giá trị hiện tại sẽ bị mất.
Bất kỳ chuỗi nào được lưu trong kho dữ liệu phải hợp lệ UTF-8 .Trong UTF-8, các giá trị lớn hơn 127 được sử dụng riêng cho việc mã hóa các điểm mã nhiều byte, vì vậy một byte lớn hơn 127 sẽ không hợp lệ UTF-8 và cố gắng GlobalDataStore:SetAsync() sẽ thất bại.
So sánh vs. Cập nhật
GlobalDataStore:SetAsync() là tốt nhất cho một cập nhật nhanh chóng của một chìa khóa cụ thể, và nó chỉ đếm chống giới hạn viết.Tuy nhiên, nó có thể gây ra bất đồng dữ liệu nếu hai máy chủ cố gắng đặt cùng một chìa khóa cùng một lúc.GlobalDataStore:UpdateAsync() là an toàn hơn để xử lý các lần thử nghiệm nhiều máy chủ bởi vì nó đọc giá trị chìa khóa hiện tại (từ bất kỳ máy chủ cuối cùng được cập nhật nó) trước khi thực hiện bất kỳ thay đổi nào.Tuy nhiên, nó chậm hơn một chút vì nó đọc trước khi viết, và nó cũng tính chống lại cả giới hạn đọc và viết.
Tham Số
Tên chìa khóa mà giá trị nên được cài đặt.Nếu DataStoreOptions.AllScopes được đặt thành true khi truy cập vào kho dữ liệu thông qua DataStoreService:GetDataStore(), tên chìa khóa này phải được gán với phạm vi ban đầu như trong "scope/key".
Giá trị mà chìa khóa kho dữ liệu sẽ được đặt.
Bảng của UserIds , được đề xuất cao để hỗ trợ theo dõi/loại bỏ GDPR.
(Tùy chọn) instance cho phép định nghĩa metadata trên chìa khóa.
Lợi Nhuận
Nhận dạng phiên bản của phiên bản mới được tạo. Nó có thể được sử dụng để lấy lại thông tin chính yếu bằng cách sử dụng GetVersionAsync() hoặc để xóa nó bằng RemoveVersionAsync() .
UpdateAsync
Chức năng này lấy giá trị và metadata của một chìa khóa từ kho dữ liệu và cập nhật nó với một giá trị mới được xác định bởi chức năng gọi lại được chỉ định thông qua tham số thứ hai.Nếu cuộc gọi trả về nil , hoạt động viết bị hủy và giá trị vẫn không thay đổi.
Giá trị trong GlobalDataStores được phiên bản hóa như được mô tả trong phiên bản. OrderedDataStores không hỗ trợ phiên bản, vì vậy việc gọi phương pháp này trên một chìa khóa cửa hàng dữ liệu được xếp hạng sẽ ghi đè giá trị hiện tại và làm cho các phiên bản trước không truy cập được.
Trong trường hợp một máy chủ trò chơi khác cập nhật chìa khóa trong thời gian ngắn giữa việc lấy lại giá trị chìa khóa hiện tại và đặt giá trị chìa khóa, GlobalDataStore:UpdateAsync() sẽ gọi lại chức năng một lần nữa, loại bỏ kết quả của cuộc gọi trước.Chức năng sẽ được gọi nhiều lần cần thiết cho đến khi dữ liệu được lưu hoặc cho đến khi chức năng gọi lại trả về nil .Nó có thể được sử dụng để đảm bảo không có dữ liệu nào bị ghi đè.
Bất kỳ chuỗi nào được lưu trong kho dữ liệu phải hợp lệ UTF-8 .Trong UTF-8, các giá trị lớn hơn 127 được sử dụng riêng cho việc mã hóa các điểm mã nhiều byte, vì vậy một byte lớn hơn 127 sẽ không hợp lệ UTF-8 và cố gắng GlobalDataStore:UpdateAsync() sẽ thất bại.
So sánh vs. Cập nhật
GlobalDataStore:SetAsync() là tốt nhất cho một cập nhật nhanh chóng của một chìa khóa cụ thể, và nó chỉ đếm chống giới hạn viết.Tuy nhiên, nó có thể gây ra bất đồng dữ liệu nếu hai máy chủ cố gắng đặt cùng một chìa khóa cùng một lúc.GlobalDataStore:UpdateAsync() là an toàn hơn để xử lý các lần thử nghiệm nhiều máy chủ bởi vì nó đọc giá trị chìa khóa hiện tại (từ bất kỳ máy chủ cuối cùng được cập nhật nó) trước khi thực hiện bất kỳ thay đổi nào.Tuy nhiên, nó chậm hơn một chút vì nó đọc trước khi viết, và nó cũng tính chống lại cả giới hạn đọc và viết.
Chức năng gọi lại
Chức năng trả lại có chấp nhận hai tham số:
- Giá trị hiện tại của chìa khóa trước khi cập nhật.
- DataStoreKeyInfo ví dụ chứa thông tin phiên bản mới nhất (tham số này có thể bị bỏ qua nếu metadata không được sử dụng).
Đổi lại, chức năng trả lại cuộc gọi trả lại lên đến ba giá trị:
- Giá trị mới để đặt cho chìa khóa.
- Một mảng của UserIds để liên kết với chìa khóa.DataStoreKeyInfo:GetUserIds() nên được trả về trừ khi các ID hiện tại đang được thay đổi; nếu không, tất cả các ID hiện tại sẽ được xóa bỏ.
- Một bảng Luau chứa metadata để liên kết với chìa khóa.DataStoreKeyInfo:GetMetadata() nên được trả về trừ khi dữ liệu meta hiện tại đang được thay đổi; nếu không, tất cả dữ liệu meta hiện tại sẽ được xóa bỏ.
Nếu callback trả về nil thay vào đó, máy chủ hiện tại sẽ ngừng cố gắng cập nhật chìa khóa.
Chức năng trả lại không thể đưa ra, vì vậy hãy không bao gồm các cuộc gọi như task.wait() .
Tham Số
Tên chìa khóa mà giá trị nên được cập nhật.Nếu DataStoreOptions.AllScopes được đặt thành true khi truy cập vào kho dữ liệu thông qua DataStoreService:GetDataStore(), tên chìa khóa này phải được gán với phạm vi ban đầu như trong "scope/key".
Chuyển chức năng nhận giá trị hiện tại và DataStoreKeyInfo làm tham số và trả lại giá trị mới cùng với tùy chọn UserIds và metadata.
Lợi Nhuận
Giá trị được cập nhật của mục trong kho dữ liệu với chìa khóa được cung cấp và một DataStoreKeyInfo bao gồm số phiên bản, ngày và thời gian phiên bản được tạo và các chức năng để lấy lại UserIds.