GlobalDataStore

Mostrar obsoleto

*Este conteúdo é traduzido por IA (Beta) e pode conter erros. Para ver a página em inglês, clique aqui.

Não criável
Não replicado

Um Armazenamento Global de Dados exibe funções para salvar e carregar dados para o DataStoreService .

Veja Armazenamentos de Dados para um guia abrangente sobre estrutura de dados, gerenciamento, manipulação de erros, etc.

Armazenamentos de dados ordenados não suportam versões e metadados, então DataStoreKeyInfo é sempre nil para chaves em um OrderedDataStore .Se você precisar de Suportea versões e metadados, use um DataStore .

Resumo

Métodos

Propriedades

Métodos

GetAsync

Rendimentos

Essa função retorna o último valor da chave fornecida e uma instância DataStoreKeyInfo .Se a chave não existir ou se a versão mais recente for marcada como excluída, ambos os valores de retorno serão nil .

Chaves são armazenadas localmente por 4 segundos após a primeira ler.Uma chamada GlobalDataStore:GetAsync() dentro desses 4 segundos retorna um valor do cache.As modificações na chave por GlobalDataStore:SetAsync() ou GlobalDataStore:UpdateAsync() aplicam-se ao cache imediatamente e reiniciam o cronômetro de 4 segundos.

Para obter uma versão específica, como uma versão antes da mais recente, use DataStore:GetVersionAsync() .

Parâmetros

key: string

O nome da chave para a qual o valor é solicitado.Se DataStoreOptions.AllScopes for definido como verdadeiro ao acessar o armazenamento de dados através de DataStoreService:GetDataStore(), este nome de chave deve ser precedido pelo escopo original como em "scope/key".

Valor Padrão: ""
Valor Padrão: "nil"

Devolução

O valor da entrada no armazenamento de dados com a chave dada e uma instância DataStoreKeyInfo que inclui o número de versão, data e hora em que a versão foi criada e funções para recuperar UserIds e metadados.

IncrementAsync

Variant
Rendimentos

Essa função aumenta o valor de uma chave pelo valor fornecido (ambos devem ser inteiros).

Os valores em GlobalDataStores são versionados como descrito em versão.OrderedDataStores não suporta versões, então chamar este método em uma chave de armazenamento de dados ordenada substituirá o valor atual pelo valor incrementado e tornará as versões anteriores inacessíveis.

Parâmetros

key: string

Nome da chave para a qual o valor deve ser atualizado.Se DataStoreOptions.AllScopes for definido como verdadeiro ao acessar o armazenamento de dados através de DataStoreService:GetDataStore(), este nome de chave deve ser precedido pelo escopo original como em "scope/key".

Valor Padrão: ""
delta: number

Quantia para incrementar o valor atual por.

Valor Padrão: 1
userIds: Array

(Opcional) Uma tabela de UserIds para se associar à chave.

Valor Padrão: "{}"

(Opcional) DataStoreIncrementOptions instância que combina vários parâmetros adicionais como metadados personalizados e permite extensibilidade futura.

Valor Padrão: "nil"

Devolução

Variant

O valor atualizado da entrada no armazenamento de dados com a chave fornecida.

RemoveAsync

Rendimentos

Essa função marca a chave especificada como excluída ao criar uma nova versão "lápide" da chave.Antes disso, ele retorna a versão mais recente antes da chamada de remoção.

Depois que uma chave for removida via essa função, GlobalDataStore:GetAsync() chamadas para a chave retornarão nil.Versões mais antigas da chave permanecem acessíveis através de DataStore:ListVersionsAsync() e DataStore:GetVersionAsync(), assumindo que elas não expiraram.

OrderedDataStore não suporta versões, então chamar RemoveAsync() em uma chave OrderedDataStore excluirá permanentemente.

Objetos removidos serão excluídos permanentemente após 30 dias.

Se os valores anteriores já foram excluídos via GlobalDataStore:RemoveAsync() ou DataStore:RemoveVersionAsync() , a função retornará nil , nil para o valor e DataStoreKeyInfo respectivamente.

Parâmetros

key: string

Nome da chave para ser removido.Se DataStoreOptions.AllScopes for definido como verdadeiro ao acessar o armazenamento de dados através de DataStoreService:GetDataStore(), este nome de chave deve ser precedido pelo escopo original como em "scope/key".

Valor Padrão: ""

Devolução

O valor do armazenamento de dados antes da exclusão e uma instância DataStoreKeyInfo que inclui o número de versão, data e hora em que a versão foi criada e funções para recuperar UserIds e metadados.

SetAsync

Variant
Rendimentos

Essa função define o último valor, UserIds , e metadados para a chave dada.

Os valores em GlobalDataStores são versionados como descrito em versão.OrderedDataStores não suporta versões, então chamar este método em uma chave de armazenamento de dados ordenada substituirá o valor atual e tornará as versões anteriores inacessíveis.

As definições de metadados devem sempre ser atualizadas com um valor, mesmo que não haja mudanças no valor atual; caso contrário, o valor atual será perdido.

Qualquer string armazenada em um armazenamento de dados deve ser válida UTF-8 .No UTF-8, valores maiores que 127 são usados exclusivamente para codificar pontos de código multibyte, portanto, um único byte maior que 127 não será válido no UTF-8 e a tentativa GlobalDataStore:SetAsync() falhará.

Definir vs. Atualizar

GlobalDataStore:SetAsync() é melhor para uma atualização rápida de uma chave específica, e só conta contra o limite de escrita.No entanto, pode causar inconsistência de dados se dois servidores tentarem definir a mesma chave ao mesmo tempo.GlobalDataStore:UpdateAsync() é mais seguro para lidar com tentativas de vários servidores porque lê o valor da chave atual (de qualquer servidor que foi atualizado pela última vez) antes de fazer quaisquer alterações.No entanto, é um pouco mais lento porque lê antes de escrever e também conta contra o limite de leitura e escrita.

Parâmetros

key: string

Nome da chave para a qual o valor deve ser configurar.Se DataStoreOptions.AllScopes for definido como verdadeiro ao acessar o armazenamento de dados através de DataStoreService:GetDataStore(), este nome de chave deve ser precedido pelo escopo original como em "scope/key".

Valor Padrão: ""
value: Variant

O valor que a chave do armazenamento de dados será definida.

Valor Padrão: ""
userIds: Array

Tabela de UserIds, altamente recomendada para ajudar com o rastreamento/remoção do GDPR.

Valor Padrão: "{}"

(Opcional) DataStoreSetOptions instância que permite a especificação de metadados na chave.

Valor Padrão: "nil"

Devolução

Variant

O identificador de versão da versão recém-criada. Pode ser usado para recuperar informações importantes usando GetVersionAsync() ou para removê-la usando RemoveVersionAsync().

UpdateAsync

Rendimentos

Essa função recupera o valor e os metadados de uma chave do armazenamento de dados e atualiza-a com um novo valor determinado pela função de chamada especificada através do segundo parâmetro.Se o retorno do callback for nil, a operação de escrita é cancelada e o valor permanece inalterado.

Os valores em GlobalDataStores são versionados como descrito em versão.OrderedDataStores não suporta versões, então chamar este método em uma chave de armazenamento de dados ordenada substituirá o valor atual e tornará as versões anteriores inacessíveis.

Em casos em que outro servidor de jogos atualizou a chave no curto período de tempo entre a recuperação do valor atual da chave e a definição do valor da chave, GlobalDataStore:UpdateAsync() chamará a função novamente, descartando o resultado da chamada anterior.A função será chamada tantas vezes quanto necessário até que os dados sejam salvos ou até que a função de retorno de chamada retorne nil .Isso pode ser usado para garantir que nenhum dado seja sobrescrito.

Qualquer string armazenada em um armazenamento de dados deve ser válida UTF-8 .No UTF-8, valores maiores que 127 são usados exclusivamente para codificar pontos de código multibyte, portanto, um único byte maior que 127 não será válido no UTF-8 e a tentativa GlobalDataStore:UpdateAsync() falhará.

Definir vs. Atualizar

GlobalDataStore:SetAsync() é melhor para uma atualização rápida de uma chave específica, e só conta contra o limite de escrita.No entanto, pode causar inconsistência de dados se dois servidores tentarem definir a mesma chave ao mesmo tempo.GlobalDataStore:UpdateAsync() é mais seguro para lidar com tentativas de vários servidores porque lê o valor da chave atual (de qualquer servidor que foi atualizado pela última vez) antes de fazer quaisquer alterações.No entanto, é um pouco mais lento porque lê antes de escrever e também conta contra o limite de leitura e escrita.

Função de retorno de chamada

A função de retorno aceita dois argumentos:

  • Valor atual da chave antes da atualização.
  • DataStoreKeyInfo instância que contém a informação mais recente da versão (este argumento pode ser ignorado se o metadado não estiver sendo usado).

Em troca, a função de retorno de chamada retorna até três valores:

  • O novo valor a definir para a chave.
  • Um array de UserIds para associar à chave.DataStoreKeyInfo:GetUserIds() deve ser retornado a menos que os IDs existentes estejam sendo alterados; caso contrário, todos os IDs existentes serão limpados.
  • Uma tabela Luau que contém metadados para se associar à chave.DataStoreKeyInfo:GetMetadata() deve ser retornado a menos que o metadado existente esteja sendo alterado; caso contrário, todos os metadados existentes serão limpados.

Se o retorno do callback for nil em vez disso, o servidor atual deixará de tentar atualizar a chave.

A função de retorno não pode retornar, então não inclua chamadas como não .

Parâmetros

key: string

Nome da chave para a qual o valor deve ser atualizado.Se DataStoreOptions.AllScopes for definido como verdadeiro ao acessar o armazenamento de dados através de DataStoreService:GetDataStore(), este nome de chave deve ser precedido pelo escopo original como em "scope/key".

Valor Padrão: ""
transformFunction: function

Transformar função que toma o valor atual e DataStoreKeyInfo como parâmetros e retorna o novo valor junto com metadados opcionais UserIds e opcionais.

Valor Padrão: ""

Devolução

O valor atualizado da entrada no armazenamento de dados com a chave fornecida e uma instância DataStoreKeyInfo que inclui o número de versão, data e hora em que a versão foi criada e funções para recuperar UserIds e metadados.

Eventos