Códigos de erro e limites do armazenamento de dados

As solicitações que você faz aos armazenamentos de dados podem falhar devido a conectividade ruim ou outros problemas. Para lidar com erros e retornar mensagens com um código de erro, envolva as funções do armazenamento de dados em pcall().

Uma chamada de gravação falhada, como UpdateAsync(), significa que o servidor do jogo não recebeu uma resposta bem-sucedida. Isso não garante sempre que a gravação no backend não ocorreu. Em alguns cenários de falha, o estado final da gravação pode ser desconhecido para o chamador até que seja verificado com uma leitura subsequente sem cache.

Referência de códigos de erro

Códigos de erro do servidor

Limites

Os modelos de dados têm limites. Se uma experiência exceder esses limites, o serviço automaticamente limita o uso do armazenamento de dados da experiência e causa que futuras solicitações sejam colocadas em uma das seguintes filas:

• Definir
• Conjunto ordenado
• Obter
• Obter ordenado

As solicitações em uma fila são tratadas na ordem em que são recebidas. A função chamada continua a ceder enquanto sua solicitação ainda estiver na fila. Se a chave do armazenamento de dados em si estiver limitada, a solicitação é colocada em uma fila, mas é temporariamente ignorada.

Cada fila tem um limite de 30 solicitações. Quando o limite de uma fila é atingido, as solicitações falham com um código de erro na faixa de 301-306, indicando que as solicitações foram descartadas completamente.

Limites de acesso

Os armazenamentos de dados estão sujeitos a limites de experiência e de nível de servidor. Os limites de nível de experiência escalam com o total de usuários simultâneos na experiência, enquanto os limites de nível de servidor são configuráveis e destinados a serem usados como uma ferramenta pelo criador.

Limites de experiência

Cada experiência tem um certo número de solicitações de armazenamento de dados permitidas com base no tipo de armazenamento de dados, tipo de solicitação e número de usuários simultâneos. Para cada tipo de armazenamento de dados e tipo de solicitação, o limite é compartilhado entre todas as funções listadas.

• UpdateAsync() consome tanto do orçamento de solicitações de leitura quanto de gravação. Uma única chamada diminuirá ambos os limites.
• O servidor do jogo e a Open Cloud compartilham um orçamento; o tráfego da Open Cloud pode ser limitado pelo uso dentro da experiência (e vice-versa). Veja Controlar limites de taxa para mais orientações.

Armazenamentos de dados padrão

Armazenamentos de dados ordenados

Controlar limites de taxa

Como as solicitações da Open Cloud e do servidor do jogo são compartilhadas, é importante controlar independentemente quanto cada uma pode consumir do orçamento.

Servidor do jogo

Servidores individuais têm limites embutidos, conforme descrito acima. Use uma combinação de SetRateLimitForRequestType() e GetRequestBudgetForRequestType() para manter um controle detalhado sobre a contribuição de servidores individuais para o orçamento total.

Open Cloud

As solicitações da Open Cloud requerem uma solução externa de limitação de taxa. Recomendamos uma das seguintes abordagens:

• (Simples) Adicione um curto tempo limite após cada solicitação, especialmente se estiver chamando a mesma API em um loop contínuo. Defina esse tempo limite igual a 60 / (consumo desejado do orçamento por minuto) segundos, como um limite superior. Observe que essa abordagem não permite que as solicitações sejam enviadas em explosões.
• (Robusta) Implemente um limitador de taxa local usando a estratégia do balde furado.

Os seguintes exemplos de código Node.js incluem implementações de referência.

const apiKey = process.env.API_KEY;
if (!apiKey) {
    throw new Error('A variável de ambiente API_KEY não está definida.');
}

const apiHeaderKey = 'x-api-key';

const universeId = '';
const dataStoreId = 'Inventory';

const baseUrl = 'https://apis.roblox.com/cloud/v2/';

// --- Configuração de limitação de taxa por operação (solicitações por minuto) ---
const LIST_RATE_PER_MIN = 60;
const GET_RATE_PER_MIN = 120;
const UPDATE_RATE_PER_MIN = 60;

// Intervalo superior por operação: 60 / (solicitações por min) segundos.
const LIST_INTERVAL_MS = (60 / LIST_RATE_PER_MIN) * 1000;
const GET_INTERVAL_MS = (60 / GET_RATE_PER_MIN) * 1000;
const UPDATE_INTERVAL_MS = (60 / UPDATE_RATE_PER_MIN) * 1000;

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// Realiza a solicitação, depois espera o intervalo desta operação antes de retornar.
async function throttledFetch(url, options, intervalMs) {
    const response = await fetch(url, options);
    await sleep(intervalMs);
    return response;
}

async function listEntries(universe, dataStore) {
    const listPath = `universes/${universe}/data-stores/${dataStore}/entries`;
    const url = baseUrl + listPath;
    const response = await throttledFetch(url, {
        headers: { [apiHeaderKey]: apiKey }
    }, LIST_INTERVAL_MS);
    return response.json();
}

async function getEntry(path) {
    const url = baseUrl + path;
    const response = await throttledFetch(url, {
        headers: { [apiHeaderKey]: apiKey }
    }, GET_INTERVAL_MS);
    return response.json();
}

async function updateEntry(path, payload) {
    const url = baseUrl + path;
    const response = await throttledFetch(url, {
        method: 'PATCH',
        headers: {
            [apiHeaderKey]: apiKey,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(payload) // O corpo deve ser uma string
    }, UPDATE_INTERVAL_MS);
    return response;
}

(async () => {
    try {
        const entries = await listEntries(universeId, dataStoreId);

        for (const entry of entries.dataStoreEntries) {
            const path = entry.path;
            console.log(`\nProcessando entrada: ${path}`);

            const currentData = await getEntry(path);

            currentData.value.currency += 10;

            const payload = { value: currentData.value };

            const updateResponse = await updateEntry(path, payload);

            console.log(`Status: ${updateResponse.status}`);
            console.log(`Resposta: ${await updateResponse.text()}`);
        }
    } catch (error) {
        console.error('Ocorreu um erro durante a execução:', error);
    }
})();

Limites do servidor

Cada servidor tem um limite de taxa configurável para cada tipo de solicitação, com base no número de jogadores naquele servidor. Os servidores recebem um estouro inicial de orçamento de solicitação adicional quando são criados pela primeira vez. Use GetRequestBudgetForRequestType() para confirmar o número de solicitações de armazenamento de dados que o servidor atual pode fazer a qualquer momento.

Esses limites são configuráveis pelo criador usando a API SetRateLimitForRequestType(). Usando essa API, um criador pode configurar seus próprios limites de taxa de armazenamentos de dados para cada tipo de solicitação.

Os seguintes limites de taxa padrão se aplicam se a API não for chamada:

Armazenamentos de dados padrão

Armazenamentos de dados ordenados

Limites de dados

Os armazenamentos de dados limitam quanto dados podem ser usados por entrada.

O nome do armazenamento de dados, o nome da chave e o escopo devem estar todos abaixo de um certo comprimento de caracteres. Use string.len() para verificar seu comprimento.

Os dados (valor da chave) também são armazenados como uma string, independentemente de seu tipo inicial. Você pode verificar o tamanho dos dados com a função JSONEncode(), que converte dados Luau em uma tabela JSON serializada.

Limites de metadados

Limites para o número de caracteres em metadados definidos pelo usuário.

Limites de taxa

Limites de taxa por chave garantem que o desempenho seja ideal nos servidores do Roblox. Cada limite se aplica a cada chave individual em todos os servidores em uma experiência e é renovado ao longo do tempo.

O Roblox examina o uso da cota associada à chave nos últimos 60 segundos. Se o uso, incluindo a solicitação atual, estiver dentro do limite de taxa, a solicitação é aprovada. Se o uso exceder o limite, a solicitação é negada.

Além dos limites de taxa acima, o Roblox organiza dados em partições com base em um esquema interno. Como resultado, quando o servidor backend recebe um alto volume de solicitações para o mesmo armazenamento de dados, isso pode resultar em uma limitação adicional. Independentemente da causa, a limitação se manifesta como erros DatastoreThrottled ou KeyThrottled, dependendo se o limite de taxa foi excedido para um único armazenamento de dados ou uma chave. Essas mensagens de erro se aplicam tanto a armazenamentos de dados ordenados quanto padrão.

Limites de armazenamento

Para manter o armazenamento estável e escalável, os armazenamentos de dados usam um limite de nível de jogo em seu uso de armazenamento.

Esse limite consiste em uma alocação base para cada jogo mais uma alocação adicional com base no número de usuários vitalícios. Um usuário vitalício é qualquer usuário que tenha se juntado ao seu jogo pelo menos uma vez.

O limite de armazenamento é calculado usando a seguinte fórmula Limite total de armazenamento da versão mais recente = 500 MB + 1 MB × contagem de usuários vitalícios.

O uso de armazenamento é medido usando o tamanho comprimido da versão mais recente de cada chave. Os armazenamentos de dados comprimem automaticamente seus dados antes do armazenamento, portanto, evite pré-comprimir você mesmo. A pré-compressão adiciona sobrecarga de CPU desnecessária e pode reduzir a eficácia da compressão embutida dos armazenamentos de dados. Ao armazenar dados não comprimidos, você se beneficia automaticamente das melhorias nos algoritmos de compressão do Roblox e de futuras otimizações baseadas em esquema.

Apenas a versão mais recente de cada chave conta para o seu uso de armazenamento. Chaves excluídas e versões substituídas, embora ainda acessíveis por meio das APIs de versão durante seu período de retenção, não contam para o seu uso de armazenamento. No entanto, os armazenamentos de dados excluídos através do método Open Cloud DeleteDataStore continuam a contar para o uso de armazenamento durante seu período de processamento de exclusão de 30 dias, até que sejam removidos permanentemente.