Gerenciar os níveis de coerência no Azure Cosmos DB

  • Artigo

APLICA-SE A: NoSQL

Este artigo explica como gerenciar os níveis de consistência no Azure Cosmos DB. Você aprende como configurar o nível de consistência padrão, substituir a consistência padrão, gerenciar manualmente os tokens de sessão e compreender a métrica PBS (Desatualização Limitada Probabilística).

À medida que você altera a consistência do nível da conta, certifique-se de reimplantar seus aplicativos e fazer as modificações de código necessárias para aplicar essas alterações.

Observação

Recomendamos que você use o módulo Az PowerShell do Azure para interagir com o Azure. Para começar, consulte Instalar o Azure PowerShell. Para saber como migrar para o módulo Az PowerShell, confira Migrar o Azure PowerShell do AzureRM para o Az.

Configurar o nível de consistência padrão

O nível de consistência padrão é o nível de coerência que os clientes usam por padrão.

Para exibir ou modificar o nível de consistência padrão, entre no portal do Azure. Localize a conta do Azure Cosmos DB e abra o painel Consistência Padrão. Escolha o nível de consistência que você gostaria de ter como o novo padrão e escolha Salvar. O portal do Azure também fornece uma visualização dos diferentes níveis de consistência com notas musicais.

Menu de consistência no portal do Azure

Substituir o nível de consistência padrão

Os clientes podem substituir o nível de consistência padrão que é definido pelo serviço. O nível de consistência pode ser definido por solicitação, o que substitui o nível de consistência padrão definido no nível da conta.

Dica

A consistência só pode ser reduzida no nível da instância ou da solicitação do SDK. Para mudar de uma consistência mais fraca para uma mais forte, atualize a consistência padrão da conta do Azure Cosmos DB.

Dica

A substituição do nível de consistência padrão aplica-se somente a leituras dentro do cliente do SDK. Uma conta configurada para consistência forte por padrão ainda gravará e replicará dados de modo síncrono em todas as regiões da conta. Quando a instância ou solicitação do cliente do SDK substituir essa opção por Sessão ou por uma consistência mais fraca, as leituras serão executadas com uma só réplica. Confira Níveis de consistência e taxa de transferência para obter mais detalhes.

SDK .NET

// Override consistency at the client level
documentClient = new DocumentClient(new Uri(endpoint), authKey, connectionPolicy, ConsistencyLevel.Eventual);

// Override consistency at the request level via request options
RequestOptions requestOptions = new RequestOptions { ConsistencyLevel = ConsistencyLevel.Eventual };

var response = await client.ReadDocumentAsync(collectionUri, document, requestOptions);

SDK do Java v4

API assíncrona do SDK do Java V4 (Maven com.azure::azure-cosmos)


CosmosAsyncClient client =
        new CosmosClientBuilder()
                .endpoint(HOST)
                .key(MASTER_KEY)
                .consistencyLevel(ConsistencyLevel.EVENTUAL)
                .buildAsyncClient();

Java V2 SDKs

SDK do Java Assíncrono V2 (Maven com.microsoft.azure::azure-cosmosdb)

// Override consistency at the client level
ConnectionPolicy policy = new ConnectionPolicy();

AsyncDocumentClient client =
        new AsyncDocumentClient.Builder()
                .withMasterKey(this.accountKey)
                .withServiceEndpoint(this.accountEndpoint)
                .withConsistencyLevel(ConsistencyLevel.Eventual)
                .withConnectionPolicy(policy).build();

SDK de Node.js/JavaScript/TypeScript

// Override consistency at the client level
const client = new CosmosClient({
  /* other config... */
  consistencyLevel: ConsistencyLevel.Eventual
});

// Override consistency at the request level via request options
const { body } = await item.read({ consistencyLevel: ConsistencyLevel.Eventual });

SDK do Python

# Override consistency at the client level
connection_policy = documents.ConnectionPolicy()
client = cosmos_client.CosmosClient(self.account_endpoint, {
                                    'masterKey': self.account_key}, connection_policy, documents.ConsistencyLevel.Eventual)

Utilizar tokens de sessão

Um dos níveis de consistência no Azure Cosmos DB é a consistência de Sessão. Esse é o nível padrão aplicado às contas do Azure Cosmos DB por padrão. Ao trabalhar com consistência de Sessão, cada nova solicitação de gravação para o Azure Cosmos DB recebe um novo SessionToken. O CosmosClient usará esse token internamente com cada solicitação de consulta/leitura para garantir que o nível de consistência definido seja mantido.

