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 que falhou, 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

Modelos de dados têm limites. Se uma experiência exceder esses limites, o serviço desacelera automaticamente o uso do armazenamento de dados da experiência e causa futuras solicitações a serem colocadas em uma das seguintes filas:

• Definir
• Conjunto ordenado
• Obter
• Obter ordenado

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 estiver desacelerada, 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 totalmente descartadas.

Limites de acesso

Os armazenamentos de dados estão sujeitos a limites de experiência e níveis de servidor. Limites de nível de experiência escalam com o número total de usuários concorrentes na experiência, enquanto os limites de nível de servidor são configuráveis e devem ser 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 concorrentes. 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 do orçamento de solicitações de gravação. Uma única chamada diminuirá ambos os limites.
• Servidores de jogos e Open Cloud compartilham um orçamento; o tráfego do Open Cloud pode ser desacelerado 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 do Open Cloud e do servidor de jogos são compartilhadas, é importante controlar independentemente quanto cada um pode consumir do orçamento.

Servidor de jogos

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

Open Cloud

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

• (Simples) Adicione um pequeno 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 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 de balde furado.

Os seguintes exemplos de código em 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 = 'Inventário';

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 para cada 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, em seguida aguarda o intervalo próprio 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 único de orçamento adicional de solicitações quando são criados inicialmente. 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 esta API, um criador pode configurar seus próprios limites de taxa de armazenamento de dados para cada tipo de solicitação.

Os seguintes limites padrão de taxa 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 o comprimento deles.

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 ao número de caracteres nos metadados definidos pelo usuário.

Limites de throughput

Limites de throughput por chave garantem que o desempenho seja otimizado nos servidores do Roblox. Cada limite se aplica a cada chave individual em todos os servidores de uma experiência e se atualiza 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 throughput, a solicitação é aprovada. Se o uso exceder o limite, a solicitação é negada.

Além dos limites de throughput acima, o Roblox organiza dados em partições com base em um esquema interno. Como resultado, quando o servidor de backend recebe um alto volume de solicitações ao mesmo armazenamento de dados, isso pode resultar em mais desacelerações. Independentemente da causa, a desaceleração se manifesta como erros DatastoreThrottled ou KeyThrottled, dependendo se o limite de throughput 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 sobre 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 ingressado em seu jogo pelo menos uma vez.

O limite de armazenamento é calculado usando a seguinte fórmula Limite total de armazenamento de 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 de armazená-los, portanto, evite pré-comprimir os dados. A pré-compressão adiciona sobrecarga desnecessária da CPU e pode reduzir a eficácia da compressão interna dos dados. Ao armazenar dados não comprimidos, você se beneficia automaticamente de melhorias nos algoritmos de compressão do Roblox e em futuras otimizações com base em esquemas.

Apenas a versão mais recente de cada chave conta para o uso de armazenamento. Chaves excluídas e versões superadas, embora ainda acessíveis por meio das APIs de versão durante seu período de retenção, não contam para o uso do 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.