De geïntegreerde Cache van Azure Cosmos DB configureren

VAN TOEPASSING OP: NoSQL

In dit artikel wordt beschreven hoe u een toegewezen gateway inricht, de geïntegreerde cache configureert en verbinding maakt met uw toepassing.

Vereisten

• Als u geen Azure-abonnement hebt, maakt u een gratis account voordat u begint.
• Een bestaande toepassing die gebruikmaakt van Azure Cosmos DB. Als u er nog geen hebt, vindt u hier enkele voorbeelden.
• Een bestaand Azure Cosmos DB-API voor NoSQL-account.

De toegewezen gateway inrichten

1. Navigeer naar een Azure Cosmos DB-account in Azure Portal en selecteer het tabblad Toegewezen gateway .

   

2. Vul het formulier Toegewezen gateway in met de volgende details:

   • Toegewezen gateway : schakel de wisselknop in op Ingericht.
   • SKU: selecteer een SKU met de vereiste reken- en geheugengrootte. De geïntegreerde cache gebruikt ongeveer 50% van het geheugen en het resterende geheugen wordt gebruikt voor metagegevens en routeringsaanvragen naar de back-endpartities.
   • Aantal exemplaren - aantal knooppunten. Voor ontwikkelingsdoeleinden wordt u aangeraden te beginnen met één knooppunt van de D4-grootte. Op basis van de hoeveelheid gegevens die u in de cache moet opslaan en hoge beschikbaarheid wilt bereiken, kunt u de knooppuntgrootte vergroten na de eerste test.

   

3. Selecteer Opslaan en wacht ongeveer 5-10 minuten totdat het inrichten van de toegewezen gateway is voltooid. Wanneer het inrichten is voltooid, ziet u de volgende melding:

   

Uw toepassing configureren voor het gebruik van de geïntegreerde cache

Wanneer u een toegewezen gateway inricht, wordt automatisch een geïntegreerde cache gemaakt. U hoeft niet alle toepassingen te verbinden met Behulp van Azure Cosmos DB met de toegewezen gateway als ze de geïntegreerde cache niet hoeven te gebruiken. Het toevoegen van een toegewezen gateway heeft geen invloed op de bestaande manieren om verbinding te maken met Azure Cosmos DB. U kunt bijvoorbeeld een CosmosClient verbinding maken via de gatewaymodus en het toegewezen gateway-eindpunt terwijl een andere CosmosClient gebruikmaakt van de directe modus.

Verifiëren met op rollen gebaseerd toegangsbeheer

De toegewezen gateway gebruikt dezelfde machtigingen, roldefinities en roltoewijzingen als Azure Cosmos DB. Als u al op rollen gebaseerd toegangsbeheer (RBAC) hebt geconfigureerd voor gegevensvlakbewerkingen in uw Azure Cosmos DB-account, kunt u dit ook gebruiken voor verificatie bij de toegewezen gateway. Meer informatie over RBAC voor bewerkingen van azure Cosmos DB-gegevensvlakken .

Configureer uw CosmosClient door het toegewezen gateway-eindpunt, de referenties en de gatewayconnectiviteitsmodus in te stellen. Alle toegewezen gateway-eindpunten volgen hetzelfde patroon. Verwijder documents.azure.com het uit het oorspronkelijke eindpunt en vervang het sqlx.cosmos.azure.comdoor . Een toegewezen gateway heeft altijd hetzelfde eindpunt, zelfs als u deze verwijdert en opnieuw indeelt.

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

Belangrijk

De directe connectiviteitsmodus is de standaardmodus in de .NET SDK. U moet de gatewaymodus expliciet configureren om de toegewezen gateway te kunnen gebruiken.

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

Belangrijk

De directe connectiviteitsmodus is de standaardmodus in de Java SDK. U moet de gatewaymodus expliciet configureren om de toegewezen gateway te kunnen gebruiken.

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)

Verifiëren met verbindingsreeks s

1. Wijzig de verbindingsreeks van uw toepassing om het nieuwe toegewezen gateway-eindpunt te gebruiken.

   De bijgewerkte toegewezen gateway verbindingsreeks bevindt zich op de blade Sleutels:

   

   Alle toegewezen gateways verbindingsreeks volgen hetzelfde patroon. Verwijder documents.azure.com de oorspronkelijke verbindingsreeks en vervang deze door sqlx.cosmos.azure.com. Een toegewezen gateway heeft altijd dezelfde verbindingsreeks, zelfs als u deze verwijdert en opnieuw indeelt.