Em alguns cenários, você mesmo precisará gerenciar essa sessão. Considere um aplicativo Web com vários nós, cada nó terá sua própria instância do CosmosClient. Se você quiser que esses nós participem da mesma sessão (para poder ler suas próprias gravações de forma consistente nas camadas da Web), terá que enviar o SessionToken do FeedResponse<T> da ação de gravação ao usuário final usando um cookie ou outro mecanismo e fazer esse token retornar à camada da Web e, por fim, o CosmosClient para leituras subsequentes. Se você estiver usando um balanceador de carga de distribuição equilibrada que não mantém a afinidade de sessão entre as solicitações, como o Azure Load Balancer, a leitura poderá chegar a um nó diferente da solicitação de gravação, onde a sessão foi criada.

Se você não transmitir o SessionToken do Azure Cosmos DB, conforme descrito acima, poderá acabar com resultados de leitura inconsistentes por um período de tempo.

Os Tokens de Sessão no Azure Cosmos DB são vinculados à partição, o que significa que são associados exclusivamente a uma partição. Para garantir que você possa ler suas gravações, use o último token de sessão que foi gerado para os itens relevantes. Para gerenciar os tokens de sessão manualmente, obtenha o token de sessão na resposta e configure-os por solicitação. Se não for necessário gerenciar manualmente os tokens de sessão, você não precisa usar esses exemplos. O SDK controla os tokens de sessão automaticamente. Se você não definir o token de sessão manualmente, por padrão, o SDK usará o token de sessão mais recente.

SDK .NET

var response = await client.ReadDocumentAsync(
                UriFactory.CreateDocumentUri(databaseName, collectionName, "SalesOrder1"));
string sessionToken = response.SessionToken;

RequestOptions options = new RequestOptions();
options.SessionToken = sessionToken;
var response = await client.ReadDocumentAsync(
                UriFactory.CreateDocumentUri(databaseName, collectionName, "SalesOrder1"), options);

SDK do Java v4

API assíncrona do SDK do Java V4 (Maven com.azure::azure-cosmos)


// Get session token from response
CosmosItemResponse<JsonNode> response = container.readItem(itemId, new PartitionKey(partitionKey), JsonNode.class).block();
String sessionToken = response.getSessionToken();

// Resume the session by setting the session token on the RequestOptions
CosmosItemRequestOptions options = new CosmosItemRequestOptions();
options.setSessionToken(sessionToken);
CosmosItemResponse<JsonNode> response2 = container.readItem(itemId, new PartitionKey(partitionKey), JsonNode.class).block();

Java V2 SDKs

SDK do Java Assíncrono V2 (Maven com.microsoft.azure::azure-cosmosdb)

// Get session token from response
RequestOptions options = new RequestOptions();
options.setPartitionKey(new PartitionKey(document.get("mypk")));
Observable<ResourceResponse<Document>> readObservable = client.readDocument(document.getSelfLink(), options);
readObservable.single()           // we know there will be one response
  .subscribe(
      documentResourceResponse -> {
          System.out.println(documentResourceResponse.getSessionToken());
      },
      error -> {
          System.err.println("an error happened: " + error.getMessage());
      });

// Resume the session by setting the session token on RequestOptions
RequestOptions options = new RequestOptions();
requestOptions.setSessionToken(sessionToken);
Observable<ResourceResponse<Document>> readObservable = client.readDocument(document.getSelfLink(), options);

SDK de Node.js/JavaScript/TypeScript

// Get session token from response
const { headers, item } = await container.items.create({ id: "meaningful-id" });
const sessionToken = headers["x-ms-session-token"];

// Immediately or later, you can use that sessionToken from the header to resume that session.
const { body } = await item.read({ sessionToken });

SDK do Python

// Get the session token from the last response headers
item = client.ReadItem(item_link)
session_token = client.last_response_headers["x-ms-session-token"]

// Resume the session by setting the session token on the options for the request
options = {
    "sessionToken": session_token
}
item = client.ReadItem(doc_link, options)

Monitorar métrica PBS (Desatualização Limitada Probabilística)

Quão eventual é a consistência eventual? Para o caso médio, podemos oferece limites de desatualização com relação ao histórico de versão e à hora. A métrica PBS (desatualização limitada probabilística) tenta quantificar a probabilidade de desatualização e mostra-a como uma métrica.

Para exibir a métrica PBS, vá para a conta do Azure Cosmos DB no portal do Azure. Abra o painel Métricas (Clássico) e selecione a guia Consistência. Observe o grafo chamado Probabilidade de leituras altamente consistentes com base na sua carga de trabalho (confira o PBS).

Gráfico PBS no portal do Azure

Próximas etapas

Saiba mais sobre como gerenciar conflitos de dados ou passar para o próximo conceito fundamental no Azure Cosmos DB. Veja os artigos a seguir: