Поделиться через

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

  • Статья

Область применения: MongoDB

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

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

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

Вы можете воспользоваться этими преимуществами, сохраняя свои инвестиции в существующее приложение MongoDB[s]. Вы можете взаимодействовать с 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
}

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

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

Используйте 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 представляет токен возобновления. Команда возвращает curser для всех документов, которые были вставлены, обновлены или заменены из этой физической секции после выполнения пользовательской команды 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: