Administración de los niveles de coherencia en Azure Cosmos DB

  • Artículo

SE APLICA A: NoSQL

Este artículo explica cómo administrar los niveles de coherencia en Azure Cosmos DB. Aprenderá a configurar el nivel de coherencia predeterminado, invalidar la coherencia predeterminada, administrar manualmente tokens de sesión y comprender la métrica de obsolescencia limitada por probabilidades (PBS).

A medida que cambie la coherencia del nivel de cuenta, asegúrese de volver a implementar sus aplicaciones y realizar las modificaciones de código necesarias para aplicar estos cambios.

Nota

Se recomienda usar el módulo Azure Az de PowerShell para interactuar con Azure. Consulte Instalación de Azure PowerShell para empezar. Para más información sobre cómo migrar al módulo Az de PowerShell, consulte Migración de Azure PowerShell de AzureRM a Az.

Configuración del nivel de coherencia predeterminado

El nivel de coherencia predeterminado es el que los clientes usan de forma predeterminada.

Para ver o modificar el nivel de coherencia predeterminado, inicie sesión en Azure Portal. Busque la cuenta de Azure Cosmos DB y abra el panel Coherencia predeterminada. Seleccione el nivel de coherencia que desee como el nuevo valor predeterminado y, a continuación, seleccione Guardar. Azure Portal también proporciona una visualización de los diferentes niveles de coherencia con notas musicales.

Menú de coherencia en Azure Portal

Invalidación del nivel de coherencia predeterminado

Los clientes pueden invalidar el nivel de coherencia predeterminado establecido por el servicio. El nivel de coherencia se puede establecer por cada solicitud, lo que invalida el nivel de coherencia predeterminado establecido en el nivel de cuenta.

Sugerencia

La coherencia solo se puede relajar en el nivel de solicitud o de instancia del SDK. Para pasar de una coherencia más débil a una más fuerte, actualice la coherencia predeterminada para la cuenta de Azure Cosmos DB.

Sugerencia

La invalidación del nivel de coherencia predeterminado solo se aplica a las lecturas dentro del cliente del SDK. Una cuenta configurada para una coherencia fuerte, de manera predeterminada sigue escribiendo y replicando datos de forma sincrónica en todas las regiones de la cuenta. Cuando la instancia o solicitud del cliente del SDK invalida esta configuración con el valor De sesión o uno más débil, las lecturas se realizan con una única réplica. Para obtener más detalles, consulte Rendimiento y niveles de coherencia.

.NET SDK

// 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 de Java V4

API asincrónica del SDK para Java V4 (Maven com.azure::azure-cosmos)


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

SDK de Java V2

SDK de Java v2 asincrónico (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 para 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 de 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)

Uso de tokens de sesión

Uno de los niveles de coherencia de Azure Cosmos DB es Sesión. Este es el nivel predeterminado que se aplica a las cuentas de Azure Cosmos DB de forma predeterminada. Al trabajar con coherencia de sesión, a cada nueva solicitud de escritura en Azure Cosmos DB se le asigna un nuevo SessionToken. CosmosClient usará este token internamente con cada solicitud de lectura o consulta para asegurarse de que se mantiene el nivel de coherencia establecido.

En algunos escenarios, debe administrar esta sesión usted mismo. Considere una aplicación web con varios nodos, donde cada nodo tendrá su propia instancia de CosmosClient. Si quisiera que estos nodos participaran en la misma sesión (para poder leer sus propias escrituras de forma coherente en los niveles web), tendría que enviar SessionToken desde FeedResponse<T> de la acción de escritura al usuario final mediante una cookie u otro mecanismo, y hacer que ese token fluya de vuelta al nivel web y, en última instancia, a CosmosClient para las lecturas posteriores. Si usa un equilibrador de carga round robin que no mantiene la afinidad de sesión entre las solicitudes, como Azure Load Balancer, la lectura podría llegar a un nodo diferente a la solicitud de escritura, donde se creó la sesión.

Si SessionToken de Azure Cosmos DB no fluye tal y como se describió anteriormente, podría acabar con resultados de lectura incoherentes durante un período de tiempo.

Los tokens de sesión en Azure Cosmos DB están vinculados a una partición, lo que significa que están asociados exclusivamente a una partición. Para asegurarse de que puede leer sus escrituras, utilice el testigo de sesión que se generó por última vez para el elemento o elementos correspondientes. Para administrar los tokens de sesión manualmente, obtenga el token de sesión de la respuesta y establézcalos por cada solicitud. Si no tiene la necesidad de administrar manualmente los tokens de sesión, no es necesario que utilice estos ejemplos. El SDK realiza el seguimiento de los tokens de sesión automáticamente. Si no establece el token de sesión manualmente, el SDK usa el token de sesión más reciente de forma predeterminada.

.NET SDK

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 de Java V4

API asincrónica del SDK para 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();

SDK de Java V2

SDK de Java v2 asincrónico (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 para 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 de 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)

Supervisión de la métrica de obsolescencia limitada de manera probabilística (PBS)

¿Cómo de eventual es la coherencia eventual? Por término medio, se puede ofrecer obsolescencia limitada con respecto al historial de versiones y la hora. La métrica Obsolescencia limitada de manera probabilística (PBS) intenta cuantificar la probabilidad de obsolescencia y la muestra como una métrica.

Para ver la métrica de PBS, vaya a la cuenta de Azure Cosmos DB en Azure Portal. Abra el panel Métricas (clásicas) y seleccione la pestaña Coherencia. Examine el gráfico denominado Probabilidad de lecturas altamente coherentes en función de la carga de trabajo (vea PBS).

Gráfico de PBS en Azure Portal

Pasos siguientes

Aprenda cómo administrar los conflictos de datos o pase al siguiente concepto principal de Azure Cosmos DB. Vea los artículos siguientes: