Использование команд расширения MongoDB для управления данными, хранящимися в Azure Cosmos DB для MongoDB

  • Статья

ПРИМЕНИМО К: Mongodb

В следующем документе содержатся пользовательские команды действий, относящиеся к Azure Cosmos DB для MongoDB. Эти команды можно использовать для создания и получения ресурсов базы данных, относящихся к модели емкости Azure Cosmos DB.

Используя Azure Cosmos DB для MongoDB, вы можете воспользоваться общими преимуществами Azure Cosmos DB. К этим преимуществам относятся, помимо прочего, следующие:

  • Глобальное распределение
  • Автоматическое сегментирование
  • Высокий уровень доступности
  • Гарантии относительно задержки
  • Шифрование при хранении
  • Резервные копии

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

Поддержка протокола MongoDB

Azure Cosmos DB для MongoDB совместим с сервером MongoDB версий 4.0, 3.6 и 3.2. Дополнительные сведения см. в статье Поддерживаемые функции и синтаксис в версиях 4.0, 3.6 и 3.2.

Следующие команды расширения создают и изменяют ресурсы, относящиеся к Azure Cosmos DB, с помощью запросов к базе данных:

Создание базы данных

Команда расширения для создания базы данных создает базу данных MongoDB. Имя базы данных можно использовать из контекста базы данных, установленного командой use database. В следующей таблице описаны параметры в команде:

Поле Тип Описание
customAction string Имя пользовательской команды. Значение должно быть равно CreateDatabase.
offerThroughput int Подготовленная пропускная способность, заданная для базы данных. Это необязательный параметр.
autoScaleSettings Object Обязательный параметр для режима автомасштабирования. Этот объект содержит параметры, связанные с режимом емкости автомасштабирования. Можно настроить maxThroughput значение , описывающее наибольшее число единиц запросов, до которых коллекция может динамически увеличиваться.

Выходные данные

Если команда выполнена успешно, она возвращает следующий ответ:

{ "ok" : 1 }

Просмотрите выходные данные по умолчанию пользовательской команды для параметров в выходных данных.

Пример. Создание базы данных

Чтобы создать базу данных с именем "test", использующую все значения по умолчанию, выполните следующую команду:

use test
db.runCommand({customAction: "CreateDatabase"});

Эта команда создает базу данных без пропускной способности на уровне базы данных. Эта операция означает, что коллекции в этой базе данных должны указывать объем пропускной способности, который необходимо использовать.

Пример. Создание базы данных с пропускной способностью

Чтобы создать базу данных с именем "test" и указать подготовленную пропускную способность уровня базы данных в 1000 единиц запросов, используйте следующую команду:

use test
db.runCommand({customAction: "CreateDatabase", offerThroughput: 1000 });

Эта команда создает базу данных и задает для нее пропускную способность. Все коллекции в этой базе данных используют заданную пропускную способность, если только коллекции не созданы с определенным уровнем пропускной способности.

Пример. Создание базы данных с автомасштабированием пропускной способности

Чтобы создать базу данных с именем "test" и указать максимальную автомасштабируемую пропускную способность в 20 000 единиц запросов в секунду на уровне базы данных, используйте следующую команду:

use test
db.runCommand({customAction: "CreateDatabase", autoScaleSettings: { maxThroughput: 20000 } });

Обновление базы данных

Команда расширения для обновления базы данных обновляет свойства, связанные с указанной базой данных. Изменение подготовленной пропускной способности базы данных на автомасштабирование и наоборот поддерживается только в портал Azure. В следующей таблице описаны параметры в команде:

Поле Тип Описание
customAction string Имя пользовательской команды. Значение должно быть равно UpdateDatabase.
offerThroughput int Новая подготовленная пропускная способность, которую необходимо задать для базы данных, если в базе данных используется пропускная способность уровня базы данных.
autoScaleSettings Object Обязательный параметр для режима автомасштабирования. Этот объект содержит параметры, связанные с режимом емкости автомасштабирования. Можно задать maxThroughput значение , описывающее наибольшее число единиц запросов, до которых база данных может быть динамически увеличена.

Эта команда использует базу данных, указанную в контексте сеанса. Это та же база данных, которая использовалась в команде use <database> . На данный момент имя базы данных нельзя изменить с помощью этой команды.

Выходные данные

Если команда выполнена успешно, она возвращает следующий ответ:

{ "ok" : 1 }

Просмотрите выходные данные по умолчанию пользовательской команды для параметров в выходных данных.

Пример. Обновление подготовленной пропускной способности, связанной с базой данных

Чтобы обновить подготовленную пропускную способность базы данных с именем "test" до 1200 единиц запросов, используйте следующую команду:

use test
db.runCommand({customAction: "UpdateDatabase", offerThroughput: 1200 });

Пример. Обновление пропускной способности автомасштабирования, связанной с базой данных

Чтобы обновить подготовленную пропускную способность базы данных с именем "test" до 20 000 единиц запросов или преобразовать ее в уровень автомасштабируемой пропускной способности, используйте следующую команду:

use test
db.runCommand({customAction: "UpdateDatabase", autoScaleSettings: { maxThroughput: 20000 } });

Получение базы данных

Команда расширения для получения базы данных возвращает объект базы данных. Имя базы данных используется из контекста базы данных, для которого выполняется команда.

{
  customAction: "GetDatabase"
}

В следующей таблице описаны параметры в команде:

Поле Тип Описание
customAction string Имя пользовательской команды. Значение должно быть равно GetDatabase.

Выходные данные

Если команда выполнена успешно, ответ будет содержать документ со следующими полями:

Поле Тип Описание
ok int Состояние ответа. 1 == успешное завершение. 0 == неудачное завершение.
database string Имя базы данных.
provisionedThroughput int Подготовленная пропускная способность, заданная для базы данных, если в базе данных используется пропускная способность уровня базы данных, заданная вручную.
autoScaleSettings Object Этот объект содержит параметры емкости, связанные с базой данных, если она использует режим автомасштабирования. Значение maxThroughput описывает наибольшее число единиц запросов, до которых база данных может быть динамически увеличена.

Если команда завершается ошибкой, возвращается ответ пользовательской команды по умолчанию. Просмотрите выходные данные по умолчанию пользовательской команды для параметров в выходных данных.

Пример. Получение базы данных

Чтобы получить объект базы данных с именем "test", используйте следующую команду:

use test
db.runCommand({customAction: "GetDatabase"});

Если с базой данных не связана пропускная способность, выходные данные будут выглядеть следующим образом:

{ "database" : "test", "ok" : 1 }

Если с базой данных связана пропускная способность на уровне базы данных, заданная вручную, то выходные данные будут содержать значения provisionedThroughput:

{ "database" : "test", "provisionedThroughput" : 20000, "ok" : 1 }

Если с базой данных связана автомасштабируемая пропускная способность на уровне базы данных, то в выходных данных будет отображаться provisionedThroughput, что описывает минимальное количество единиц запросов в базе данных, и объект autoScaleSettings, включая maxThroughput, который описывает максимальное количество единиц запросов в секунду для базы данных.

{
        "database" : "test",
        "provisionedThroughput" : 2000,
        "autoScaleSettings" : {
                "maxThroughput" : 20000
        },
        "ok" : 1
}

Создание коллекции

Команда расширения для создания коллекции создает коллекцию MongoDB. Имя для базы данных используется из контекста базы данных, заданного командой use database. Формат команды CreateCollection выглядит следующим образом:

{
  customAction: "CreateCollection",
  collection: "<Collection Name>",
  shardKey: "<Shard key path>",
  // Replace the line below with "autoScaleSettings: { maxThroughput: (int) }" to use Autoscale instead of Provisioned Throughput. Fill the required Autoscale max throughput setting.
  offerThroughput: (int) // Provisioned Throughput enabled with required throughput amount set.
  indexes: [{key: {_id: 1}, name: "_id_1"}, ... ] // Optional indexes (3.6+ accounts only).
}

В следующей таблице описаны параметры в команде:

Поле Тип Обязательно Описание
customAction string Обязательно Имя пользовательской команды. Значение должно быть равно CreateCollection.
collection string Обязательно Имя коллекции. Специальные символы и пробелы запрещены.
offerThroughput int Необязательно Подготовленная пропускная способность, которую необходимо задать для базы данных. Если этот параметр не указан, он по умолчанию составляет не менее 400 ЕЗ/с. * Чтобы указать пропускную способность свыше 10 000 единиц запросов в секунду, необходимо задать параметр shardKey.
shardKey string Требуется для коллекций с большой пропускной способностью. Путь к ключу сегмента для сегментированной коллекции. Этот параметр является обязательным, если в offerThroughput задано более 10 000 единиц запросов в секунду. Если он указан, для всех вставляемых документов требуются этот ключ и значение.
autoScaleSettings Object Обязательный параметр для режима автомасштабирования Этот объект содержит параметры, связанные с режимом емкости автомасштабирования. Можно настроить maxThroughput значение , которое описывает наибольшее число единиц запросов, до которых можно динамически увеличивать коллекцию.
indexes Array При необходимости настройте индексы. Этот параметр поддерживается только для учетных записей 3.6+. При наличии параметра требуется индекс для _id. Каждая запись в массиве должна включать ключ одного или нескольких полей, имя и может содержать параметры индекса. Например, чтобы создать составной уникальный индекс для полей a и b, используйте эту запись: {key: {a: 1, b: 1}, name:"a_1_b_1", unique: true}.

Выходные данные

Возвращает ответ пользовательской команды по умолчанию. Просмотрите выходные данные по умолчанию пользовательской команды для параметров в выходных данных.

Пример. Создание коллекции с минимальной конфигурацией

Чтобы создать коллекцию с именем "testCollection" и значениями по умолчанию, используйте следующую команду:

use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection"});

Эта операция приводит к созданию новой фиксированной, несегментированной коллекции с 400RU/s и автоматически созданным индексом в _id поле. Этот тип конфигурации также применяется при создании новых коллекций insert() с помощью функции . Пример:

use test
db.newCollection.insert({});

Пример. Создание несегментированной коллекции

Чтобы создать несегментированную коллекцию с именем "testCollection" и подготовленной пропускной способностью 1000 ЕЗ, используйте следующую команду:

use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection", offerThroughput: 1000});

Можно создать коллекцию размером до 10 000 единиц запросов в секунду в качестве offerThroughput, и при этом вам не нужно будет указывать ключ сегмента. Сведения о коллекциях с большей пропускной способностью см. в следующем разделе.

Пример. Создание сегментированной коллекции

Чтобы создать сегментированную коллекцию с именем "testCollection" и подготовленной пропускной способностью в 11 000 единиц запросов, а также свойством a.b shardkey, используйте следующую команду:

use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection", offerThroughput: 11000, shardKey: "a.b" });

Теперь для этой команды требуется параметр shardKey, так как в параметре offerThroughput задано более 10 000 единиц запросов в секунду.

Пример. Создание несегментированной коллекции автомасштабирования

Чтобы создать несегментированную коллекцию с именем 'testCollection', которая использует автомасштабируемую пропускную способность в 4000 единиц запросов в секунду, выполните следующую команду:

use test
db.runCommand({ 
    customAction: "CreateCollection", collection: "testCollection", 
    autoScaleSettings:{
      maxThroughput: 4000
    } 
});

autoScaleSettings.maxThroughput Для значения можно указать диапазон от 4000 ЕЗ/с до 10 000 ЕЗ/с без ключа сегмента. Для более высокой автомасштабируемой пропускной способности необходимо указать параметр shardKey.

Пример. Создание сегментированной коллекции автомасштабирования

Чтобы создать сегментированную коллекцию с именем 'testCollection' и ключом сегмента 'a.b', которая использует автомасштабируемую пропускную способность в размере 20 000 единиц запросов в секунду, выполните следующую команду:

use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection", shardKey: "a.b", autoScaleSettings: { maxThroughput: 20000 }});

Обновление коллекции

Команда расширения для обновления коллекции обновляет свойства, связанные с указанной коллекцией. Изменение подготовленной пропускной способности коллекции на автомасштабирование и наоборот поддерживается только в портал Azure.

{
  customAction: "UpdateCollection",
  collection: "<Name of the collection that you want to update>",
  // Replace the line below with "autoScaleSettings: { maxThroughput: (int) }" if using Autoscale instead of Provisioned Throughput. Fill the required Autoscale max throughput setting. Changing between Autoscale and Provisioned throughput is only supported in the Azure Portal.
  offerThroughput: (int) // Provisioned Throughput enabled with required throughput amount set.
  indexes: [{key: {_id: 1}, name: "_id_1"}, ... ] // Optional indexes (3.6+ accounts only).
}

В следующей таблице описаны параметры в команде:

Поле Тип Описание
customAction string Имя пользовательской команды. Значение должно быть равно UpdateCollection.
collection string Имя коллекции.
offerThroughput int Подготовленная пропускная способность, которую необходимо задать для коллекции.
autoScaleSettings Object Обязательный параметр для режима автомасштабирования. Этот объект содержит параметры, связанные с режимом емкости автомасштабирования. Значение maxThroughput описывает наибольшее число единиц запросов, до которых можно динамически увеличить коллекцию.
indexes Array При необходимости настройте индексы. Этот параметр поддерживается только для учетных записей 3.6+. При наличии указанный набор индексов (включая отбрасываемые индексы) заменяет существующие индексы коллекции. Требуется индекс для _id. Каждая запись в массиве должна включать ключ одного или нескольких полей, имя и может содержать параметры индекса. Например, чтобы создать составной уникальный индекс для полей a и b, используйте эту запись: {key: {a: 1, b: 1}, name: "a_1_b_1", unique: true}.

Выходные данные

Возвращает ответ пользовательской команды по умолчанию. Просмотрите выходные данные по умолчанию пользовательской команды для параметров в выходных данных.

Пример. Обновление подготовленной пропускной способности, связанной с коллекцией

Чтобы обновить подготовленную пропускную способность коллекции с именем "testCollection" до 1200 единиц запросов, используйте следующую команду:

use test
db.runCommand({customAction: "UpdateCollection", collection: "testCollection", offerThroughput: 1200 });

Получение коллекции

Пользовательская команда получения коллекции возвращает объект коллекции.

{
  customAction: "GetCollection",
  collection: "<Name of the collection>"
}

В следующей таблице описаны параметры в команде:

Поле Тип Описание
customAction string Имя пользовательской команды. Значение должно быть равно GetCollection.
collection string Имя коллекции.

Выходные данные

Если команда выполнена успешно, ответ будет содержать документ со следующими полями:

Поле Тип Описание
ok int Состояние ответа. 1 == успешное завершение. 0 == неудачное завершение.
database string Имя базы данных.
collection string Имя коллекции.
shardKeyDefinition document Документ спецификации индекса, используемый в качестве ключа сегмента. Это поле является необязательным параметром ответа.
provisionedThroughput int Подготовленная пропускная способность, которую необходимо задать для коллекции. Это поле является необязательным параметром ответа.
autoScaleSettings Object Этот объект содержит параметры емкости, связанные с базой данных, если используется режим автомасштабирования. Значение maxThroughput описывает наибольшее число единиц запроса, до которых можно динамически увеличивать коллекцию.

Если команда завершается ошибкой, возвращается ответ пользовательской команды по умолчанию. Просмотрите выходные данные по умолчанию пользовательской команды для параметров в выходных данных.

Пример. Получение коллекции

Чтобы получить объект коллекции с именем "testCollection", используйте следующую команду:

use test
db.runCommand({customAction: "GetCollection", collection: "testCollection"});

Если с коллекцией связана пропускная способность, она включает provisionedThroughput значение , а выходные данные будут следующими:

{
        "database" : "test",
        "collection" : "testCollection",
        "provisionedThroughput" : 400,
        "ok" : 1
}

Если коллекция имеет связанную пропускную способность автомасштабирования, она включает autoScaleSettings объект с параметром maxThroughput , который определяет максимальную пропускную способность, которую коллекция увеличивает динамически. Кроме того, он также включает provisionedThroughput значение , которое определяет минимальную пропускную способность, которую эта коллекция уменьшает до, если в коллекции нет запросов:

{
        "database" : "test",
        "collection" : "testCollection",
        "provisionedThroughput" : 1000,
        "autoScaleSettings" : {
            "maxThroughput" : 10000
        },
        "ok" : 1
}

Если в коллекции используется общая пропускная способность на уровне базы данных в режиме автомасштабирования или ручном режиме, выходные данные будут выглядеть следующим образом:

{ "database" : "test", "collection" : "testCollection", "ok" : 1 }

{
        "database" : "test",
        "provisionedThroughput" : 2000,
        "autoScaleSettings" : {
            "maxThroughput" : 20000
        },
        "ok" : 1
}

Параллелизация потоков изменений

При использовании потоков изменений в большом масштабе лучше равномерно распределять нагрузку. Следующая команда возвращает один или несколько токенов возобновления потока изменений, каждый из которых соответствует данным из одного физического сегмента или секции (в одной физической секции может существовать несколько логических сегментов или секций). Каждый маркер возобновления приводит к тому, что функция watch() возвращает данные только из этого физического сегмента или секции.

Используйте db.collection.watch() для каждого маркера возобновления (по одному потоку на маркер), чтобы эффективно масштабировать потоки изменений.

{
        customAction: "GetChangeStreamTokens", 
        collection: "<Name of the collection>", 
        startAtOperationTime: "<BSON Timestamp>" // Optional. Defaults to the time the command is run.
}

Пример. Получение маркера потока

Выполните пользовательскую команду, чтобы получить токен возобновления для каждого физического сегмента или каждой физической секции.

use test
db.runCommand({customAction: "GetChangeStreamTokens", collection: "<Name of the collection>"})

Запустите процесс или поток watch() для каждого токена возобновления, возвращенного из пользовательской команды GetChangeStreamTokens. Ниже приведен пример для одного потока.

db.test_coll.watch([{ $match: { "operationType": { $in: ["insert", "update", "replace"] } } }, { $project: { "_id": 1, "fullDocument": 1, "ns": 1, "documentKey": 1 } }], 
{fullDocument: "updateLookup", 
resumeAfter: { "_data" : BinData(0,"eyJWIjoyLCJSaWQiOiJQeFVhQUxuMFNLRT0iLCJDb250aW51YXRpb24iOlt7IkZlZWRSYW5nZSI6eyJ0eXBlIjoiRWZmZWN0aXZlIFBhcnRpdGlvbiBLZXkgUmFuZ2UiLCJ2YWx1ZSI6eyJtaW4iOiIiLCJtYXgiOiJGRiJ9fSwiU3RhdGUiOnsidHlwZSI6ImNvbnRpbndkFLbiIsInZhbHVlIjoiXCIxODQ0XCIifX1dfQ=="), "_kind" : NumberInt(1)}})

Документ (значение) в поле resumeAfter представляет токен возобновления. Команда watch() возвращает средство обработки для всех документов, которые были вставлены, обновлены или заменены из этой физической секции с момента выполнения пользовательской команды GetChangeStreamTokens. Здесь приведен пример возвращаемых данных.

{
  "_id": {
    "_data": BinData(0,
    "eyJWIjoyLCJSaWQiOiJQeFVhQUxuMFNLRT0iLCJDfdsfdsfdsft7IkZlZWRSYW5nZSI6eyJ0eXBlIjoiRWZmZWN0aXZlIFBhcnRpdGlvbiBLZXkgUmFuZ2UiLCJ2YWx1ZSI6eyJtaW4iOiIiLCJtYXgiOiJGRiJ9fSwiU3RhdGUiOnsidHlwZSI6ImNvbnRpbnVhdGlvbiIsInZhbHVlIjoiXCIxOTgwXCIifX1dfQ=="),
    "_kind": 1
  },
  "fullDocument": {
    "_id": ObjectId("60da41ec9d1065b9f3b238fc"),
    "name": John,
    "age": 6
  },
  "ns": {
    "db": "test-db",
    "coll": "test_coll"
  },
  "documentKey": {
    "_id": ObjectId("60da41ec9d1065b9f3b238fc")
  }
}

Каждый возвращаемый документ содержит маркер возобновления (они одинаковы для каждой страницы). Этот токен возобновления должен быть сохранен и использован повторно в случае завершения потока или процесса. Этот маркер возобновления получает данные только из этой физической секции.

Выходные данные пользовательской команды по умолчанию

Если не указано, пользовательский ответ содержит документ со следующими полями:

Поле Тип Описание
ok int Состояние ответа. 1 == успешное завершение. 0 == неудачное завершение.
code int Возвращается только при сбое команды (то есть ok == 0). Содержит код ошибки MongoDB. Это поле является необязательным параметром ответа.
errMsg string Возвращается только при сбое команды (то есть ok == 0). Содержит понятное сообщение об ошибке. Это поле является необязательным параметром ответа.

Пример:

{ "ok" : 1 }

Дальнейшие действия

Далее можно перейти к изучению следующих понятий Azure Cosmos DB: