GlobalDataStore
*Este contenido se traduce usando la IA (Beta) y puede contener errores. Para ver esta página en inglés, haz clic en aquí.
Un almacén de datos global exponen funciones para guardar y cargar datos para el DataStoreService.
Vea Almacenes de datos para una guía detallada sobre la estructura de datos, la gestión, la gestión de errores, etc.
Las tiendas de datos ordenadas no admiten versiones y metadatos, por lo que DataStoreKeyInfo siempre es nil para las claves en un OrderedDataStore .Si necesita Soportede versiones y metadatos, utilice un DataStore .
Resumen
Métodos
Devuelve el valor de una clave en un almacén de datos especificado y una instancia DataStoreKeyInfo .
- IncrementAsync(key : string,delta : number,userIds : Array,options : DataStoreIncrementOptions):Variant
Incrementa el valor de una clave por la cantidad proporcionada (ambos deben ser enteros).
Elimina la clave especificada mientras mantiene una versión accesible.
Establece el valor del almacén de datos para la clave dada.
Actualiza el valor de una clave con un nuevo valor de la función de llamada especificada.
Propiedades
Métodos
GetAsync
Esta función devuelve el último valor de la clave proporcionada y una instancia DataStoreKeyInfo .Si la clave no existe o si la versión más reciente se ha marcado como eliminada, ambos valores de devolución serán nil .
Las claves se almacenan localmente durante 4 segundos después de la primera leído.Una llamada GlobalDataStore:GetAsync() dentro de estos 4 segundos devuelve un valor de la caché.Las modificaciones de la clave por GlobalDataStore:SetAsync() o GlobalDataStore:UpdateAsync() se aplican al almacén inmediatamente y se reinicia el temporizador de 4 segundos.
Para obtener una versión específica, como una versión antes de la más reciente, use DataStore:GetVersionAsync() .
Parámetros
El nombre de la clave para la cual se solicita el valor.Si DataStoreOptions.AllScopes se estableció en verdad al acceder al almacén de datos a través de DataStoreService:GetDataStore(), este nombre de clave debe precederse con el alcance original como en "scope/key".
Devuelve
El valor de la entrada en el almacén de datos con la clave dada y una instancia DataStoreKeyInfo que incluye el número de versión, la fecha y la hora en que se creó la versión y las funciones para recuperar UserIds y metadatos.
IncrementAsync
Esta función incrementa el valor de una clave por la cantidad proporcionada (ambos deben ser enteros).
Los valores en GlobalDataStores están versionados como se describe en versionado. OrderedDataStores no soporta versiones, por lo que llamar a este método en una clave de almacén de datos ordenada reemplazará el valor actual con el valor incrementado y hará que las versiones anteriores sean inaccesibles.
Parámetros
Nombre de clave para el cual se debe actualizar el valor.Si DataStoreOptions.AllScopes se estableció en verdad al acceder al almacén de datos a través de DataStoreService:GetDataStore(), este nombre de clave debe precederse con el alcance original como en "scope/key".
Cantidad para incrementar el valor actual por.
(Opcional) DataStoreIncrementOptions instancia que combina múltiples parámetros adicionales como metadatos personalizados y permite una futura extensión.
Devuelve
El valor actualizado de la entrada en el almacén de datos con la clave dada.
RemoveAsync
Esta función marca la clave especificada como eliminada al crear una nueva versión "de tumba" de la clave.Antes de esto, devuelve la versión más reciente antes de la llamada de eliminación.
Después de que se elimine una clave a través de esta función, las llamadas de GlobalDataStore:GetAsync() para la clave devolverán nil .Las versiones más antiguas de la clave siguen siendo accesibles a través de DataStore:ListVersionsAsync() y DataStore:GetVersionAsync(), asumiendo que no han expirado.
OrderedDataStore no admite versiones, por lo que llamar RemoveAsync() a una clave OrderedDataStore la eliminará permanentemente.
Los objetos eliminados se eliminarán permanentemente después de 30 días.
Si los valores anteriores ya se eliminaron a través de GlobalDataStore:RemoveAsync() o DataStore:RemoveVersionAsync() , la función devolverá nil , nil para el valor y DataStoreKeyInfo respectivamente.
Parámetros
Nombre de clave para ser eliminado.Si DataStoreOptions.AllScopes se estableció en verdad al acceder al almacén de datos a través de DataStoreService:GetDataStore(), este nombre de clave debe precederse con el alcance original como en "scope/key".
Devuelve
El valor del almacén de datos antes de la eliminación y una instancia DataStoreKeyInfo que incluye el número de versión, la fecha y la hora en que se creó la versión y las funciones para recuperar UserIds y metadatos.
SetAsync
Esta función establece el último valor, UserIds , y el metadato para la clave dada.
Los valores en GlobalDataStores están versionados como se describe en versionado. OrderedDataStores no soporta versiones, por lo que llamar a este método en una clave de almacén de datos ordenada reemplazará el valor actual y hará que las versiones anteriores sean inaccesibles.
Las definiciones de metadatos siempre deben actualizarse con un valor, incluso si no hay cambios en el valor actual; de lo contrario, se perderá el valor actual.
Cualquier cadena que se almacene en un almacén de datos debe ser válida UTF-8 .En UTF-8, los valores mayores a 127 se utilizan exclusivamente para codificar puntos de código multibyte, por lo que un solo byte mayor a 127 no será válido en UTF-8 y el intento de GlobalDataStore:SetAsync() fallará.
Establecer vs. actualizar
GlobalDataStore:SetAsync() es mejor para una actualización rápida de una clave específica, y solo cuenta contra el límite de escritura.Sin embargo, puede causar inconsistencia de datos si dos servidores intentan establecer la misma clave al mismo tiempo.GlobalDataStore:UpdateAsync() es más seguro para manejar intentos de múltiples servidores porque lee el valor de clave actual (de cualquier servidor que se actualizó por última vez) antes de realizar cualquier cambio.Sin embargo, es algo más lento porque se lee antes de escribir, y también cuenta contra el límite de lectura y escritura.
Parámetros
Nombre de clave para el cual se debe establecer el valor.Si DataStoreOptions.AllScopes se estableció en verdad al acceder al almacén de datos a través de DataStoreService:GetDataStore(), este nombre de clave debe precederse con el alcance original como en "scope/key".
El valor al que se asignará la clave del almacén de datos.
Tabla de UserIds, altamente recomendada para ayudar con el seguimiento/eliminación de GDPR.
(Opcional) instancia que permite la especificación de metadatos en la clave.
Devuelve
El identificador de versión de la versión recién creada. Se puede usar para recuperar información clave usando GetVersionAsync() o para eliminarla usando RemoveVersionAsync() .
UpdateAsync
Esta función recupera el valor y los metadatos de una clave del almacén de datos y la actualiza con un nuevo valor determinado por la función de llamada especificada a través del segundo parámetro.Si la llamada de devolución devuelve nil, la operación de escritura se cancela y el valor se mantiene sin cambios.
Los valores en GlobalDataStores están versionados como se describe en versionado. OrderedDataStores no soporta versiones, por lo que llamar a este método en una clave de almacén de datos ordenada reemplazará el valor actual y hará que las versiones anteriores sean inaccesibles.
En casos en que otro servidor de juegos actualizó la clave en el corto período de tiempo entre la recuperación del valor actual de la clave y la configuración del valor de la clave, GlobalDataStore:UpdateAsync() llamará nuevamente la función, descartando el resultado de la llamada anterior.La función se llamará tantas veces como sea necesario hasta que los datos se guarden o hasta que la función de devolución de llamada devuelva nil .Esto se puede usar para asegurarse de que no se sobrescriba ningún dato.
Cualquier cadena que se almacene en un almacén de datos debe ser válida UTF-8 .En UTF-8, los valores mayores a 127 se utilizan exclusivamente para codificar puntos de código multibyte, por lo que un solo byte mayor a 127 no será válido en UTF-8 y el intento de GlobalDataStore:UpdateAsync() fallará.
Establecer vs. actualizar
GlobalDataStore:SetAsync() es mejor para una actualización rápida de una clave específica, y solo cuenta contra el límite de escritura.Sin embargo, puede causar inconsistencia de datos si dos servidores intentan establecer la misma clave al mismo tiempo.GlobalDataStore:UpdateAsync() es más seguro para manejar intentos de múltiples servidores porque lee el valor de clave actual (de cualquier servidor que se actualizó por última vez) antes de realizar cualquier cambio.Sin embargo, es algo más lento porque se lee antes de escribir, y también cuenta contra el límite de lectura y escritura.
Función de devolución de llamada
La función de devolución de llamada acepta dos argumentos:
- Valor actual de la clave antes de la actualización.
- DataStoreKeyInfo instancia que contiene la información de la última versión (este argumento se puede ignorar si no se está utilizando el metadato).
A su vez, la función de devolución de llamada devuelve hasta tres valores:
- El nuevo valor para establecer para la clave.
- Un array de UserIds para asociar con la clave.DataStoreKeyInfo:GetUserIds() debe devolverse a menos que se cambien los ID existentes; de lo contrario, se borrarán todos los ID existentes.
- Una tabla Luau que contiene metadatos para asociar con la clave.DataStoreKeyInfo:GetMetadata() debe devolverse a menos que se esté cambiando el metadato existente; de lo contrario, se eliminará todo el metadato existente.
Si la llamada de devolución devuelve nil en lugar, el servidor actual dejará de intentar actualizar la clave.
La función de devolución de llamadas no puede producirse, así que no incluya llamadas como .
Parámetros
Nombre de clave para el cual se debe actualizar el valor.Si DataStoreOptions.AllScopes se estableció en verdad al acceder al almacén de datos a través de DataStoreService:GetDataStore(), este nombre de clave debe precederse con el alcance original como en "scope/key".
Transformar función que toma el valor actual y DataStoreKeyInfo como parámetros y devuelve el nuevo valor junto con metadatos opcionales UserIds y opcionales.
Devuelve
El valor actualizado de la entrada en el almacén de datos con la clave dada y una instancia DataStoreKeyInfo que incluye el número de versión, la fecha y la hora en que se creó la versión y las funciones para recuperar UserIds y metadatos.