Comment configurer le cache intégré Azure Cosmos DB

S’APPLIQUE À : NoSQL

Cet article explique comment approvisionner une passerelle dédiée, configurer le cache intégré et connecter votre application.

Prérequis

• Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.
• Une application existante utilisant Azure Cosmos DB. Si vous n’en avez pas, voici quelques exemples.
• Un compte d’API Azure Cosmos DB for NoSQL existant.

Provisionner la passerelle dédiée

1. Accédez à un compte Azure Cosmos DB dans le portail Azure et sélectionnez l’onglet Passerelle dédiée.

   

2. Remplissez le formulaire Passerelle dédiée avec les informations suivantes :

   • Passerelle dédiée : activez le bouton bascule sur Approvisionné.
   • Référence (SKU) : sélectionnez une référence (SKU) offrant les tailles de calcul et de mémoire requises. Le cache intégré utilise environ 50 % de la mémoire, et la mémoire restante est utilisée pour les métadonnées et le routage des demandes vers les partitions back-end.
   • Nombre d’instances : nombre de nœuds. À des fins de développement, nous vous recommandons de commencer avec un nœud de la taille D4. En fonction de la quantité de données à mettre en cache et pour atteindre une haute disponibilité, vous pouvez augmenter la taille du nœud après le test initial.

   

3. Sélectionnez Enregistrer, puis attendez environ de 5 à 10 minutes que l’approvisionnement de la passerelle dédiée se termine. Une fois l’approvisionnement terminé, la notification suivante s’affiche :

   

Configurez votre application pour utiliser le cache intégré

Lorsque vous provisionnez une passerelle dédiée, un cache intégré est automatiquement créé. Vous n’avez pas besoin de connecter toutes les applications utilisant Azure Cosmos DB à la passerelle dédiée si elles n’ont pas besoin d’utiliser le cache intégré. L’ajout d’une passerelle dédiée n’a aucun impact sur les méthodes existantes de connexion à Azure Cosmos DB. Par exemple, vous pouvez avoir une connexion CosmosClient utilisant le mode passerelle et le point de terminaison de passerelle dédiée tandis qu’un autre CosmosClient utilise le mode direct.

Authentifiez-vous avec un contrôle d'accès basé sur les rôles

La passerelle dédiée utilise les mêmes autorisations, définitions de rôles et attributions de rôles qu’Azure Cosmos DB. Si vous avez déjà configuré le contrôle d’accès basé sur les rôles (RBAC) pour les opérations de plan de données dans votre compte Azure Cosmos DB, vous pouvez également l’utiliser pour vous authentifier auprès de la passerelle dédiée. Découvrez RBAC pour les opérations de plan de données Azure Cosmos DB.

Configurez votre CosmosClient en définissant le point de terminaison de passerelle dédié, les informations d'identification et en configurant le mode de connectivité de la passerelle. Tous les points de terminaison de passerelle dédiés suivent le même modèle. Supprimez documents.azure.com de votre point de terminaison d'origine et remplacez-le par sqlx.cosmos.azure.com. Une passerelle dédiée aura toujours le même point de terminaison, même si vous la supprimez et la réapprovisionnez.

.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 });

Important

Le mode de connectivité directe est la valeur par défaut dans le SDK .NET. Vous devez configurer explicitement le mode passerelle pour utiliser la passerelle dédiée.

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();
    }
}

Important

Le mode de connectivité directe est la valeur par défaut dans le SDK Java. Vous devez configurer explicitement le mode passerelle pour utiliser la passerelle dédiée.

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)

Authentifiez avec des chaînes de connexion

1. Modifiez la chaîne de connexion de votre application pour utiliser le nouveau point de terminaison de passerelle dédiée.

   La chaîne de connexion à la passerelle dédiée mise à jour figure dans le panneau Clés :

   

   Toutes les chaînes de connexion à la passerelle dédiée suivent le même modèle. Supprimez documents.azure.com de la chaîne de connexion d’origine et entrez sqlx.cosmos.azure.com à la place. Une passerelle dédiée aura toujours la même chaîne de connexion, même si vous la supprimez et la réapprovisionnez.

2. Si vous utilisez le Kit de développement logiciel (SDK) .NET ou Java, définissez le mode de connexion sur mode passerelle. Cette étape n’est pas nécessaire pour les kits de développement logiciel (SDK) Python et Node.js, car ils n’ont pas d’options de connexion autres que le mode passerelle.

Important

Si vous utilisez la dernière version du kit de développement logiciel (SDK) .NET ou Java, le mode de connexion par défaut est le mode direct. Pour pouvoir utiliser le cache intégré, vous devez remplacer cette valeur par défaut.

Ajuster la cohérence des demandes

Vous devez vous assurer que la cohérence des demandes est une cohérence de session ou à terme. Si ce n’est pas le cas, la demande contourne toujours le cache intégré. Le moyen le plus simple de configurer une cohérence spécifique pour toutes les opérations de lecture est de la définir au niveau du compte. Vous pouvez également configurer la cohérence au niveau de la demande, ce qui est recommandé si vous souhaitez uniquement qu’un sous-ensemble de vos lectures utilise le cache intégré.

Ajuster MaxIntegratedCacheStaleness

Configurez MaxIntegratedCacheStaleness, qui correspond à la durée maximale pendant laquelle vous voulez tolérer des données mises en cache obsolètes. Nous vous recommandons de définir une valeur la plus élevée possible pour MaxIntegratedCacheStaleness, car elle augmente la probabilité que les lectures de points et les requêtes répétées puissent avoir des correspondances dans le cache. Si vous affectez à MaxIntegratedCacheStaleness la valeur 0, votre requête de lecture n’utilisera jamais le cache intégré, quel que soit le niveau de cohérence. En l’absence de configuration, la valeur par défaut de MaxIntegratedCacheStaleness est 5 minutes.

Notes

La valeur MaxIntegratedCacheStaleness peut être définie sur maximum 10 ans. Dans la pratique, cette valeur est l’obsolescence maximale et le cache peut être réinitialisé plus tôt en raison du redémarrages de nœud qui peut se produire.

L’ajustement de MaxIntegratedCacheStaleness est pris en charge dans les versions ci-après de chaque SDK :

Kit SDK	Versions prises en charge
Kit de développement logiciel (SDK) .NET v3	>= 3.30.0
Kit SDK Java v4	>= 4.34.0
Kit de développement logiciel (SDK) Node.js	>=3.17.0
Kit de développement logiciel (SDK) Python	>=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
)

Contourner le cache intégré

Utilisez l’option de requête BypassIntegratedCache pour contrôler quelles requêtes utilisent le cache intégré. Les écritures, les lectures de points et les requêtes qui contournent le cache intégré n’utilisent pas le stockage du cache, ce qui permet d’économiser de l’espace pour d’autres éléments. Les requêtes qui ignorent le cache sont néanmoins toujours routées via la passerelle dédiée. Ces requêtes sont traitées depuis le back-end et engendrent des coûts en RU.

Le contournement du cache est pris en charge dans ces versions de chaque SDK :

Kit SDK	Versions prises en charge
Kit de développement logiciel (SDK) .NET v3	>= 3.39.0
Kit SDK Java v4	>= 4.49.0
Kit de développement logiciel (SDK) Node.js	>= 4.1.0
Kit de développement logiciel (SDK) Python	Non pris en charge

.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

L’option de contournement du cache intégré par les requêtes n’est pas disponible dans le SDK Python.

Vérifier les correspondances dans le cache

Enfin, vous pouvez redémarrer votre application et vérifier les correspondances dans le cache intégré pour des lectures ou requêtes de point répétées en regardant si le coût de la demande est égal à 0. Une fois votre CosmosClient modifié pour utiliser le point de terminaison de passerelle dédiée, toutes les demandes sont routées via la passerelle dédiée.

Pour qu’une demande de lecture (lecture ou interrogation de point) utilise le cache intégré, tous les critères suivants doivent être vrais :

• Votre client se connecte au point de terminaison de passerelle dédiée
• Votre client utilise le mode passerelle (Les kits de développement logiciel (SDK) Python et Node.js utilisent toujours le mode passerelle)
• La cohérence de la demande doit être définie sur la session ou à terme.

Notes

Avez-vous des commentaires sur le cache intégré ? Nous attendons vos remarques ! N’hésitez pas à partager vos commentaires directement avec l’équipe d’ingénierie Azure Cosmos DB :cosmoscachefeedback@microsoft.com

Étapes suivantes

• FAQ sur le cache intégré
• Vue d’ensemble du cache intégré
• Passerelle dédiée