Så här konfigurerar du azure Cosmos DB-integrerad cache

GÄLLER FÖR: NoSQL

Den här artikeln beskriver hur du etablerar en dedikerad gateway, konfigurerar den integrerade cachen och ansluter ditt program.

Förutsättningar

• Om du inte har en Azure-prenumeration kan du skapa ettkostnadsfritt konto innan du börjar.
• Ett befintligt program som använder Azure Cosmos DB. Om du inte har någon, här är några exempel.
• Ett befintligt Azure Cosmos DB-API för NoSQL-konto.

Etablera den dedikerade gatewayen

1. Gå till ett Azure Cosmos DB-konto i Azure Portal och välj fliken Dedikerad gateway.

   

2. Fyll i formuläret Dedikerad gateway med följande information:

   • Dedikerad gateway – Aktivera växlingsknappen till Etablerad.
   • SKU – Välj en SKU med den beräknings- och minnesstorlek som krävs. Den integrerade cachen använder cirka 50 % av minnet och det återstående minnet används för metadata och routningsbegäranden till serverdelspartitionerna.
   • Antal instanser – Antal noder. I utvecklingssyfte rekommenderar vi att du börjar med en nod av D4-storleken. Baserat på mängden data som du behöver cachelagrat och för att uppnå hög tillgänglighet kan du öka nodstorleken efter den inledande testningen.

   

3. Välj Spara och vänta ungefär 5–10 minuter innan etableringen av den dedikerade gatewayen slutförs. När etableringen är klar visas följande meddelande:

   

Konfigurera ditt program så att det använder den integrerade cachen

När du etablerar en dedikerad gateway skapas automatiskt en integrerad cache. Du behöver inte ansluta alla program med Azure Cosmos DB till den dedikerade gatewayen om de inte behöver använda den integrerade cachen. Att lägga till en dedikerad gateway påverkar inte de befintliga sätten att ansluta till Azure Cosmos DB. Du kan till exempel ha en CosmosClient anslutning med gatewayläge och den dedikerade gatewayslutpunkten medan en annan CosmosClient använder direktläge.

Autentisera med rollbaserad åtkomstkontroll

Den dedikerade gatewayen använder samma behörigheter, rolldefinitioner och rolltilldelningar som Azure Cosmos DB. Om du redan har rollbaserad åtkomstkontroll (RBAC) konfigurerad för dataplansåtgärder i ditt Azure Cosmos DB-konto kan du även använda den för autentisering till den dedikerade gatewayen. Läs mer om RBAC för dataplansåtgärder i Azure Cosmos DB.

Konfigurera din CosmosClient genom att ange den dedikerade gatewayens slutpunkt, autentiseringsuppgifter och konfigurera gatewayanslutningsläge. Alla dedikerade gatewayslutpunkter följer samma mönster. Ta bort documents.azure.com från den ursprungliga slutpunkten och ersätt den med sqlx.cosmos.azure.com. En dedikerad gateway har alltid samma slutpunkt, även om du tar bort och etablerar om den.

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

Viktigt!

Direktanslutningsläge är standard i .NET SDK. Du måste uttryckligen konfigurera gatewayläge för att använda den dedikerade gatewayen.

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

Viktigt!

Direktanslutningsläge är standard i Java SDK. Du måste uttryckligen konfigurera gatewayläge för att använda den dedikerade gatewayen.

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)

Autentisera med anslutningssträng

1. Ändra programmets anslutningssträng för att använda den nya dedikerade gatewayslutpunkten.

   Den uppdaterade dedikerade gatewayen anslutningssträng finns på bladet Nycklar:

   

   Alla dedikerade gateway-anslutningssträng följer samma mönster. Ta bort documents.azure.com från den ursprungliga anslutningssträng och ersätt den med sqlx.cosmos.azure.com. En dedikerad gateway har alltid samma anslutningssträng, även om du tar bort och etablerar om den.

2. Om du använder .NET eller Java SDK anger du anslutningsläget till gatewayläge. Det här steget är inte nödvändigt för Python och Node.js SDK:er eftersom de inte har ytterligare alternativ för att ansluta förutom gatewayläge.

Viktigt!

Om du använder den senaste .NET- eller Java SDK-versionen är standardanslutningsläget direktläge. För att kunna använda den integrerade cachen måste du åsidosätta den här standardinställningen.

Justera konsekvens för begäran

Du måste se till att begärandekonsekvensen är session eller eventuell. Annars kringgår begäran alltid den integrerade cachen. Det enklaste sättet att konfigurera en specifik konsekvens för alla läsåtgärder är att ange den på kontonivå. Du kan också konfigurera konsekvens på begärandenivå, vilket rekommenderas om du bara vill att en delmängd av läsningarna ska använda den integrerade cachen.

Justera MaxIntegratedCacheStaleness

Konfigurera MaxIntegratedCacheStaleness, vilket är den maximala tid då du är villig att tolerera inaktuella cachelagrade data. Vi rekommenderar att du anger MaxIntegratedCacheStaleness så högt som möjligt eftersom det ökar sannolikheten för att upprepade punktläsningar och frågor kan vara cacheträffar. Om du anger MaxIntegratedCacheStaleness till 0 kommer din läsbegäran aldrig att använda den integrerade cachen, oavsett konsekvensnivå. När den inte har konfigurerats är standardvärdet MaxIntegratedCacheStaleness 5 minuter.

Kommentar

MaxIntegratedCacheStaleness Kan anges så högt som 10 år. I praktiken är det här värdet maximal föråldring och cachen kan återställas tidigare på grund av omstarter av noden som kan inträffa.

Justering av MaxIntegratedCacheStaleness stöds i dessa versioner av varje SDK:

SDK	Versioner som stöds
.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
)

Kringgå den integrerade cachen

Använd begärandealternativet BypassIntegratedCache för att styra vilka begäranden som använder den integrerade cachen. Skrivningar, punktläsningar och frågor som kringgår den integrerade cachen använder inte cachelagring, vilket sparar utrymme för andra objekt. Begäranden som kringgår cachen dirigeras fortfarande via den dedikerade gatewayen. Dessa begäranden hanteras från serverdelen och kostnads-RU:er.

Det går att kringgå cachen i dessa versioner av varje SDK:

SDK	Versioner som stöds
.NET SDK v3	>= 3,39,0
Java SDK v4	>= 4.49.0
Node.js SDK	>= 4.1.0
Python SDK	Stöds inte

.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

Alternativet för att kringgå integrerad cachebegäran är inte tillgängligt i Python SDK.

Verifiera cacheträffar

Slutligen kan du starta om programmet och verifiera integrerade cacheträffar för upprepade punktläsningar eller frågor genom att se om begärandeavgiften är 0. När du har ändrat din CosmosClient för att använda den dedikerade gatewayslutpunkten dirigeras alla begäranden via den dedikerade gatewayen.

För en läsbegäran (punktläsning eller fråga) för att använda den integrerade cachen måste alla följande villkor vara sanna:

• Klienten ansluter till den dedikerade gatewayslutpunkten
• Klienten använder gatewayläge (Python och Node.js SDK:er använder alltid gatewayläge)
• Konsekvensen för begäran måste anges till session eller slutlig

Kommentar

Har du någon feedback om den integrerade cachen? Vi vill höra det! Dela gärna feedback direkt med Azure Cosmos DB-teknikteamet: cosmoscachefeedback@microsoft.com

Nästa steg

• Vanliga frågor och svar om integrerad cache
• Översikt av integrerad cache
• Dedikerad gateway