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

ПРИМЕНИМО К: API Azure Cosmos DB для MongoDB

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

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

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

API-интерфейс 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"});

Это приведет к созданию фиксированной, несегментированной коллекции размером в 400 единиц запросов и автоматическому созданию индекса в поле _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 Возвращается только при сбое команды (т. е. ОК == 0). Содержит код ошибки MongoDB. Это необязательный параметр ответа.
errMsg string Возвращается только при сбое команды (т. е. ОК == 0). Содержит понятное сообщение об ошибке. Это необязательный параметр ответа.

Пример:

{ "ok" : 1 }

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

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