Настройка интегрированного кэша Azure Cosmos DB

ОБЛАСТЬ ПРИМЕНЕНИЯ: NoSQL

В этой статье объясняется, как подготавливать выделенный шлюз, настраивать интегрированный кэш и подключаться к приложению.

Необходимые компоненты

• Если у вас еще нет подписки Azure, создайте бесплатную учетную запись Azure, прежде чем начать работу.
• Существующее приложение, использующее Azure Cosmos DB. Если у вас его нет, вот несколько примеров.
• Существующая учетная запись API Azure Cosmos DB для NoSQL.

Подготовка выделенного шлюза

1. Перейдите к учетной записи Azure Cosmos DB на портале Azure и выберите вкладку Dedicated Gateway (Выделенный шлюз).

   

2. Укажите в форме Dedicated Gateway (Выделенный шлюз) следующие сведения:

   • Выделенный шлюз — переведите переключатель в состояние Подготовлено.
   • SKU — выберите номер SKU с требуемым объемом вычислений и памяти. Интегрированный кэш использует приблизительно 50 % памяти, остальная часть используется для метаданных и направления запросов к разделам серверной части.
   • Число экземпляров — укажите количество узлов. Для целей разработки рекомендуется начать с одного узла с размером D4. В зависимости от объема данных, которые необходимо кэшировать, для повышения высокого уровня доступности можно увеличить размер узла после начального тестирования.

   

3. Выберите элемент Сохранить и подождите 5–10 минут, пока подготовка выделенного шлюза будет завершена. По завершении подготовки вы увидите следующее уведомление:

   

Настройка приложения для использования встроенного кэша

При подготовке выделенного шлюза автоматически создается интегрированный кэш. Вам не нужно подключать все приложения с помощью Azure Cosmos DB к выделенному шлюзу, если они не должны использовать интегрированный кэш. Добавление выделенного шлюза не влияет на существующие способы подключения к Azure Cosmos DB. Например, один клиент CosmosClient может подключаться в режиме шлюза с выделенной конечной точкой шлюза, а другой клиент CosmosClient может использовать прямой режим.

Проверка подлинности с помощью управления доступом на основе ролей

Выделенный шлюз использует те же разрешения, определения ролей и назначения ролей, что и Azure Cosmos DB. Если у вас уже есть управление доступом на основе ролей (RBAC) для операций плоскости данных в учетной записи Azure Cosmos DB, вы также можете использовать его для проверки подлинности в выделенном шлюзе. Сведения об операциях плоскости данных RBAC для Azure Cosmos DB.

Настройте свою CosmosClient настройку, задав конечную точку выделенного шлюза, учетные данные и настроив режим подключения шлюза. Все конечные точки выделенного шлюза соответствуют одному и тому же шаблону. Удалите documents.azure.com исходную конечную точку и замените ее sqlx.cosmos.azure.comна . Выделенный шлюз всегда будет иметь одну и ту же конечную точку, даже если удалить и повторно подготовить ее.

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

Внимание

Режим прямого подключения используется по умолчанию в пакете SDK для .NET. Необходимо явно настроить режим шлюза для использования выделенного шлюза.

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

Внимание

Режим прямого подключения используется по умолчанию в пакете SDK для Java. Необходимо явно настроить режим шлюза для использования выделенного шлюза.

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)

Проверка подлинности с помощью строка подключения

1. Измените строку подключения приложения таким образом, чтобы использовалась новая выделенная конечная точка шлюза.

   Обновленная строка подключения выделенного шлюза находится в колонке Ключи:

   

   Все строки подключения выделенного шлюза формируются по той же схеме. Удалите documents.azure.com из исходной строки подключения и измените на sqlx.cosmos.azure.com. У выделенного шлюза всегда будет одна и та же строка подключения, даже если вы удалите ее и выполните подготовку заново.

2. Если вы используете пакет SDK для .NET или Java, установите режим подключения в режим шлюза. Этот шаг не требуется для SDK для Python и Node.js, так как у них нет дополнительных параметров подключения, кроме режима шлюза.

Внимание

Если вы используете последнюю версию пакета SDK для .NET или Java, по умолчанию используется режим подключения Direct. Чтобы использовать встроенный кэш, необходимо переопределить это значение по умолчанию.

Настройка согласованности запросов

Убедитесь, что выбрана согласованность сеансов или случайная согласованность. Иначе запрос будет всегда обходить интегрированный кэш. Самый простой способ настроить конкретную согласованность для всех операций чтения — установить ее на уровне учетной записи. Кроме того, вы можете настроить согласованность на уровне запроса. Это рекомендуется, если нужно, чтобы интегрированный кэш использовало только подмножество операций чтения.

Настройка MaxIntegratedCacheStaleness

Настройте MaxIntegratedCacheStaleness, что является максимальным временем, в течение которого вы готовы терпеть устаревшие кэшированные данные. Рекомендуется установить MaxIntegratedCacheStaleness максимально высокий уровень, так как он увеличит вероятность того, что повторяющиеся операции чтения и запросы могут быть попаданиями в кэш. Если для MaxIntegratedCacheStaleness задано значение 0, то запрос на чтение никогда не будет использовать интегрированный кэш, независимо от уровня согласованности. Если параметр MaxIntegratedCacheStaleness не задан, то используется значение по умолчанию — 5 минут.

Примечание.

Его MaxIntegratedCacheStaleness можно задать до 10 лет. На практике это значение является максимальной устаревшим, и кэш может быть сброшен раньше из-за перезапусков узлов, которые могут произойти.

Изменение параметра MaxIntegratedCacheStaleness поддерживается в следующих версиях пакетов SDK:

SDK	Поддерживаемые версии
Пакет SDK версии 3 для .NET	>= 3.30.0
Пакет SDK для Java версии 4	>= 4.34.0
Пакет SDK для Node.js	>=3.17.0
Пакет 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
)

Обход интегрированного кэша

BypassIntegratedCache Используйте параметр запроса для управления тем, какие запросы используют интегрированный кэш. Записи, операции чтения точек и запросы, которые обходят интегрированный кэш, не будут использовать хранилище кэша, экономя место для других элементов. Запросы, которые обходят кэш, по-прежнему направляются через выделенный шлюз. Эти запросы обслуживаются из серверной части и единиц затрат.

Обход кэша поддерживается в следующих версиях каждого пакета SDK:

SDK	Поддерживаемые версии
Пакет SDK версии 3 для .NET	>= 3.39.0
Пакет SDK для Java версии 4	>= 4.49.0
Пакет SDK для Node.js	>= 4.1.0
Пакет SDK для Python	Не поддерживается

.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

Параметр обхода встроенного запроса кэша недоступен в пакете SDK для Python.

Проверка попаданий в кэше

Наконец, можно перезапустить приложение и проверить взимаемую плату за запросы. Если она равна 0, повторяющиеся операции точечного чтения или запросы попадают в интегрированный кэш. После изменения CosmosClient для использования выделенной конечной точки шлюза все запросы будут направляться через выделенный шлюз.

Для запроса на чтение (точечное чтение или запрос) для использования интегрированного кэша должны выполняться все следующие условия:

• клиент подключается к выделенной конечной точке шлюза;
• клиент использует режим шлюза (в пакете SDK для Python и Node.js всегда используется режим шлюза);
• Должна быть установлена сеансовая или итоговая согласованность для запроса

Примечание.

Хотите поделиться мнением о встроенном кэше? Нам очень интересно ваше мнение! Вы можете поделиться им непосредственно с командой разработчиков Azure Cosmos DB по адресу cosmoscachefeedback@microsoft.com

Следующие шаги

• Вопросы и ответы по интегрированному кэшу
• Общие сведения об интегрированном кэше
• Выделенный шлюз