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 :

   

Configuration du cache intégré

Lorsque vous créez une passerelle dédiée, un cache intégré est automatiquement approvisionné.

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.

   Vous n’avez pas besoin de modifier la chaîne de connexion dans toutes les applications utilisant le même compte 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. En d’autres termes, l’ajout d’une passerelle dédiée n’a pas d’impact sur les méthodes existantes de connexion à Azure Cosmos DB.

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.

Notes

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é.

Notes

Si vous utilisez le Kit de développement logiciel (SDK) Python, vous devez définir explicitement le niveau de cohérence pour chaque demande. Le paramètre par défaut au niveau du compte ne s’applique pas automatiquement.

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é (préversion)

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.35.0-preview
Kit SDK Java v4	>= 4.49.0
Kit de développement logiciel (SDK) Node.js	Non pris en charge
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

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

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