GlobalDataStore
*Ce contenu est traduit en utilisant l'IA (Beta) et peut contenir des erreurs. Pour consulter cette page en anglais, clique ici.
Un magasin de données global expose des fonctions pour sauvegarder et charger des données pour le DataStoreService.
Voir magasins de données pour un guide complet sur la structure des données, la gestion, la gestion des erreurs, etc.
Les magasins de données ordonnés ne supportent pas la version et les métadonnées, donc DataStoreKeyInfo est toujours nil pour les clés dans un OrderedDataStore.Si vous avez besoin de assistancede version et de métadonnées, utilisez un DataStore .
Résumé
Méthodes
Renvoie la valeur d'une clé dans un magasin de données spécifié et une instance DataStoreKeyInfo.
- IncrementAsync(key : string,delta : number,userIds : Array,options : DataStoreIncrementOptions):Variant
Augmente la valeur d'une clé de la quantité fournie (les deux doivent être des entiers).
Supprime la clé spécifiée tout en conservant une version accessible.
Définit la valeur du magasin de données pour la clé donnée.
Mise à jour de la valeur d'une clé avec une nouvelle valeur de la fonction d'appel spécifiée.
Propriétés
Méthodes
GetAsync
Cette fonction renvoie la dernière valeur de la clé fournie et une instance DataStoreKeyInfo .Si la clé n'existe pas ou si la dernière version a été marquée comme supprimée, les deux valeurs de retour seront nil .
Les clés sont mises en cache localement pendant 4 secondes après la première lu.Un appel A GlobalDataStore:GetAsync() dans ces 4 secondes renvoie une valeur du cache.Les modifications de la clé par GlobalDataStore:SetAsync() ou GlobalDataStore:UpdateAsync() s'appliquent immédiatement au cache et redémarrent le minuteur de 4 secondes.
Pour obtenir une version spécifique, comme une version avant la dernière, utilisez DataStore:GetVersionAsync() .
Paramètres
Le nom de clé pour lequel la valeur est demandée.Si DataStoreOptions.AllScopes a été défini sur true lors de l'accès au magasin de données via DataStoreService:GetDataStore(), ce nom de clé doit être préfixé avec la portée originale comme dans "scope/key".
Retours
La valeur de l'entrée dans le magasin de données avec la clé donnée et une instance DataStoreKeyInfo qui inclut le numéro de version, la date et l'heure à laquelle la version a été créée, et les fonctions pour récupérer UserIds et les métadonnées.
IncrementAsync
Cette fonction augmente la valeur d'une clé de la quantité fournie (les deux doivent être des entiers).
Les valeurs dans GlobalDataStores sont versionnées comme décrit dans la version.OrderedDataStores ne prend pas en charge la version, donc l'appel de cette méthode sur une clé de stockage de données ordonnée écrasera la valeur actuelle par la valeur augmentée et rendra les versions précédentes inaccessibles.
Paramètres
Nom de clé pour lequel la valeur doit être mise à jour.Si DataStoreOptions.AllScopes a été défini sur true lors de l'accès au magasin de données via DataStoreService:GetDataStore(), ce nom de clé doit être préfixé avec la portée originale comme dans "scope/key".
Montant à augmenter la valeur actuelle par.
(Facultatif) DataStoreIncrementOptions instance qui combine plusieurs paramètres supplémentaires comme métadonnées personnalisées et permet une extension future.
Retours
La valeur mise à jour de l'entrée dans le magasin de données avec la clé donnée.
RemoveAsync
Cette fonction marque la clé spécifiée comme supprimée en créant une nouvelle version « tombstone » de la clé.Avant cela, il renvoie la dernière version avant l'appel de suppression.
Après qu'une clé a été supprimée via cette fonction, les appels de GlobalDataStore:GetAsync() pour la clé retourneront nil .Les versions plus anciennes de la clé restent accessibles via DataStore:ListVersionsAsync() et DataStore:GetVersionAsync(), en supposant qu'elles n'ont pas expiré.
OrderedDataStore ne prend pas en charge la version, donc l'appel de RemoveAsync() sur une clé OrderedDataStore la supprimera définitivement.
Les objets supprimés seront définitivement supprimés après 30 jours.
Si les valeurs précédentes ont déjà été supprimées via GlobalDataStore:RemoveAsync() ou DataStore:RemoveVersionAsync() , la fonction retournera nil , nil pour la valeur et DataStoreKeyInfo respectivement.
Paramètres
Nom de clé à supprimer.Si DataStoreOptions.AllScopes a été défini sur true lors de l'accès au magasin de données via DataStoreService:GetDataStore(), ce nom de clé doit être préfixé avec la portée originale comme dans "scope/key".
Retours
La valeur du magasin de données avant suppression et une instance DataStoreKeyInfo qui inclut le numéro de version, la date et l'heure à laquelle la version a été créée, et les fonctions pour récupérer UserIds et les métadonnées.
SetAsync
Cette fonction définit la dernière valeur, UserIds , et les métadonnées pour la clé donnée.
Les valeurs dans GlobalDataStores sont versionnées comme décrit dans la version.OrderedDataStores ne prend pas en charge la version, donc l'appel de cette méthode sur une clé de stockage de données ordonnée écrasera la valeur actuelle et rendra les versions précédentes inaccessibles.
Les définitions de métadonnées doivent toujours être mises à jour avec une valeur, même s'il n'y a pas de modifications de la valeur actuelle ; sinon, la valeur actuelle sera perdue.
Toute chaîne stockée dans un magasin de données doit être valide UTF-8 .Dans UTF-8, les valeurs supérieures à 127 sont utilisées exclusivement pour encoder des points de code multibytes, donc un seul octet supérieur à 127 ne sera pas valide en UTF-8 et l'essai GlobalDataStore:SetAsync() échouera.
Définir vs. mettre à jour
GlobalDataStore:SetAsync() est le meilleur pour une mise à jour rapide d'une clé spécifique, et ne compte que contre la limite d'écriture.Cependant, cela peut provoquer une incohérence des données si deux serveurs tentent de définir la même clé en même temps.GlobalDataStore:UpdateAsync() est plus sûr pour gérer les tentatives multi-serveurs car il lit la valeur de clé actuelle (de n'importe quel serveur dernièrement mis à jour) avant d'apporter des modifications.Cependant, c'est un peu plus lent car il lit avant d'écrire, et il compte également contre la limite de lecture et d'écriture.
Paramètres
Nom de clé pour lequel la valeur doit être configurer.Si DataStoreOptions.AllScopes a été défini sur true lors de l'accès au magasin de données via DataStoreService:GetDataStore(), ce nom de clé doit être préfixé avec la portée originale comme dans "scope/key".
La valeur à laquelle la clé du magasin de données sera définie.
Table de UserIds , fortement recommandée pour aider à la traçabilité/élimination du RGPD.
(Facultatif) DataStoreSetOptions instance qui permet la spécification de métadonnées sur la clé.
Retours
L'identifiant de version de la version nouvellement créée. Il peut être utilisé pour récupérer des informations clés en utilisant GetVersionAsync() ou pour le supprimer en utilisant RemoveVersionAsync() .
UpdateAsync
Cette fonction récupère la valeur et les métadonnées d'une clé dans le magasin de données et la met à jour avec une nouvelle valeur déterminée par la fonction d'appel spécifiée via le deuxième paramètre.Si le rappel renvoie nil, l'opération d'écriture est annulée et la valeur reste inchangée.
Les valeurs dans GlobalDataStores sont versionnées comme décrit dans la version.OrderedDataStores ne prend pas en charge la version, donc l'appel de cette méthode sur une clé de stockage de données ordonnée écrasera la valeur actuelle et rendra les versions précédentes inaccessibles.
Dans les cas où un autre serveur de jeu a mis à jour la clé dans la courte période entre la récupération de la valeur actuelle de la clé et le définition de la valeur de la clé, GlobalDataStore:UpdateAsync() appellera à nouveau la fonction, rejetant le résultat de l'appel précédent.La fonction sera appelée autant de fois que nécessaire jusqu'à ce que les données soient enregistrées ou jusqu'à ce que la fonction de rappel retourne nil .Cela peut être utilisé pour garantir que aucune donnée ne soit écrasée.
Toute chaîne stockée dans un magasin de données doit être valide UTF-8 .Dans UTF-8, les valeurs supérieures à 127 sont utilisées exclusivement pour encoder des points de code multibytes, donc un seul octet supérieur à 127 ne sera pas valide en UTF-8 et l'essai GlobalDataStore:UpdateAsync() échouera.
Définir vs. mettre à jour
GlobalDataStore:SetAsync() est le meilleur pour une mise à jour rapide d'une clé spécifique, et ne compte que contre la limite d'écriture.Cependant, cela peut provoquer une incohérence des données si deux serveurs tentent de définir la même clé en même temps.GlobalDataStore:UpdateAsync() est plus sûr pour gérer les tentatives multi-serveurs car il lit la valeur de clé actuelle (de n'importe quel serveur dernièrement mis à jour) avant d'apporter des modifications.Cependant, c'est un peu plus lent car il lit avant d'écrire, et il compte également contre la limite de lecture et d'écriture.
Fonction de rappel
La fonction de rappel accepte deux arguments :
- Valeur actuelle de la clé avant la mise à jour.
- DataStoreKeyInfo instance qui contient les informations de dernière version (ce paramètre peut être ignoré si les métadonnées ne sont pas utilisées).
À son tour, la fonction de rappel renvoie jusqu'à trois valeurs :
- La nouvelle valeur à définir pour la clé.
- Un ensemble de UserIds à associer à la clé.DataStoreKeyInfo:GetUserIds() devrait être renvoyé à moins que les ID existants ne soient modifiés ; sinon, tous les ID existants seront effacés.
- Une table Luau contenant des métadonnées à associer à la clé.DataStoreKeyInfo:GetMetadata() doit être renvoyé à moins que les métadonnées existantes ne soient modifiées ; sinon, toutes les métadonnées existantes seront effacées.
Si le rappel renvoie nil, le serveur actuel cessera d'essayer de mettre à jour la clé.
La fonction de rappel ne peut pas être retournée, donc ne faites pas pas inclure des appels comme task.wait().
Paramètres
Nom de clé pour lequel la valeur doit être mise à jour.Si DataStoreOptions.AllScopes a été défini sur true lors de l'accès au magasin de données via DataStoreService:GetDataStore(), ce nom de clé doit être préfixé avec la portée originale comme dans "scope/key".
Fonction de transformation qui prend la valeur actuelle et DataStoreKeyInfo en paramètres et renvoie la nouvelle valeur ainsi que les métadonnées facultatives UserIds et optionnelles.
Retours
La valeur mise à jour de l'entrée dans le magasin de données avec la clé donnée et une instance DataStoreKeyInfo qui inclut le numéro de version, la date et l'heure à laquelle la version a été créée, et les fonctions pour récupérer UserIds et les métadonnées.