Como configurar o cache integrado do Azure Cosmos DB

APLICA-SE A: NoSQL

Este artigo descreve como provisionar um gateway dedicado, configurar o cache integrado e conectar o aplicativo.

Pré-requisitos

• Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.
• Um aplicativo existente que usa o Azure Cosmos DB. Se você não tiver um, obtenha aqui alguns exemplos.
• Uma conta da API do Azure Cosmos DB para NoSQL.

Provisionamento do gateway dedicado

1. Navegue até uma conta do Azure Cosmos DB no portal do Azure e selecione a guia Gateway Dedicado.

   

2. Preencha o formulário Gateway dedicado com os seguintes dados:

   • Gateway Dedicado – Altere para Provisionado.
   • SKU – selecione um SKU com o tamanho de computação e memória necessários. O cache integrado usará cerca de 50% da memória e a memória restante é usada para metadados e solicitações de roteamento para as partições de back-end.
   • Número de instâncias – número de nós. Para fins de desenvolvimento, recomendamos começar com um nó de tamanho D4. Com base na quantidade de dados que você precisa armazenar em cache e para atingir a alta disponibilidade, aumente o tamanho do nó após o teste inicial.

   

3. Selecione Salvar e aguarde cerca de 5 a 10 minutos para que o provisionamento do gateway dedicado seja concluído. Quando o provisionamento for concluído, você verá a seguinte notificação:

   

Configuração do cache integrado

Quando você cria um gateway dedicado, um cache integrado é provisionado automaticamente.

1. Modifique a cadeia de conexão do aplicativo para usar o novo ponto de extremidade de gateway dedicado.

   A cadeia de conexão atualizada de gateway dedicado está na folha Chaves:

   

   Todas as cadeias de conexão do gateway dedicado seguem o mesmo padrão. Remova documents.azure.com da cadeia de conexão original e substitua por sqlx.cosmos.azure.com. Um gateway dedicado sempre terá a mesma cadeia de conexão, mesmo se você remover e provisionar novamente a cadeia.

   Não é necessário modificar a cadeia de conexão em todos os aplicativos usando a mesma conta do Azure Cosmos DB. Por exemplo, você pode ter uma conexão CosmosClient usando o modo de gateway e o ponto de extremidade de gateway dedicado, enquanto outro CosmosClient usa o modo direto. Em outras palavras, a adição de um gateway dedicado não afeta as maneiras existentes de se conectar ao Azure Cosmos DB.

2. Se estiver usando o SDK do .NET ou Java, defina o modo de conexão como modo gateway. Esta etapa não é necessária para os SDKs do Python e do Node.js, pois eles não têm opções adicionais de conexão, além do modo gateway.

Observação

Se você estiver usando a versão mais recente do SDK do .NET ou do Java, o modo de conexão padrão será o modo direto. Para usar o cache integrado, você deve substituir esse padrão.

Ajustar a consistência da solicitação

Você precisa garantir que a consistência da solicitação seja sessão ou eventual. Caso contrário, a solicitação sempre irá ignorar o cache integrado. A maneira mais fácil de configurar a consistência para Eventual para todas as operações de leitura, é defini-la no nível da conta. Você também pode configurar a consistência no nível da solicitação, o que é recomendado se quiser que apenas um subconjunto das leituras utilize o cache integrado.

Observação

Se estiver usando o SDK do Python, você precisa definir explicitamente o nível de consistência para cada solicitação. A configuração padrão no nível de conta não será aplicada automaticamente.

Ajustar MaxIntegratedCacheStaleness

Configure MaxIntegratedCacheStaleness, que é o tempo máximo no qual você está disposto a tolerar dados armazenados em cache obsoletos. É recomendável definir MaxIntegratedCacheStaleness com o nível mais alto possível, pois isso aumentará a probabilidade de que leituras e consultas de ponto repetidas sejam ocorrências no cache. Se você definir MaxIntegratedCacheStaleness como 0, sua solicitação de leitura nunca usará o cache integrado, independentemente do nível de consistência. Quando não configurado, o padrão de MaxIntegratedCacheStaleness é 5 minutos.

Observação

O MaxIntegratedCacheStaleness pode ser definido para até 10 anos. Na prática, esse valor é a inatividade máxima e o cache pode ser redefinido mais cedo devido a reinicializações de nó que podem ocorrer.

O ajuste de MaxIntegratedCacheStaleness é compatível com estas versões de cada SDK:

.	Versões com suporte
SDK v3 do .NET	>= 3.30.0
SDK do Java v4	>= 4.34.0
SDK do Node.js	>=3.17.0
SDK do Python	>=4.3.1

.NET

FeedIterator<MyClass> myQuery = container.GetItemQueryIterator<MyClass>(new QueryDefinition("SELECT * FROM c"), requestOptions: new QueryRequestOptions
        {
            DedicatedGatewayRequestOptions = new DedicatedGatewayRequestOptions 
            { 
                MaxIntegratedCacheStaleness = TimeSpan.FromMinutes(30) 
            }
        }
);

Java

DedicatedGatewayRequestOptions dgOptions = new DedicatedGatewayRequestOptions()
   .setMaxIntegratedCacheStaleness(Duration.ofMinutes(30));
CosmosQueryRequestOptions queryOptions = new CosmosQueryRequestOptions()
   .setDedicatedGatewayRequestOptions(dgOptions);

CosmosPagedFlux<MyClass> pagedFluxResponse = container.queryItems(
        "SELECT * FROM c", queryOptions, MyClass.class);

Node.js

 const queryRequestOptions = {
   maxIntegratedCacheStalenessInMs: 1800000 };
 const querySpec = {
   query: "SELECT * from c"
 };
 const { resources: items } = await container.items
   .query(querySpec, queryRequestOptions)
   .fetchAll();

Python

query = "SELECT * FROM c"
container.query_items(
    query=query,
    max_integrated_cache_staleness_in_ms=1800000
)

Ignorar o cache integrado (versão prévia)

Use a opção se solicitação BypassIntegratedCache para controlar quais solicitações usam o cache integrado. Gravações, leituras de ponto e consultas que ignoram o cache integrado não usarão o armazenamento em cache, economizando espaço para outros itens. As solicitações que ignoram o cache ainda são roteada por meio do gateway dedicado. Essas solicitações são atendidas nas RUs de back-end e de custo.

Há suporte para ignorar o cache nestas versões de cada SDK:

.	Versões com suporte
SDK v3 do .NET	>= 3.35.0-preview
SDK do Java v4	>= 4.49.0
SDK do Node.js	Sem suporte
SDK do Python	Sem suporte

.NET

FeedIterator<MyClass> myQuery = container.GetItemQueryIterator<MyClass>(new QueryDefinition("SELECT * FROM c"), requestOptions: new QueryRequestOptions
        {
            DedicatedGatewayRequestOptions = new DedicatedGatewayRequestOptions 
            { 
                BypassIntegratedCache = true
            }
        }
);

Java

DedicatedGatewayRequestOptions dgOptions = new DedicatedGatewayRequestOptions()
   .setIntegratedCacheBypassed(true);
CosmosQueryRequestOptions queryOptions = new CosmosQueryRequestOptions()
   .setDedicatedGatewayRequestOptions(dgOptions);

CosmosPagedFlux<MyClass> pagedFluxResponse = container.queryItems(
        "SELECT * FROM c", queryOptions, MyClass.class);

Node.js

A opção de ignorar a solicitação de cache integrada não está disponível no SDK do Node.js.

Python

A opção de ignorar a solicitação de cache integrada não está disponível no SDK do Python.

Verificar ocorrências no cache

Por fim, reinicie o aplicativo e verifique as ocorrências no cache integrado de leituras ou consultas de ponto repetidas observando se o encargo da solicitação é 0. Depois de modificar o CosmosClient para usar o ponto de extremidade do gateway dedicado, todas as solicitações serão roteadas por meio do gateway dedicado.

Para que uma solicitação de leitura (leitura de ponto ou consulta) utilize o cache integrado, todos os seguintes critérios devem ser verdadeiros:

• Seu cliente se conecta ao ponto de extremidade do gateway dedicado
• Seu cliente usa o modo de gateway (Os SKDs Python e Node.js sempre usam o modo gateway)
• A consistência da solicitação deve estar definida para sessão ou eventual

Observação

Você tem algum comentário sobre o cache integrado? Queremos saber sua opinião! Sinta-se à vontade para compartilhar comentários diretamente com a equipe de engenharia do Azure Cosmos DB: cosmoscachefeedback@microsoft.com

Próximas etapas

• Perguntas frequentes sobre cache integrado
• Visão geral do cache integrado
• Gateway dedicado