GlobalDataStore
*Questo contenuto è tradotto usando AI (Beta) e potrebbe contenere errori. Per visualizzare questa pagina in inglese, clicca qui.
Un GlobalDataStore esposto esegue funzioni per il salvataggio e il caricamento dei dati per il DataStoreService.
Vedi Magazzini di dati per una guida approfondita sulla struttura dei dati, sulla gestione, sulla gestione degli errori, ecc.
Gli store di dati ordinati non supportano la versioning e i metadati, quindi DataStoreKeyInfo è sempre nil per le chiavi in un OrderedDataStore .Se hai bisogno di Assistenzaper la versionazione e i metadati, usa un DataStore .
Sommario
Proprietà
Metodi
Restituisce il valore di una chiave in un data store specificato e un'esempioDataStoreKeyInfo .
- IncrementAsync(key : string,delta : number,userIds : Array,options : DataStoreIncrementOptions):Variant
Aumenta il valore di una chiave dell'importo fornito (entrambi devono essere interi).
Rimuove la chiave specificata mentre mantiene anche una versione accessibile.
Imposta il valore del deposito dati per la chiave data.
Aggiorna il valore di una chiave con un nuovo valore dalla funzione callback specificata.
Proprietà
Metodi
GetAsync
Questa funzione restituisce l'ultimo valore della chiave fornita e un'esempioDataStoreKeyInfo .Se la chiave non esiste o se l'ultima versione è stata contrassegnata come eliminata, entrambi i valori di restituzione saranno nil .
Le chiavi vengono memorizzate localmente per 4 secondi dopo la prima lettura.Una chiamata A GlobalDataStore:GetAsync() entro questi 4 secondi restituisce un valore dalla cache.Le modifiche alla chiave da GlobalDataStore:SetAsync() o GlobalDataStore:UpdateAsync() si applicano alla cache immediatamente e riavviano il timer di 4 secondi.
Per ottenere una versione specifica, come una versione prima dell'ultima, usa DataStore:GetVersionAsync() .
Parametri
Il nome della chiave per cui viene richiesto il valore.Se DataStoreOptions.AllScopes è stato impostato su vero quando si accede al deposito di dati attraverso DataStoreService:GetDataStore() , questo nome di chiave deve essere preceduto dalla scopo originale come in "scope/key".
Restituzioni
Il valore dell'elemento nel data store con la chiave specificata e un'istanza DataStoreKeyInfo che include il numero di versione, la data e l'ora in cui è stata creata la versione e le funzioni per recuperare UserIds e i metadati.
IncrementAsync
Questa funzione aumenta il valore di una chiave dell'importo fornito (entrambi devono essere interi).
I valori in GlobalDataStores sono versionati come descritto in versionamento .OrderedDataStores non supporta la versioning, quindi chiamare questo metodo su una chiave di archiviazione ordinata sovrascriverà il valore attuale con il valore incrementato e renderà le versioni precedenti non accessibili.
Parametri
Nome chiave per cui il valore deve essere aggiornato.Se DataStoreOptions.AllScopes è stato impostato su vero quando si accede al deposito di dati attraverso DataStoreService:GetDataStore() , questo nome di chiave deve essere preceduto dalla scopo originale come in "scope/key".
Importo per aumentare il valore attuale di .
(Opzionale) DataStoreIncrementOptions istanza che combina più parametri aggiuntivi come metadati personalizzati e consente una futura estensibilità.
Restituzioni
Il valore aggiornato dell'elemento nel data store con la chiave specificata.
RemoveAsync
Questa funzione contrassegna la chiave specificata come eliminata creando una nuova versione "tombstone" della chiave.Prima di questo, restituisce l'ultima versione prima della chiamata di rimozione.
Dopo che una chiave viene rimossa tramite questa funzione, GlobalDataStore:GetAsync() le chiamate per la chiave restituiranno nil.Le versioni precedenti della chiave rimangono accessibili attraverso DataStore:ListVersionsAsync() e DataStore:GetVersionAsync(), supponendo che non siano scadute.
OrderedDataStore non supporta la versioning, quindi chiamare RemoveAsync() su una chiave OrderedDataStore la eliminerà permanentemente.
Gli oggetti rimossi verranno eliminati definitivamente dopo 30 giorni.
Se i valori precedenti sono già stati eliminati tramite GlobalDataStore:RemoveAsync() o DataStore:RemoveVersionAsync() , la funzione restituirà nil , nil per il valore e DataStoreKeyInfo rispettivamente.
Parametri
Nome della chiave da rimuovere.Se DataStoreOptions.AllScopes è stato impostato su vero quando si accede al deposito di dati attraverso DataStoreService:GetDataStore() , questo nome di chiave deve essere preceduto dalla scopo originale come in "scope/key".
Restituzioni
Il valore del deposito di dati prima della cancellazione e un'istanza DataStoreKeyInfo che include il numero di versione, la data e l'ora in cui è stata creata la versione e le funzioni per recuperare UserIds e i metadati.
SetAsync
Questa funzione imposta l'ultimo valore, UserIds , e i metadati per la chiave data.
I valori in GlobalDataStores sono versionati come descritto in versionamento .OrderedDataStores non supporta la versioning, quindi chiamare questo metodo su una chiave di archiviazione ordinata sovrascriverà il valore attuale e renderà le versioni precedenti non accessibili.
Le definizioni dei metadati devono essere sempre aggiornate con un valore, anche se non ci sono cambiamenti nel valore attuale; altrimenti il valore attuale verrà perso.
Qualunque stringa viene memorizzata in un deposito di dati deve essere valida UTF-8 .In UTF-8, i valori superiori a 127 sono utilizzati esclusivamente per l'encoding di punti di codice multi-byte, quindi un singolo byte superiore a 127 non sarà valido UTF-8 e l'attempt GlobalDataStore:SetAsync() fallirà.
Set vs. Aggiornamento
GlobalDataStore:SetAsync() è la soluzione migliore per un rapido aggiornamento di una chiave specifica, e conta solo contro il limite di scrittura.Tuttavia, può causare insincronia dei dati se due server tentano di impostare la stessa chiave allo stesso tempo.GlobalDataStore:UpdateAsync() è più sicuro per gestire tentativi multi-server perché legge il valore attuale della chiave (da qualsiasi server aggiornato per ultimo) prima di apportare qualsiasi modifica.Tuttavia, è leggermente più lento perché legge prima di scrivere e conta anche contro entrambi il limite di lettura e scrittura.
Parametri
Nome chiave per il quale il valore deve essere Impostare.Se DataStoreOptions.AllScopes è stato impostato su vero quando si accede al deposito di dati attraverso DataStoreService:GetDataStore() , questo nome di chiave deve essere preceduto dalla scopo originale come in "scope/key".
Il valore a cui verrà impostata la chiave del data store.
Tabella di UserIds , altamente raccomandata per assistere con la tracciatura/rimozione GDPR.
(Opzionale) DataStoreSetOptions istanza che consente la specificazione dei metadati sulla chiave.
Restituzioni
L'identificatore della versione appena creata. Può essere utilizzato per recuperare informazioni chiave usando GetVersionAsync() o per rimuoverlo usando RemoveVersionAsync() .
UpdateAsync
Questa funzione recupera il valore e i metadati di una chiave dal data store e lo aggiorna con un nuovo valore determinato dalla funzione di richiamo specificata attraverso il secondo parametro.Se il richiamo restituisce nil , l'operazione di scrittura viene annullata e il valore rimane invariato.
I valori in GlobalDataStores sono versionati come descritto in versionamento .OrderedDataStores non supporta la versioning, quindi chiamare questo metodo su una chiave di archiviazione ordinata sovrascriverà il valore attuale e renderà le versioni precedenti non accessibili.
Nei casi in cui un altro server di gioco ha aggiornato la chiave nel breve periodo tra il recupero del valore attuale della chiave e l'impostazione del valore della chiave, GlobalDataStore:UpdateAsync() chiamerà nuovamente la funzione, scartando il risultato della chiamata precedente.La funzione verrà chiamata il numero di volte necessario fino a quando i dati non vengono salvati o fino a quando la funzione di richiamo non restituisce nil .Questo può essere utilizzato per garantire che nessun dato venga sovrascritto.
Qualunque stringa viene memorizzata in un deposito di dati deve essere valida UTF-8 .In UTF-8, i valori superiori a 127 sono utilizzati esclusivamente per l'encoding di punti di codice multi-byte, quindi un singolo byte superiore a 127 non sarà valido UTF-8 e l'attempt GlobalDataStore:UpdateAsync() fallirà.
Set vs. Aggiornamento
GlobalDataStore:SetAsync() è la soluzione migliore per un rapido aggiornamento di una chiave specifica, e conta solo contro il limite di scrittura.Tuttavia, può causare insincronia dei dati se due server tentano di impostare la stessa chiave allo stesso tempo.GlobalDataStore:UpdateAsync() è più sicuro per gestire tentativi multi-server perché legge il valore attuale della chiave (da qualsiasi server aggiornato per ultimo) prima di apportare qualsiasi modifica.Tuttavia, è leggermente più lento perché legge prima di scrivere e conta anche contro entrambi il limite di lettura e scrittura.
Funzione di richiamo
La funzione di richiamo accetta due argomenti:
- Valore corrente della chiave prima dell'Aggiornarmento.
- DataStoreKeyInfo istanza che contiene le informazioni più recenti sulla versione (questo argomento può essere ignorato se i metadati non vengono utilizzati).
A sua volta, la funzione di richiamo restituisce fino a tre valori:
- Il nuovo valore da impostare per la chiave.
- Un array di UserIds per associarsi alla chiave.DataStoreKeyInfo:GetUserIds() deve essere restituito a meno che gli ID esistenti non vengano modificati; altrimenti tutti gli ID esistenti verranno cancellati.
- Un tavolo Luau che contiene metadata da associare alla chiave.DataStoreKeyInfo:GetMetadata() Dovrebbe essere restituito a meno che i metadati esistenti non vengono modificati; altrimenti tutti i metadati esistenti verranno cancellati.
Se il richiamo restituisce nil invece, il server attuale smetterà di tentare di aggiornare la chiave.
La funzione di richiamo non può produrre, quindi non includere le chiamate come .
Parametri
Nome chiave per cui il valore deve essere aggiornato.Se DataStoreOptions.AllScopes è stato impostato su vero quando si accede al deposito di dati attraverso DataStoreService:GetDataStore() , questo nome di chiave deve essere preceduto dalla scopo originale come in "scope/key".
Transform funzione che prende il valore attuale e DataStoreKeyInfo come parametri e restituisce il nuovo valore insieme a metadata opzionale UserIds e opzionale.
Restituzioni
Il valore aggiornato dell'elemento nel data store con la chiave indicata e un'istanza DataStoreKeyInfo che include il numero di versione, la data e l'ora in cui è stata creata la versione e le funzioni per recuperare UserIds e i metadati.