Konfigurace integrované mezipaměti Azure Cosmos DB

PLATÍ PRO: NoSQL

Tento článek popisuje, jak zřídit vyhrazenou bránu, nakonfigurovat integrovanou mezipaměť a připojit aplikaci.

Požadavky

• Pokud ještě nemáte předplatné Azure, vytvořte si bezplatný účet před tím, než začnete.
• Existující aplikace, která používá službu Azure Cosmos DB. Pokud ho nemáte, tady je několik příkladů.
• Existující účet rozhraní API služby Azure Cosmos DB pro NoSQL

Zřízení vyhrazené brány

1. Na webu Azure Portal přejděte k účtu služby Azure Cosmos DB a vyberte kartu Vyhrazená brána .

   

2. Vyplňte formulář vyhrazené brány s následujícími podrobnostmi:

   • Vyhrazená brána – Zapněte přepínač na Zřízeno.
   • Skladová položka – Vyberte skladovou položku s požadovanou velikostí výpočetních prostředků a paměti. Integrovaná mezipaměť bude používat přibližně 50 % paměti a zbývající paměť se používá pro metadata a požadavky směrování do back-endových oddílů.
   • Počet instancí – počet uzlů Pro účely vývoje doporučujeme začít s jedním uzlem velikosti D4. Na základě množství dat, která potřebujete uložit do mezipaměti a dosáhnout vysoké dostupnosti, můžete po počátečním testování zvětšit velikost uzlu.

   

3. Vyberte Uložit a počkejte asi 5 až 10 minut, než se dokončí zřizování vyhrazené brány. Po dokončení zřizování se zobrazí následující oznámení:

   

Nakonfigurujte aplikaci tak, aby používala integrovanou mezipaměť.

Když zřídíte vyhrazenou bránu, automaticky se vytvoří integrovaná mezipaměť. Pokud nepotřebují používat integrovanou mezipaměť, nemusíte připojovat všechny aplikace pomocí služby Azure Cosmos DB k vyhrazené bráně. Přidání vyhrazené brány nemá vliv na stávající způsoby připojení ke službě Azure Cosmos DB. Můžete mít například jedno CosmosClient připojení pomocí režimu brány a vyhrazeného koncového bodu brány, zatímco jiný CosmosClient používá přímý režim.

Ověřování pomocí řízení přístupu na základě role

Vyhrazená brána používá stejná oprávnění, definice rolí a přiřazení rolí jako Azure Cosmos DB. Pokud už máte v účtu Služby Azure Cosmos DB nakonfigurované řízení přístupu na základě role (RBAC) pro operace roviny dat, můžete ho také použít k ověřování ve vyhrazené bráně. Seznamte se s RBAC pro operace roviny dat Azure Cosmos DB.

Nakonfigurujte ho CosmosClient nastavením vyhrazeného koncového bodu brány, přihlašovacích údajů a konfigurace režimu připojení brány. Všechny vyhrazené koncové body brány se řídí stejným vzorem. Odeberte documents.azure.com z původního koncového bodu a nahraďte ho .sqlx.cosmos.azure.com Vyhrazená brána bude mít vždy stejný koncový bod, i když ji odeberete a znovu vytvoříte.

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

Důležité

Režim přímého připojení je výchozí v sadě .NET SDK. Musíte explicitně nakonfigurovat režim brány tak, aby používal vyhrazenou bránu.

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

Důležité

Režim přímého připojení je výchozí v sadě Java SDK. Musíte explicitně nakonfigurovat režim brány tak, aby používal vyhrazenou bránu.

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)

Ověřování pomocí připojovací řetězec

1. Upravte připojovací řetězec aplikace tak, aby používala nový koncový bod vyhrazené brány.

   Aktualizovaná vyhrazená brána připojovací řetězec je v okně Klíče:

   

   Všechny vyhrazené brány připojovací řetězec se řídí stejným vzorem. Odeberte documents.azure.com z původního připojovací řetězec a nahraďte ho .sqlx.cosmos.azure.com Vyhrazená brána bude mít vždy stejné připojovací řetězec, i když ji odeberete a znovu vytvoříte.

