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:

   

Configurar seu aplicativo para usar o cache integrado

Quando você provisiona um gateway dedicado, um cache integrado é criado automaticamente. Você não precisa conectar todos os aplicativos que usam o Azure Cosmos DB ao gateway dedicado se eles não precisarem usar o cache integrado. Adicionar um gateway dedicado não afeta as maneiras existentes de se conectar ao 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.

Autenticar com o controle de acesso baseado em função

O gateway dedicado usa as mesmas permissões, definições de função e atribuições de função do Azure Cosmos DB. Se já tiver o controle de acesso baseado em função (RBAC) configurado para operações de plano de dados na sua conta do Azure Cosmos DB, você também poderá usá-lo para autenticação no gateway dedicado. Saiba mais sobre o RBAC para operações do plano de dados do Azure Cosmos DB.

Configure seu CosmosClient definindo o ponto de extremidade e a credencial do gateway dedicado e configurando o modo de conectividade do gateway. Todos os pontos de extremidade de gateway dedicados seguem o mesmo padrão. Remova o documents.azure.com do seu ponto de extremidade original e o substitua por sqlx.cosmos.azure.com. Um gateway dedicado sempre terá o mesmo ponto de extremidade, mesmo se você removê-lo e provisioná-lo novamente.

.NET

using Azure.Core;
using Azure.Identity;
using Microsoft.Azure.Cosmos;

string endpoint = "<dedicated-gateway-endpoint>";

TokenCredential credential = new DefaultAzureCredential();

CosmosClient client = new(endpoint, credential, new CosmosClientOptions { ConnectionMode = ConnectionMode.Gateway });

Importante

O modo de conectividade direta é padrão no SDK do .NET. Você precisa configurar o modo gateway explicitamente para usar o gateway dedicado.

Java

import com.azure.cosmos.CosmosClient;
import com.azure.cosmos.CosmosClientBuilder;
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

public class NoSQL{
    public static void main(String[] args){
        DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
            .build();
        
        CosmosClient client = new CosmosClientBuilder()
            .endpoint("<dedicated-gateway-endpoint>")
            .gatewayMode()
            .credential(credential);
            .buildClient();
    }
}

Importante

O modo de conectividade direta é padrão no SDK do Java. Você precisa configurar o modo gateway explicitamente para usar o gateway dedicado.

Node.js

const { CosmosClient } = require('@azure/cosmos');
const { DefaultAzureCredential } = require('@azure/identity');

const endpoint = '<dedicated-gateway-endpoint>';

const credential = new DefaultAzureCredential();

const client = new CosmosClient({ endpoint, aadCredentials:credential})

Python

from azure.cosmos import CosmosClient
from azure.identity import DefaultAzureCredential

endpoint = "<dedicated-gateway-endpoint>"

credential = DefaultAzureCredential()

client = CosmosClient(endpoint, credential=credential)

Autenticar com cadeias de conexão

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.

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.

Importante

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.

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

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.39.0
SDK do Java v4	>= 4.49.0
SDK do Node.js	>= 4.1.0
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

    const queryRequestOptions = {
      bypassIntegratedCache: true };
    const querySpec = {
      query: "SELECT * from c"
    };
    const { resources: items, requestCharge: queryCharge } = await container.items
      .query(querySpec, queryRequestOptions)
      .fetchAll();

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