Gérer les niveaux de cohérence dans Azure Cosmos DB

  • Article

S’APPLIQUE À : NoSQL

Cet article explique comment gérer les niveaux de cohérence dans Azure Cosmos DB. Vous apprenez à configurer le niveau de cohérence par défaut, à remplacer la cohérence par défaut, à gérer manuellement les jetons de session et à comprendre la métrique PBS (Probabilistically Bounded Staleness).

Lorsque vous modifiez la cohérence au niveau de votre compte, veillez à redéployer vos applications et à apporter les modifications de code nécessaires pour appliquer ces modifications.

Remarque

Nous vous recommandons d’utiliser le module Azure Az PowerShell pour interagir avec Azure. Pour bien démarrer, consultez Installer Azure PowerShell. Pour savoir comment migrer vers le module Az PowerShell, consultez Migrer Azure PowerShell depuis AzureRM vers Az.

Configurer le niveau de cohérence par défaut

Le niveau de cohérence par défaut est le niveau de cohérence que les clients utilisent par défaut.

Pour afficher ou modifier le niveau de cohérence par défaut, connectez-vous au portail Azure. Recherchez votre compte Azure Cosmos DB et ouvrez le volet Cohérence par défaut. Sélectionnez le niveau de cohérence que vous souhaitez utiliser comme nouvelle valeur par défaut, puis sélectionnez Enregistrer. Le portail Azure permet également de visualiser les différents niveaux de cohérence grâce à des notes de musique.

Menu Cohérence dans le portail Azure

Remplacer le niveau de cohérence par défaut

Les clients peuvent remplacer le niveau de cohérence par défaut, qui est défini par le service. Le niveau de cohérence peut être défini par demande, ce qui remplace le niveau de cohérence par défaut défini au niveau du compte.

Conseil

La cohérence ne peut être que souple au niveau de l'instance du Kit de développement logiciel (SDK) ou de la requête. Pour passer d’une cohérence plus faible à une cohérence renforcée, mettez à jour la cohérence par défaut du compte Azure Cosmos DB.

Conseil

Le remplacement du niveau de cohérence par défaut s’applique uniquement aux lectures au sein du client de Kit de développement logiciel (SDK). Un compte configuré pour une cohérence forte par défaut continuera à écrire et à répliquer les données de façon synchrone dans chaque région du compte. Lorsque la requête ou l’instance du client de Kit de développement logiciel (SDK) remplace cette opération par une cohérence de session ou une cohérence plus faible, les lectures sont effectuées en utilisant un seul réplica. Pour en savoir plus, consultez Niveaux de cohérence et débit.

Kit de développement logiciel (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 Java V4

API asynchrone du kit SDK Java V4 (Maven com.azure::azure-cosmos)


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

Kits de développement logiciel (SDK) Java v2

Kit de développement logiciel (SDK) Async Java 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();

Kit SDK 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 });

Kit de développement logiciel (SDK) 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)

Utiliser des jetons de session

Parmi les différents niveaux de cohérence rencontrés dans Azure Cosmos DB figure la cohérence Session. Il s’agit du niveau appliqué par défaut aux comptes Azure Cosmos DB. Lors de l’utilisation de la cohérence de session, chaque nouvelle demande d’écriture à Azure Cosmos DB est attribuée à une nouvelle SessionToken. Le CosmosClient utilise ce jeton en interne avec chaque demande de lecture/requête pour s’assurer que le niveau de cohérence défini est conservé.

Dans certains scénarios, vous devez gérer cette session vous-même. Prenons l’exemple d’une application web avec plusieurs nœuds, où chaque nœud a sa propre instance de CosmosClient. Si vous souhaitez que ces nœuds participent à la même session (pour pouvoir lire vos propres écritures de manière cohérente sur tous les niveaux Web), vous devrez envoyer le SessionToken de FeedResponse<T> de l'action d'écriture à l'utilisateur final à l'aide d'un cookie ou d'un autre mécanisme, et faire en sorte que ce jeton revienne au niveau Web et finalement au CosmosClient pour les lectures ultérieures. Si vous utilisez un équilibreur de charge de tourniquet qui ne conserve pas l’affinité de session entre les requêtes, comme Azure Load Balancer, la lecture peut potentiellement atterrir sur un nœud différent de la demande d’écriture, où la session a été créée.

Si vous ne circulez pas dans Azure Cosmos DB SessionToken comme décrit ci-dessus, vous risquez de rencontrer des résultats de lecture incohérents pendant un certain temps.

Les jetons de session dans Azure Cosmos DB sont liés à la partition, ce qui signifie qu’ils sont exclusivement associés à une partition. Pour veiller à ce que vous puissiez lire vos écritures, utilisez le jeton de session qui a été généré pour la dernière fois pour le ou les éléments appropriés. Pour gérer les jetons de session manuellement, obtenez le jeton de session à partir de la réponse, puis définissez-les par requête. Si vous n’avez pas besoin de gérer des jetons de session manuellement, les exemples ci-dessous ne vous sont pas utiles. Le kit SDK effectue le suivi des jetons de session automatiquement. Si vous ne définissez pas le jeton de session manuellement, par défaut, le kit SDK utilise le jeton de session le plus récent.

Kit de développement logiciel (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 Java V4

API asynchrone du kit SDK 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();

Kits de développement logiciel (SDK) Java v2

Kit de développement logiciel (SDK) Async Java 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);

Kit SDK 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 });

Kit de développement logiciel (SDK) 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)

Surveiller la métrique de probabilités en fonction de l’obsolescence limitée (PBS)

Quel est le degré d’éventualité de la cohérence éventuelle ? Dans le cas moyen, nous pouvons offrir des limites d’obsolescence par rapport à l’historique des versions et à l’heure. La métrique PBS (Probabilistically Bounded Staleness) essaie de quantifier la probabilité d’obsolescence et l’affiche sous forme de métrique.

Pour afficher la métrique PBS, accédez à votre compte Azure Cosmos DB dans le portail Azure. Ouvrez l’onglet Métriques (classique), puis sélectionnez l’onglet Cohérence. Observez le graphique intitulé Probabilité de lectures fortement cohérentes en fonction de votre charge de travail (voir PBS).

Graphe PBS dans le portail Azure

Étapes suivantes

Découvrez plus en détail la gestion des conflits de données ou passez au concept clé suivant dans Azure Cosmos DB. Voir les articles suivants :