2. Pokud používáte sadu .NET nebo Java SDK, nastavte režim připojení na režim brány. Tento krok není nezbytný pro Sady SDK Pythonu a Node.js, protože nemají další možnosti připojení kromě režimu brány.

Důležité

Pokud používáte nejnovější verzi sady .NET nebo Java SDK, je výchozí režim připojení přímý. Chcete-li použít integrovanou mezipaměť, musíte toto výchozí nastavení přepsat.

Úprava konzistence požadavků

Musíte zajistit, aby konzistence požadavků byla relace nebo případná. Pokud ne, požadavek vždy vynechá integrovanou mezipaměť. Nejjednodušší způsob, jak nakonfigurovat konkrétní konzistenci pro všechny operace čtení, je nastavit ji na úrovni účtu. Konzistenci můžete nakonfigurovat také na úrovni požadavku, což se doporučuje, pokud chcete, aby integrovaná mezipaměť využívala jenom podmnožinu čtení.

Upravit MaxIntegratedCacheStaleness

Nakonfigurujte MaxIntegratedCacheStaleness, což je maximální doba, ve které jste ochotni tolerovat zastaralá data uložená v mezipaměti. Doporučuje se nastavit MaxIntegratedCacheStaleness co nejvyšší hodnotu, protože zvýší pravděpodobnost, že opakované čtení bodů a dotazy mohou být do mezipaměti. Pokud nastavíte MaxIntegratedCacheStaleness hodnotu 0, váš požadavek na čtení nikdy nebude používat integrovanou mezipaměť bez ohledu na úroveň konzistence. Pokud není nakonfigurováno, výchozí MaxIntegratedCacheStaleness hodnota je 5 minut.

Poznámka:

Lze MaxIntegratedCacheStaleness nastavit až 10 let. V praxi je tato hodnota maximální zastaralost a mezipaměť může být resetována dříve kvůli restartování uzlů, ke kterým může dojít.

Úprava je podporována MaxIntegratedCacheStaleness v těchto verzích každé sady SDK:

Sada SDK	Podporované verze
.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
)

Obejití integrované mezipaměti

BypassIntegratedCache Pomocí možnosti žádosti můžete určit, které požadavky používají integrovanou mezipaměť. Zápisy, čtení bodů a dotazy, které vynechají integrovanou mezipaměť, nebudou používat úložiště mezipaměti, což šetří místo pro jiné položky. Žádosti o obejití mezipaměti se stále směrují přes vyhrazenou bránu. Tyto žádosti se obsluhují z back-endu a nákladových RU.

Obejití mezipaměti je podporováno v těchto verzích každé sady SDK:

Sada SDK	Podporované verze
.NET SDK v3	>= 3,39,0
Java SDK v4	>= 4,49,0
Node.js SDK	>= 4,1,0
Python SDK	Nepodporováno

.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

Možnost vynechat integrovanou žádost o mezipaměť není v sadě Python SDK dostupná.

Ověření přístupů do mezipaměti

Nakonec můžete restartovat aplikaci a ověřit přístupy integrované mezipaměti pro opakované čtení bodů nebo dotazy tím, že zjistíte, jestli je poplatek za žádost 0. Jakmile upravíte CosmosClient použití vyhrazeného koncového bodu brány, všechny požadavky se budou směrovat přes vyhrazenou bránu.

Aby požadavek pro čtení (bod čtení nebo dotaz) využíval integrovanou mezipaměť, musí být splněna všechna následující kritéria:

• Váš klient se připojí ke koncovému bodu vyhrazené brány.
• Váš klient používá režim brány (Python a sady SDK Node.js vždy používají režim brány).
• Konzistence požadavku musí být nastavená na relaci nebo na případnou.

Poznámka:

Máte nějaké připomínky k integrované mezipaměti? Chceme to slyšet! Svůj názor můžete sdílet přímo s technickým týmem služby Azure Cosmos DB: cosmoscachefeedback@microsoft.com

Další kroky

• Nejčastější dotazy k integrované mezipaměti
• Přehled integrované mezipaměti
• Vyhrazená brána