Настройка интегрированного кэша 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 минут, пока подготовка выделенного шлюза будет завершена. По завершении подготовки вы увидите следующее уведомление:

   

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

При создании выделенного шлюза автоматически подготавливается интегрированный кэш.

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

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

   

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

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

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

Примечание.

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

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

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

Примечание.

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

Настройка 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.35.0-preview
Пакет SDK для Java версии 4	>= 4.49.0
Пакет SDK для Node.js	Не поддерживается
Пакет 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

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

Python

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

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

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

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

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

Примечание.

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

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

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