Armazenamentos em memória

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

MemoryStoreService é um serviço de dados de alta capacidade e baixa latência que fornece armazenamento rápido de dados em memória acessível de todos os servidores em uma sessão ao vivo. Armazenamentos em Memória são adequados para dados frequentes e efêmeros que mudam rapidamente e não precisam ser duráveis, pois são mais rápidos de acessar e desaparecem ao atingir a vida útil máxima. Para dados que precisam persistir entre sessões, use armazenamentos de dados.

Estruturas de dados

Em vez de acessar dados brutos diretamente, os armazenamentos em memória têm três estruturas de dados primitivas compartilhadas entre servidores para processamento rápido: mapa ordenado, fila e mapa hash. Cada estrutura de dados é adequada para certos casos de uso:

  • Matchmaking baseado em habilidade - Salve informações do usuário, como nível de habilidade, em uma fila compartilhada entre servidores e use servidores de lobby para executar matchmaking periodicamente.
  • Trocas e leilões entre servidores - Permita trocas universais entre diferentes servidores, onde os usuários podem dar lances em itens com preços que mudam em tempo real, com um mapa ordenado de pares chave-valor.
  • Classificações globais - Armazene e atualize as classificações dos usuários em uma tabela de classificação compartilhada dentro de um mapa ordenado.
  • Inventários compartilhados - Salve itens de inventário e estatísticas em um mapa hash compartilhado, onde os usuários podem utilizar itens de inventário simultaneamente entre si.
  • Cache para Dados Persistentes - Sincronize e copie seus dados persistentes em um armazenamento de dados para um mapa hash de armazenamento em memória que pode atuar como um cache e melhorar o desempenho do seu jogo.

Em geral, se você precisa acessar dados com base em uma chave específica, use um mapa hash. Se você precisa que esses dados sejam ordenados, use um mapa ordenado. Se você precisa processar seus dados em uma ordem específica, use uma fila.

Limites e cotas

Para manter a escalabilidade e o desempenho do sistema, os armazenamentos em memória têm cotas de uso de dados para o tamanho da memória, solicitações de API e o tamanho da estrutura de dados.

Os armazenamentos em memória têm uma política de expulsão baseada no tempo de expiração, também conhecido como tempo de vida (TTL). Os itens são expulsos após expirarem, e a cota de memória é liberada para novas entradas. Quando você atinge o limite de memória, solicitações que aumentam o uso de memória falham até que você libere memória ou aumente sua cota. Veja Recuperar da exaustão da cota de memória para opções.

Cota de tamanho de memória

A cota de memória limita a quantidade total de memória que um jogo pode consumir. Não é um valor fixo; em vez disso, muda ao longo do tempo dependendo do número de usuários no jogo de acordo com a fórmula 64 KB + 1,2 KB * [número de usuários]. A cota se aplica no nível do jogo em vez do nível do servidor.

Quando os usuários entram no jogo, a cota de memória adicional está disponível imediatamente. Quando os usuários saem do jogo, a cota não é reduzida imediatamente. Há um período de rastreamento de oito dias antes que a cota seja reavaliada para um valor mais baixo.

Depois que seu jogo atinge a cota de tamanho de memória, qualquer solicitação de API que aumente o tamanho da memória sempre falha. Solicitações que diminuem ou não alteram o tamanho da memória ainda têm sucesso.

Com o painel de observabilidade, você pode visualizar a cota de tamanho de memória do seu jogo em tempo real usando o gráfico de Uso de Memória.

Limites de solicitações de API

Uma cota de unidade de solicitação se aplica a todas as chamadas de API do MemoryStoreService. Essa cota é 1000 + 120 * [número de usuários simultâneos] unidades de solicitação por minuto.

A maioria das chamadas de API consome apenas uma unidade de solicitação, com algumas exceções:

  • MemoryStoreSortedMap:GetRangeAsync()

    Consome unidades com base no número de itens retornados. Por exemplo, se este método retornar 10 itens, a chamada conta como 10 unidades de solicitação. Se retornar uma resposta vazia, conta como uma unidade de solicitação.

  • MemoryStoreQueue:ReadAsync()

    Consome unidades com base no número de itens retornados, assim como MemoryStoreSortedMap:GetRangeAsync(), mas consome uma unidade adicional a cada dois segundos enquanto lê. Especifique o tempo máximo de leitura com o parâmetro waitTimeout.

  • MemoryStoreHashMap:UpdateAsync()

    Consome um mínimo de duas unidades.

  • MemoryStoreHashMap:ListItemsAsync()

    Consome [número de partições escaneadas] + [itens retornados] unidades.

A cota de solicitações também se aplica no nível do jogo em vez do nível do servidor. Isso fornece flexibilidade para alocar as solicitações entre servidores, desde que a taxa total de solicitações não exceda a cota. Se você exceder a cota, receberá uma resposta de erro quando o serviço limitar suas solicitações.

Com o recurso de observabilidade disponível, você pode visualizar a cota de unidade de solicitação do seu jogo em tempo real.

Limites de tamanho da estrutura de dados

Para um único mapa ordenado ou fila, os seguintes limites de tamanho e contagem de itens se aplicam:

  • Número máximo de itens: 1.000.000
  • Tamanho total máximo (incluindo chaves para mapa ordenado): 100 MB

Limites por partição

Além da cota de unidade de solicitação no nível do jogo, os armazenamentos em memória aplicam limites de solicitação a cada partição como uma salvaguarda que protege a estabilidade do serviço para todos os jogos. Esses limites não são uma cota que seu jogo é alocado, e não são um teto rígido sobre a capacidade que seu jogo pode alcançar. Os seguintes valores são estimativas. Eles são configurados no backend do Roblox e podem mudar, então não projete contra eles como números fixos.

Cada solicitação conta para o limite da partição que contém o item, independentemente da estrutura de dados. Você pode atualmente esperar que a limitação comece em aproximadamente 30.000 unidades de solicitação por minuto para uma única partição, então procure ficar bem abaixo dessa taxa. Quanto desse limite uma estrutura de dados consome depende de como seus itens estão distribuídos:

  • Mapas ordenados e filas residem cada um em uma única partição, então cada solicitação a uma dessas estruturas de dados conta para o mesmo limite de partição.
  • Mapas hash espalham seus itens por muitas partições, então o tráfego distribuído entre muitas chaves de item raramente se aproxima do limite de qualquer uma partição.

Os mapas hash têm um limite adicional em cada chave de item de aproximadamente 5.000 unidades de solicitação de gravação por minuto e 15.000 unidades de solicitação de leitura por minuto. Esse limite por chave se aplica além do limite por partição, então uma chave acessada com frequência pode atingir qualquer um deles. O limite por chave se aplica apenas a operações de chave única: o limite de leitura se aplica a MemoryStoreHashMap:GetAsync(), o limite de gravação se aplica a MemoryStoreHashMap:SetAsync() e MemoryStoreHashMap:RemoveAsync(), e MemoryStoreHashMap:UpdateAsync() conta contra os limites de leitura e gravação. MemoryStoreHashMap:ListItemsAsync() escaneia partições em vez de uma única chave, então apenas o limite por partição se aplica a ele.

Se você não precisa de ordenação ou funcionalidade de primeiro a entrar, primeiro a sair, um mapa hash é geralmente a melhor escolha porque pode distribuir a carga entre partições.

Quando as solicitações excedem um limite de partição ou por chave, o serviço as limita e retorna um código de status PartitionRequestsOverLimit, que você pode monitorar com o painel de observabilidade.

Se você espera que uma estrutura de dados ou uma chave de item receba uma alta taxa de solicitações sustentadas, particione para que a carga se espalhe por mais partições ou chaves. Distribua leituras e gravações uniformemente entre várias chaves de item para permanecer dentro dos limites por chave. Você também pode reduzir a taxa de solicitações armazenando valores em cache no servidor e rechecando-os após um intervalo, agrupando solicitações sempre que possível e aplicando retorno exponencial quando você receber respostas de limitação.

Recuperar da exaustão da cota de memória