2. Als u de .NET- of Java SDK gebruikt, stelt u de verbindingsmodus in op de gatewaymodus. Deze stap is niet nodig voor de Python- en Node.js SDK's, omdat ze geen extra opties hebben om verbinding te maken naast de gatewaymodus.

Belangrijk

Als u de nieuwste versie van .NET of Java SDK gebruikt, is de standaardverbindingsmodus directe modus. Als u de geïntegreerde cache wilt gebruiken, moet u deze standaardwaarde overschrijven.

Aanvraagconsistentie aanpassen

U moet ervoor zorgen dat de consistentie van de aanvraag sessie of uiteindelijk is. Zo niet, dan slaat de aanvraag altijd de geïntegreerde cache over. De eenvoudigste manier om een specifieke consistentie voor alle leesbewerkingen te configureren, is door deze op accountniveau in te stellen. U kunt ook consistentie configureren op aanvraagniveau. Dit wordt aanbevolen als u alleen een subset van uw leesbewerkingen wilt gebruiken om de geïntegreerde cache te gebruiken.

MaxIntegratedCacheStaleness aanpassen

Configureren MaxIntegratedCacheStaleness, wat de maximale tijd is waarin u verouderde gegevens in de cache wilt tolereren. Het is raadzaam om het MaxIntegratedCacheStaleness zo hoog mogelijk in te stellen, omdat het de kans vergroot dat herhaalde puntleesbewerkingen en query's cachetreffers kunnen zijn. Als u deze optie instelt op MaxIntegratedCacheStaleness 0, gebruikt uw leesaanvraag nooit de geïntegreerde cache, ongeacht het consistentieniveau. Wanneer deze niet is geconfigureerd, is de standaardwaarde MaxIntegratedCacheStaleness vijf minuten.

Notitie

De MaxIntegratedCacheStaleness kan zo hoog worden ingesteld als 10 jaar. In de praktijk is deze waarde de maximale veroudering en kan de cache eerder opnieuw worden ingesteld als gevolg van opnieuw opstarten van knooppunten die kunnen optreden.

Het aanpassen van de instellingen MaxIntegratedCacheStaleness wordt ondersteund in deze versies van elke SDK:

SDK	Ondersteunde versies
.NET SDK v3	>= 3.30.0
Java SDK v4	>= 4.34.0
Node.js SDK	>=3.17.0
Python SDK	>=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
)

De geïntegreerde cache omzeilen

Gebruik de BypassIntegratedCache aanvraagoptie om te bepalen welke aanvragen gebruikmaken van de geïntegreerde cache. Schrijfbewerkingen, puntleesbewerkingen en query's die de geïntegreerde cache omzeilen, maken geen gebruik van cacheopslag en besparen ruimte voor andere items. Aanvragen die de cache omzeilen, worden nog steeds gerouteerd via de toegewezen gateway. Deze aanvragen worden verwerkt vanuit de back-end en kosten-RU's.

Het omzeilen van de cache wordt ondersteund in deze versies van elke SDK:

SDK	Ondersteunde versies
.NET SDK v3	>= 3,39,0
Java SDK v4	>= 4,49,0
Node.js SDK	>= 4.1.0
Python SDK	Niet ondersteund

.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

De optie voor het overslaan van geïntegreerde cacheaanvragen is niet beschikbaar in de Python SDK.

Cachetreffers controleren

Ten slotte kunt u uw toepassing opnieuw starten en geïntegreerde cachetreffers controleren op herhaalde lees- of query's van punten door te zien of de aanvraagkosten 0 zijn. Zodra u het CosmosClient toegewezen gateway-eindpunt hebt gewijzigd, worden alle aanvragen doorgestuurd via de toegewezen gateway.

Voor een leesaanvraag (punt lezen of query) om de geïntegreerde cache te kunnen gebruiken, moeten alle volgende criteria waar zijn:

• Uw client maakt verbinding met het toegewezen gateway-eindpunt
• Uw client maakt gebruik van de gatewaymodus (Python en Node.js SDK's gebruiken altijd de gatewaymodus)
• De consistentie voor de aanvraag moet worden ingesteld op sessie of uiteindelijk

Notitie

Hebt u feedback over de geïntegreerde cache? We willen het horen! U kunt feedback rechtstreeks delen met het technische team van Azure Cosmos DB: cosmoscachefeedback@microsoft.com

Volgende stappen

• Veelgestelde vragen over geïntegreerde cache
• Overzicht van geïntegreerde cache
• Toegewezen gateway