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 seu aplicativo.

Pré-requisitos

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

Provisionar o 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 de gateway dedicado com os seguintes detalhes:

   • Gateway Dedicado - Ative a alternância para Provisionado.
   • SKU - Selecione um SKU com o tamanho de computação e memória necessário. O cache integrado usará aproximadamente 50% da memória, e a memória restante será 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ó do tamanho D4. Com base na quantidade de dados que você precisa armazenar em cache e para obter alta disponibilidade, você pode aumentar 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 estiver 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 formas existentes de conexão com o Azure Cosmos DB. Por exemplo, você pode fazer com que um CosmosClient se conecte usando o modo de gateway e o ponto de extremidade de gateway dedicado, enquanto outro CosmosClient usa o modo direto.

Autenticar com 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 que o Azure Cosmos DB. Se você já tiver o RBAC (controle de acesso baseado em função) configurado para operações de plano de dados em sua conta do Azure Cosmos DB, também poderá usá-lo para autenticação no gateway dedicado. Saiba mais sobre o RBAC para operações de plano de dados do Azure Cosmos DB.

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

.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 é o padrão no SDK do .NET. Você deve configurar explicitamente o modo de gateway 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 é o padrão no Java SDK. Você deve configurar explicitamente o modo de gateway 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 seu aplicativo para usar o novo ponto de extremidade de gateway dedicado.

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

   

   Todas as cadeias de conexão de gateway dedicadas seguem o mesmo padrão. Remova documents.azure.com da cadeia de conexão original e substitua-a por sqlx.cosmos.azure.com. Um gateway dedicado sempre terá a mesma cadeia de conexão, mesmo se você removê-lo e reprovisioná-lo.

2. Se você estiver usando o SDK .NET ou Java, defina o modo de conexão para o modo gateway. Esta etapa não é necessária para os SDKs Python e 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 .NET ou Java SDK, o modo de conexão padrão é o modo direto. Para usar o cache integrado, você deve substituir esse padrão.

Ajustar a consistência da solicitação

Você deve garantir que a consistência da solicitação seja de sessão ou eventual. Caso contrário, a solicitação sempre ignorará o cache integrado. A maneira mais fácil de configurar uma consistência específica 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 você quiser apenas que um subconjunto de suas leituras utilize o cache integrado.

Ajustar MaxIntegratedCacheStaleness

Configure MaxIntegratedCacheStalenesso , que é o tempo máximo durante o qual você está disposto a tolerar dados obsoletos armazenados em cache. Recomenda-se definir o MaxIntegratedCacheStaleness mais alto possível, pois isso aumentará a probabilidade de que leituras e consultas de pontos repetidos possam ser acertos de 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 MaxIntegratedCacheStaleness é 5 minutos.

Nota

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

O ajuste do MaxIntegratedCacheStaleness é suportado nestas versões de cada SDK:

SDK	Versões suportadas
SDK do .NET v3	>= 3,30,0
Java SDK v4	>= 4,34,0
Node.js SDK	>=3,17,0
Python SDK	>=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 BypassIntegratedCache opção request para controlar quais solicitações usam o cache integrado. Gravações, leituras de pontos e consultas que ignoram o cache integrado não usarão armazenamento em cache, economizando espaço para outros itens. As solicitações que ignoram o cache ainda são roteadas pelo gateway dedicado. Essas solicitações são atendidas a partir do back-end e custam RUs.

Ignorar o cache é suportado nestas versões de cada SDK:

SDK	Versões suportadas
SDK do .NET v3	>= 3,39,0
Java SDK v4	>= 4,49,0
Node.js SDK	>= 4.1.0
Python SDK	Não suportado

.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 ignorar solicitação de cache integrado não está disponível no SDK do Python.

Verificar acertos de cache

Finalmente, você pode reiniciar seu aplicativo e verificar os acertos de cache integrados para leituras de pontos repetidas ou consultas, vendo se a cobrança de solicitação é 0. Depois de modificar CosmosClient para usar o ponto de extremidade de gateway dedicado, todas as solicitações serão roteadas através do gateway dedicado.

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

• Seu cliente se conecta ao ponto de extremidade de gateway dedicado
• Seu cliente usa o modo gateway (Python e SDKs Node.js sempre usam o modo gateway)
• A consistência do pedido deve ser definida como sessão ou eventual

Nota

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

Próximos passos

• Perguntas frequentes sobre cache integrado
• Descrição geral da cache integrada
• Gateway dedicado