Se seu jogo receber erros TotalMemoryOverLimit, verifique o gráfico de Uso de Memória no painel de observabilidade. Para retomar gravações que aumentam o uso de memória, exclua itens desnecessários, aguarde a expiração dos itens ou use uma das seguintes opções.

Limpar armazenamentos em memória com Open Cloud

Se você não precisa mais dos dados armazenados, use o endpoint Open Cloud Flush Memory Store para limpar assíncronamente todas as estruturas de dados de armazenamento em memória em um universo para o escopo selecionado.

Para limpar armazenamentos em memória:

  1. Crie uma chave de API com permissões para limpar armazenamentos em memória e obter o status da operação de limpeza para o universo alvo.
  2. Envie uma solicitação POST para https://apis.roblox.com/cloud/v2/universes/{universe_id}/memory-store:flush com a chave de API no cabeçalho x-api-key. Substitua {universe_id} pelo ID do universo do seu jogo. Defina o parâmetro de consulta scope como LIVE para dados de produção ou TEST para dados do Studio. Se você omitir scope, o endpoint usará LIVE.
  3. Use Get Memory Store Flush Operation para consultar a operação retornada pela solicitação de limpeza até que done seja true, e verifique se há um error. Use o mesmo escopo ao consultar. O path retornado já inclui cloud/v2, então consulte em https://apis.roblox.com/{path} sem adicionar outro prefixo.

Os armazenamentos em memória do Studio e da produção são isolados. Limpar um escopo não limpa o outro. Após limpar dados desnecessários, siga as melhores práticas, como tempos de expiração mais curtos e exclusão explícita, para evitar que o uso de memória atinja a cota novamente.

Aumentar a capacidade com Serviços Estendidos

Se seu jogo precisa reter os dados e usar mais armazenamento do que a cota padrão permite, ative os Serviços Estendidos para armazenamentos em memória. Os Serviços Estendidos permitem que você pague pelo armazenamento e solicitações de armazenamento em memória além das cotas padrão.

Para começar, atenda aos requisitos de elegibilidade, adicione detalhes da conta e um método de pagamento, e então selecione seu jogo no Painel do Criador. Em Serviços Estendidos, ative os armazenamentos em memória e defina orçamentos mensais para os recursos que você precisa. Veja Ativar um serviço e Preços de serviço para detalhes.

Os Serviços Estendidos limitam o serviço se o uso exceder seu orçamento. Monitore o uso e a cobrança, e continue a remover dados desnecessários.

Melhores práticas

Para manter seu padrão de uso de memória ideal e evitar atingir os limites, siga estas melhores práticas:

  • Remova itens processados. Limpar consistentemente itens lidos usando o método MemoryStoreQueue:RemoveAsync() para filas e MemoryStoreSortedMap:RemoveAsync() para mapas ordenados pode liberar memória e manter a estrutura de dados atualizada.

  • Defina o tempo de expiração para o menor intervalo de tempo possível ao adicionar dados. Embora o tempo de expiração padrão seja de 45 dias tanto para MemoryStoreQueue:AddAsync() quanto para MemoryStoreSortedMap:SetAsync(), definir o menor tempo possível pode limpar automaticamente dados antigos para evitar que ocupem sua cota de uso de memória.

    • Não armazene uma grande quantidade de dados com uma longa expiração, pois isso pode arriscar exceder sua cota de memória e potencialmente causar problemas que podem quebrar todo o seu jogo.
    • Sempre exclua explicitamente itens desnecessários ou defina uma expiração curta para os itens.
    • Geralmente, você deve usar a exclusão explícita para liberar memória e a expiração de itens como um mecanismo de segurança para evitar que itens não utilizados ocupem memória por um longo período de tempo.
  • Mantenha apenas valores necessários na memória.

    Por exemplo, para um jogo de casa de leilão, você só precisa manter o maior lance. Você pode usar MemoryStoreSortedMap:UpdateAsync() em uma chave para manter o maior lance em vez de manter todos os lances em sua estrutura de dados.

  • Use retorno exponencial para ajudar a ficar abaixo dos limites de solicitações de API.

    Por exemplo, se você receber um DataUpdateConflict, você pode tentar novamente após dois segundos, depois quatro, oito, etc., em vez de enviar constantemente solicitações para MemoryStoreService para obter a resposta correta.

  • Divida grandes estruturas de dados em várias menores por particionamento.

    É frequentemente mais fácil gerenciar dados em estruturas menores do que armazenar tudo em uma grande estrutura de dados. Essa abordagem também pode ajudar a evitar limites de uso e taxa. Por exemplo, se você tiver um mapa ordenado que usa prefixos para suas chaves, considere separar cada prefixo em seu próprio mapa ordenado. Para um jogo especialmente popular, você pode até separar usuários em vários mapas com base nos últimos dígitos de seus IDs de usuário.

  • Particione chaves acessadas com frequência em mapas hash com várias cópias da chave para distribuir a carga.

  • Comprimir valores armazenados.

    Por exemplo, considere usar o algoritmo LZW para reduzir o tamanho do valor armazenado.

  • Inscreva-se nos Serviços Estendidos.

    Para armazenamento ou uso de solicitações além das cotas padrão, ative os Serviços Estendidos para armazenamentos em memória.

