Gerenciar os níveis de coerência no Azure Cosmos DBManage consistency levels in Azure Cosmos DB

Este artigo explica como gerenciar os níveis de consistência no Azure Cosmos DB.This article explains how to manage consistency levels in 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).You learn how to configure the default consistency level, override the default consistency, manually manage session tokens, and understand the Probabilistically Bounded Staleness (PBS) metric.

Observação

Este artigo foi atualizado para usar o novo módulo Az do Azure PowerShell.This article has been updated to use the new Azure PowerShell Az module. Você ainda pode usar o módulo AzureRM, que continuará a receber as correções de bugs até pelo menos dezembro de 2020.You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. Para saber mais sobre o novo módulo Az e a compatibilidade com o AzureRM, confira Apresentação do novo módulo Az do Azure PowerShell.To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. Para obter instruções de instalação do módulo Az, confira Instalar o Azure PowerShell.For Az module installation instructions, see Install Azure PowerShell.

Configurar o nível de consistência padrãoConfigure the default consistency level

O nível de consistência padrão é o nível de coerência que os clientes usam por padrão.The default consistency level is the consistency level that clients use by default. Os clientes sempre podem substituí-lo.Clients can always override it.

CLICLI

# create with a default consistency
az cosmosdb create --name <name of Cosmos DB Account> --resource-group <resource group name> --default-consistency-level Session

# update an existing account's default consistency
az cosmosdb update --name <name of Cosmos DB Account> --resource-group <resource group name> --default-consistency-level Eventual

PowerShellPowerShell

Este exemplo cria uma nova conta do Azure Cosmos com várias regiões de gravação habilitadas, nas regiões Leste dos EUA e Oeste dos EUA.This example creates a new Azure Cosmos account with multiple write regions enabled, in East US and West US regions. O nível de consistência padrão é definido como consistência de Sessão.The default consistency level is set to Session consistency.

$locations = @(@{"locationName"="East US"; "failoverPriority"=0},
             @{"locationName"="West US"; "failoverPriority"=1})

$iprangefilter = ""

$consistencyPolicy = @{"defaultConsistencyLevel"="Session"}

$CosmosDBProperties = @{"databaseAccountOfferType"="Standard";
                        "locations"=$locations;
                        "consistencyPolicy"=$consistencyPolicy;
                        "ipRangeFilter"=$iprangefilter;
                        "enableMultipleWriteLocations"="true"}

New-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
  -ApiVersion "2015-04-08" `
  -ResourceGroupName "myResourceGroup" `
  -Location "East US" `
  -Name "myCosmosDbAccount" `
  -Properties $CosmosDBProperties

Portal do AzureAzure portal

Para exibir ou modificar o nível de consistência padrão, entre no portal do Azure.To view or modify the default consistency level, sign in to the Azure portal. Localize a conta do Azure Cosmos e abra o painel Consistência padrão.Find your Azure Cosmos account, and open the Default consistency pane. Escolha o nível de consistência que você gostaria de ter como o novo padrão e escolha Salvar.Select the level of consistency you want as the new default, and then select Save. O portal do Azure também fornece uma visualização dos diferentes níveis de consistência com notas musicais.The Azure portal also provides a visualization of different consistency levels with music notes.

Menu de consistência no portal do Azure

Substituir o nível de consistência padrãoOverride the default consistency level

Os clientes podem substituir o nível de consistência padrão que é definido pelo serviço.Clients can override the default consistency level that is set by the service. 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.Consistency level can be set on a per request, which overrides the default consistency level set at the account level.

SDK do .NET V2.NET SDK V2

// 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.CreateDocumentAsync(collectionUri, document, requestOptions);

SDK do .NET V3.NET SDK V3

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

var response = await client.GetContainer(databaseName, containerName)
    .CreateItemAsync(
        item, 
        new PartitionKey(itemPartitionKey), 
        requestOptions);

SDK de Java AssíncronoJava Async SDK

// 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 Java SíncronoJava Sync SDK

// Override consistency at the client level
ConnectionPolicy connectionPolicy = new ConnectionPolicy();
DocumentClient client = new DocumentClient(accountEndpoint, accountKey, connectionPolicy, ConsistencyLevel.Eventual);

SDK de Node.js/JavaScript/TypeScriptNode.js/JavaScript/TypeScript SDK

// 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 PythonPython SDK

# 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ãoUtilize session tokens

Um dos níveis de consistência no Azure Cosmos DB é a consistência de Sessão.One of the consistency levels in Azure Cosmos DB is Session consistency. Esse é o nível padrão aplicado a contas do Cosmos por padrão.This is the default level applied to Cosmos accounts by default. Ao trabalhar com a consistência de Sessão, o cliente usará um token de sessão internamente com cada solicitação de leitura/consulta para garantir que o nível de consistência definido seja mantido.When working with Session consistency, the client will use a session token internally with each read/query request to ensure that the set consistency level is maintained.

Para gerenciar os tokens de sessão manualmente, obtenha o token de sessão na resposta e configure-os por solicitação.To manage session tokens manually, get the session token from the response and set them per request. Se não for necessário gerenciar manualmente os tokens de sessão, você não precisa usar esses exemplos.If you don't need to manage session tokens manually, you don't need to use these samples. O SDK controla os tokens de sessão automaticamente.The SDK keeps track of session tokens automatically. Se você não definir o token de sessão manualmente, por padrão, o SDK usará o token de sessão mais recente.If you don't set the session token manually, by default, the SDK uses the most recent session token.

SDK do .NET V2.NET SDK V2

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 .NET V3.NET SDK V3

Container container = client.GetContainer(databaseName, collectionName);
ItemResponse<SalesOrder> response = await container.CreateItemAsync<SalesOrder>(salesOrder);
string sessionToken = response.Headers.Session;

ItemRequestOptions options = new ItemRequestOptions();
options.SessionToken = sessionToken;
ItemResponse<SalesOrder> response = await container.ReadItemAsync<SalesOrder>(salesOrder.Id, new PartitionKey(salesOrder.PartitionKey), options);

SDK de Java AssíncronoJava Async SDK

// 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 Java SíncronoJava Sync SDK

// Get session token from response
ResourceResponse<Document> response = client.readDocument(documentLink, null);
String sessionToken = response.getSessionToken();

// Resume the session by setting the session token on the RequestOptions
RequestOptions options = new RequestOptions();
options.setSessionToken(sessionToken);
ResourceResponse<Document> response = client.readDocument(documentLink, options);

SDK de Node.js/JavaScript/TypeScriptNode.js/JavaScript/TypeScript SDK

// 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 PythonPython SDK

// 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)Monitor Probabilistically Bounded Staleness (PBS) metric

Quão eventual é a consistência eventual?How eventual is eventual consistency? Para o caso médio, podemos oferecer limites de desatualização com relação ao histórico de versão e à hora.For the average case, can we offer staleness bounds with respect to version history and time. A métrica PBS (desatualização limitada probabilística) tenta quantificar a probabilidade de desatualização e mostra-a como uma métrica.The Probabilistically Bounded Staleness (PBS) metric tries to quantify the probability of staleness and shows it as a metric. Para exibir a métrica PBS, vá para a conta do Azure Cosmos no portal do Azure.To view the PBS metric, go to your Azure Cosmos account in the Azure portal. Abra o painel Métricas e escolha a guia Consistência. Examine o gráfico chamado Probabilidade de leituras altamente consistentes com base em sua carga de trabalho (confira PBS) .Open the Metrics pane, and select the Consistency tab. Look at the graph named Probability of strongly consistent reads based on your workload (see PBS).

Gráfico PBS no portal do Azure

Próximas etapasNext steps

Saiba mais sobre como gerenciar conflitos de dados ou passar para o próximo conceito fundamental no Azure Cosmos DB.Learn more about how to manage data conflicts, or move on to the next key concept in Azure Cosmos DB. Confira os seguintes artigos:See the following articles: