Jak skonfigurować zintegrowaną pamięć podręczną usługi Azure Cosmos DB

DOTYCZY: NoSQL

W tym artykule opisano sposób aprowizowania dedykowanej bramy, konfigurowania zintegrowanej pamięci podręcznej i łączenia aplikacji.

Wymagania wstępne

• Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto.
• Istniejąca aplikacja korzystająca z usługi Azure Cosmos DB. Jeśli go nie masz, oto kilka przykładów.
• Istniejący interfejs API usługi Azure Cosmos DB dla konta NoSQL.

Aprowizuj dedykowaną bramę

1. Przejdź do konta usługi Azure Cosmos DB w witrynie Azure Portal i wybierz kartę Dedykowana brama .

   

2. Wypełnij formularz Dedykowana brama , korzystając z następujących szczegółów:

   • Dedykowana brama — włącz przełącznik aprowizacji.
   • Jednostka SKU — wybierz jednostkę SKU z wymaganym rozmiarem zasobów obliczeniowych i pamięci. Zintegrowana pamięć podręczna będzie używać około 50% pamięci, a pozostała pamięć jest używana na potrzeby metadanych i routingu żądań do partycji zaplecza.
   • Liczba wystąpień — liczba węzłów. W celu programowania zalecamy rozpoczęcie od jednego węzła o rozmiarze D4. Na podstawie ilości danych potrzebnych do buforowania i uzyskania wysokiej dostępności można zwiększyć rozmiar węzła po początkowym przetestowaniu.

   

3. Wybierz pozycję Zapisz i poczekaj około 5–10 minut na ukończenie aprowizacji dedykowanej bramy. Po zakończeniu aprowizacji zobaczysz następujące powiadomienie:

   

Konfigurowanie aplikacji do korzystania ze zintegrowanej pamięci podręcznej

Podczas aprowizowania dedykowanej bramy zostanie automatycznie utworzona zintegrowana pamięć podręczna. Nie musisz łączyć wszystkich aplikacji przy użyciu usługi Azure Cosmos DB z dedykowaną bramą, jeśli nie muszą używać zintegrowanej pamięci podręcznej. Dodanie dedykowanej bramy nie ma wpływu na istniejące sposoby nawiązywania połączenia z usługą Azure Cosmos DB. Na przykład można mieć jedno CosmosClient połączenie przy użyciu trybu bramy i dedykowanego punktu końcowego bramy, podczas gdy inny CosmosClient używa trybu bezpośredniego.

Uwierzytelnianie za pomocą kontroli dostępu opartej na rolach

Dedykowana brama używa tych samych uprawnień, definicji ról i przypisań ról co usługa Azure Cosmos DB. Jeśli masz już kontrolę dostępu opartą na rolach (RBAC) skonfigurowaną na potrzeby operacji płaszczyzny danych na koncie usługi Azure Cosmos DB, możesz również użyć jej do uwierzytelniania w dedykowanej bramie. Dowiedz się więcej o kontroli dostępu opartej na rolach dla operacji płaszczyzny danych usługi Azure Cosmos DB.

Skonfiguruj usługę CosmosClient , ustawiając dedykowany punkt końcowy bramy, poświadczenia i konfigurując tryb łączności bramy. Wszystkie dedykowane punkty końcowe bramy są zgodne z tym samym wzorcem. Usuń documents.azure.com element z oryginalnego punktu końcowego i zastąp go ciągiem sqlx.cosmos.azure.com. Dedykowana brama zawsze będzie mieć ten sam punkt końcowy, nawet jeśli usuniesz go i ponownie aprowizujesz.

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

Ważne

Tryb łączności bezpośredniej jest domyślny w zestawie SDK platformy .NET. Aby korzystać z dedykowanej bramy, należy jawnie skonfigurować tryb bramy.

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

Ważne

Tryb bezpośredniej łączności jest domyślnym trybem zestawu JAVA SDK. Aby korzystać z dedykowanej bramy, należy jawnie skonfigurować tryb bramy.

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)

Uwierzytelnianie przy użyciu parametry połączenia

1. Zmodyfikuj parametry połączenia aplikacji, aby użyć nowego dedykowanego punktu końcowego bramy.

   Zaktualizowana dedykowana brama parametry połączenia znajduje się w bloku Klucze:

   

   Wszystkie dedykowane parametry połączenia bramy są zgodne z tym samym wzorcem. Usuń documents.azure.com element z oryginalnego parametry połączenia i zastąp go ciągiem sqlx.cosmos.azure.com. Dedykowana brama zawsze będzie miała takie same parametry połączenia, nawet jeśli usuniesz ją i ponownie aprowizujesz.

2. Jeśli używasz zestawu SDK platformy .NET lub Java, ustaw tryb połączenia na tryb bramy. Ten krok nie jest niezbędny dla języka Python i zestawów SDK Node.js, ponieważ nie ma dodatkowych opcji łączenia się poza trybem bramy.

Ważne

Jeśli używasz najnowszej wersji zestawu .NET lub Java SDK, domyślny tryb połączenia to tryb bezpośredni. Aby można było używać zintegrowanej pamięci podręcznej, należy zastąpić tę wartość domyślną.

Dostosowywanie spójności żądań

Upewnij się, że spójność żądania jest sesja lub ostateczna. Jeśli nie, żądanie zawsze pomija zintegrowaną pamięć podręczną. Najprostszym sposobem skonfigurowania konkretnej spójności dla wszystkich operacji odczytu jest ustawienie go na poziomie konta. Można również skonfigurować spójność na poziomie żądania, co jest zalecane, jeśli chcesz, aby tylko podzbiór odczytów mógł korzystać ze zintegrowanej pamięci podręcznej.

Dostosowywanie maksymalnej liczbyintegratedCacheStaleness

Skonfiguruj MaxIntegratedCacheStalenessparametr , czyli maksymalny czas, w którym chcesz tolerować nieaktualne dane z pamięci podręcznej. Zaleca się ustawienie możliwie największej MaxIntegratedCacheStaleness wartości, ponieważ zwiększy prawdopodobieństwo trafienia w pamięci podręcznej wielokrotnych odczytów punktów i zapytań. Jeśli ustawisz wartość MaxIntegratedCacheStaleness 0, żądanie odczytu nigdy nie będzie używać zintegrowanej pamięci podręcznej, niezależnie od poziomu spójności. Jeśli nie skonfigurowano, wartość domyślna MaxIntegratedCacheStaleness to 5 minut.

Uwaga

Wartość MaxIntegratedCacheStaleness można ustawić na poziomie 10 lat. W praktyce ta wartość jest maksymalną nieaktualnością, a pamięć podręczna może zostać zresetowana wcześniej z powodu ponownego uruchomienia węzła, które mogą wystąpić.

Dostosowanie elementu MaxIntegratedCacheStaleness jest obsługiwane w tych wersjach każdego zestawu SDK:

SDK	Obsługiwane wersje
Zestaw .NET SDK w wersji 3	>= 3.30.0
Zestaw Java SDK w wersji 4	>= 4.34.0
Zestaw SDK dla platformy Node.js	>=3.17.0
Zestaw SDK dla języka 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
)

Obejście zintegrowanej pamięci podręcznej

BypassIntegratedCache Użyj opcji żądania, aby kontrolować, które żądania używają zintegrowanej pamięci podręcznej. Zapisy, odczyty punktów i zapytania, które pomijają zintegrowaną pamięć podręczną, nie będą używać magazynu pamięci podręcznej, co pozwala zaoszczędzić miejsce dla innych elementów. Żądania pomijające pamięć podręczną są nadal kierowane przez dedykowaną bramę. Te żądania są obsługiwane z zaplecza i jednostek RU kosztów.

Pomijanie pamięci podręcznej jest obsługiwane w tych wersjach każdego zestawu SDK:

SDK	Obsługiwane wersje
Zestaw .NET SDK w wersji 3	>= 3.39.0
Zestaw Java SDK w wersji 4	>= 4.49.0
Zestaw SDK dla platformy Node.js	>= 4.1.0
Zestaw SDK dla języka Python	Nieobsługiwane

.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

Opcja pomijania zintegrowanej pamięci podręcznej nie jest dostępna w zestawie SDK języka Python.

Sprawdzanie trafień pamięci podręcznej

Na koniec możesz ponownie uruchomić aplikację i zweryfikować trafienia zintegrowanej pamięci podręcznej dla powtarzających się odczytów lub zapytań punktów, sprawdzając, czy opłata za żądanie wynosi 0. Po zmodyfikowaniu CosmosClient elementu w celu korzystania z dedykowanego punktu końcowego bramy wszystkie żądania będą kierowane przez dedykowaną bramę.

Aby żądanie odczytu (punkt odczytu lub kwerendy) korzystało ze zintegrowanej pamięci podręcznej, wszystkie następujące kryteria muszą być spełnione:

• Klient nawiązuje połączenie z dedykowanym punktem końcowym bramy
• Klient używa trybu bramy (zestawy SDK języka Python i Node.js zawsze używają trybu bramy)
• Spójność żądania musi być ustawiona na sesję lub ostateczną

Uwaga

Czy masz jakieś opinie na temat zintegrowanej pamięci podręcznej? Chcemy to usłyszeć! Możesz podzielić się opiniami bezpośrednio z zespołem inżynierów usługi Azure Cosmos DB: cosmoscachefeedback@microsoft.com

Następne kroki

• Zintegrowana pamięć podręczna — często zadawane pytania
• Omówienie zintegrowanej pamięci podręcznej
• Dedykowana brama