Observabilidade

O Painel de Observabilidade fornece insights e análises para monitorar e solucionar problemas de uso do seu armazenamento em memória. Com gráficos que atualizam em tempo real sobre diferentes aspectos do seu uso de memória e solicitações de API, você pode rastrear o padrão de uso de memória do seu jogo, visualizar as cotas alocadas atuais, monitorar o status da API e identificar problemas potenciais para otimização de desempenho.

A tabela a seguir lista e descreve todos os códigos de status das respostas da API disponíveis nos gráficos de Contagem de Solicitações por Status e Solicitações por API x Status do Painel de Observabilidade. Para mais informações sobre como resolver esses erros, veja Solução de Problemas. Para a cota ou limite específico ao qual um erro se relaciona, veja Limites e Cotizações.

Código de statusDescrição
SuccessSucesso.
DataStructureMemoryOverLimitExcede o limite de tamanho de memória no nível da estrutura de dados (100 MB).
DataUpdateConflictConflito devido a atualização concorrente.
AccessDeniedNão autorizado a acessar os dados do jogo. Esta solicitação não consome unidades de solicitação ou usa cota.
InternalErrorErro interno.
InvalidRequestA solicitação não possui as informações necessárias ou possui informações malformadas.
DataStructureItemsOverLimitExcede o limite de contagem de itens no nível da estrutura de dados (1M).
NoItemFoundNenhum item encontrado em MemoryStoreQueue:ReadAsync() ou MemoryStoreSortedMap:UpdateAsync(). ReadAsync() consulta a cada 2 segundos e retorna este código de status até encontrar itens na fila.
DataStructureRequestsOverLimitExcede o limite de unidade de solicitação no nível da estrutura de dados (100.000 unidades de solicitação por minuto).
PartitionRequestsOverLimitExcede um limite de unidade de solicitação por partição ou por chave.
TotalRequestsOverLimitExcede o limite de unidade de solicitação no nível do universo.
TotalMemoryOverLimitExcede a cota de memória no nível do universo.
ItemValueSizeTooLargeO tamanho do valor excede o limite (32 KB).

A tabela a seguir lista códigos de estado do lado do cliente, que atualmente não estão disponíveis no Painel de Observabilidade.

Código de statusDescrição
InternalErrorErro Interno.
UnpublishedPlaceVocê deve publicar este lugar para usar o MemoryStoreService.
InvalidClientAccessMemoryStoreService deve ser chamado do servidor.
InvalidExpirationTimeO campo 'expiration' deve estar entre 0 e 3.888.000.
InvalidRequestIncapaz de converter valor para json.
InvalidRequestIncapaz de converter sortKey para um número ou string válido.
TransformCallbackFailedFalha ao invocar a função de callback de transformação.
RequestThrottledSolicitações recentes de MemoryStores atingiram um ou mais limites.
UpdateConflictExcedeu o número máximo de tentativas.

Solução de Problemas

A tabela a seguir lista e descreve a solução recomendada para cada código de status de resposta:

ErroOpções de solução de problemas
DataStructureRequestsOverLimit / PartitionRequestsOverLimit
  • Adicione um cache local salvando informações em outra variável e rechecando após um certo intervalo de tempo, como 30 segundos.
  • Use o gráfico Contagem de Solicitações por Status para verificar se você está recebendo mais respostas Sucesso do que Nenhum Item Encontrado. Limite a quantidade de vezes que você atinge MemoryStoreService com uma solicitação falhada.
  • Implemente um pequeno atraso entre as solicitações.
  • Siga as melhores práticas, incluindo:
    • Particionar suas estruturas de dados se você receber uma quantidade significativa de respostas DataStructureRequestsOverLimit/PartitionRequestsOverLimit.
    • Particionar suas chaves de mapa hash se você receber uma quantidade significativa de respostas PartitionRequestsOverLimit em chamadas de mapa hash.
    • Reduzir ou agrupar chamadas para estruturas de dados específicas ou chaves de mapa hash se você ver respostas PartitionRequestsOverLimit.
    • Implemente um retorno exponencial para encontrar uma taxa razoável de solicitações a serem enviadas.
TotalRequestsOverLimit
DataStructureItemsOverLimit
DataStructureMemoryOverLimit
TotalMemoryOverLimit
DataUpdateConflict
  • Implemente um pequeno atraso entre as solicitações para evitar que várias solicitações atualizem a mesma chave ao mesmo tempo.
  • Para mapas ordenados, use a função de callback no método MemoryStoreSortedMap:UpdateAsync() para abortar uma solicitação após um certo número de tentativas, como o seguinte exemplo de código mostra:
  • Exemplo de Abortando Solicitação
    local MemoryStoreService = game:GetService("MemoryStoreService")
    local map = MemoryStoreService:GetSortedMap("AuctionItems")
    function placeBid(itemKey, bidAmount)
    map:UpdateAsync(itemKey, function(item)
    item = item or { highestBid = 0 }
    if item.highestBid < bidAmount then
    item.highestBid = bidAmount
    return item
    end
    print("item é "..item.highestBid)
    return nil
    end, 1000)
    end
    placeBid("MyItem", 50)
    placeBid("MyItem", 40)
    print("feito")
  • Investigue para ver se você está chamando MemoryStoreService de forma eficiente para evitar conflitos. Idealmente, você não deve enviar solicitações em excesso.
  • Remova consistentemente itens uma vez que eles sejam lidos usando o método MemoryStoreQueue:RemoveAsync() para filas e MemoryStoreSortedMap:RemoveAsync() para mapas ordenados.
Erro Interno
InvalidRequest
  • Certifique-se de incluir parâmetros corretos e válidos em sua solicitação. Exemplos de parâmetros inválidos incluem:
    • Uma string vazia
    • Uma string que excede o limite de comprimento
ItemValueSizeTooLarge
  • Particione ou divida o valor do item em várias chaves.
    • Para organizar chaves agrupadas, ordene-as alfabeticamente adicionando um prefix à chave.
  • Codificando ou comprimindo valores armazenados.

Testar e depurar no Studio

Os dados em MemoryStoreService são isolados entre o Studio e a produção, então alterar os dados no Studio não afeta o comportamento da produção. Isso significa que suas chamadas de API do Studio não acessam dados de produção, permitindo que você teste com segurança os armazenamentos em memória e novos recursos antes de ir para a produção.

Os testes no Studio têm os mesmos limites e cotas que a produção. Para cotas calculadas com base no número de usuários, a cota resultante pode ser muito pequena, uma vez que você é o único usuário para testes no Studio. Ao testar a partir do Studio, você também pode notar latência ligeiramente maior e taxas de erro elevadas em comparação com o uso na produção devido a algumas verificações adicionais que são realizadas para verificar acesso e permissões.

Para informações sobre como depurar um armazenamento em memória em jogos ao vivo ou ao testar no estúdio, use o Console do Desenvolvedor.

©2026 Roblox Corporation, Roblox, o logotipo Roblox e Powering Imagination estão entre nossas marcas registradas e não registradas nos EUA e em outros países.