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

Подключение приложения Mongoose Node.js к Azure Cosmos DB

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

Это руководство содержит сведения об использовании платформы Mongoose при сохранении данных в Azure Cosmos DB. В этом пошаговом руководстве используется API Azure Cosmos DB для MongoDB. Для тех из вас, кто еще не знаком с Mongoose, — это платформа объектного моделирования для MongoDB в Node.js, которая представляет собой простое решение на основе схемы для моделирования данных приложения.

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

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

Если у вас еще нет подписки Azure, создайте бесплатную учетную запись Azure, прежде чем начинать работу.

Пробную версию Azure Cosmos DB можно использовать бесплатно, без подписки Azure и без и каких-либо обязательств. Кроме того, вы можете создать учетную запись Azure Cosmos DB категории "Бесплатный". Для этой учетной записи бесплатно предоставляются первые 1000 ЕЗ/с и 25 ГБ пространства в хранилище. Также можно использовать эмулятор Azure Cosmos DB, который доступен по URI https://localhost:8081. Сведения о ключе для использования с эмулятором см. в этом разделе.

Node.js версии 0.10.29 или более поздней.

Создание учетной записи Azure Cosmos DB

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

  1. В новом окне браузера войдите на портал Azure.

  2. В меню слева выберите Создать ресурс.

    Снимок экрана: создание ресурса на портале Azure.

  3. На странице New (Новый) выберите Базы данных>Azure Cosmos DB.

    Снимок экрана: область

  4. На странице "Выбор API" выберите Azure Cosmos DB для MongoDB>Create.

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

    Снимок экрана: область

  5. На странице Создание учетной записи Azure Cosmos DB введите параметры для новой учетной записи Azure Cosmos DB.

    Параметр значение Описание
    Подписка Название подписки Выберите подписку Azure, которую вы хотите использовать для этой учетной записи Azure Cosmos DB.
    Группа ресурсов Имя группы ресурсов Выберите группу ресурсов или Создать, затем введите уникальное имя для новой группы ресурсов.
    Имя учетной записи Укажите уникальное имя Введите уникальное имя для идентификации вашей учетной записи Azure Cosmos DB. URI вашего аккаунта mongo.cosmos.azure.com будет добавлен к вашему уникальному имени аккаунта.

    Имя может содержать только строчные буквы, цифры и дефисы (-). Его длина должна быть от 3 до 44 знаков.
    Расположение Ближайший к пользователям регион Выберите географическое расположение для размещения учетной записи Azure Cosmos DB. Используйте ближайшее к пользователям расположение, чтобы предоставить им максимально быстрый доступ к данным.
    Режим емкости Подготовленная пропускная способность или Бессерверный режим Выберите Подготовленная пропускная способность, чтобы создать учетную запись в режиме подготовленной пропускной способности. Выберите Бессерверный, чтобы создать учетную запись в режиме Бессерверный.

    Примечание. Только API для MongoDB версии 4.2, 4.0 и 3.6 поддерживаются бессерверными учетными записями. Если выбрать версию 3.2, учетная запись перейдет в режим использования подготовленной пропускной способности.
    Применение скидки на основе категории "Бесплатный" для Azure Cosmos DB Применить или не применять В категории "Бесплатный" Azure Cosmos DB для учетной записи бесплатно предоставляются первые 1000 единиц запросов в секунду и 25 ГБ свободного места. Ознакомьтесь с дополнительными сведениями о категории "Бесплатный".
    Версия Выбор требуемой версии сервера Azure Cosmos DB для MongoDB совместима с сервером версии 4.2, 4.0, 3.6 и 3.2. Вы можете обновить или понизить уровень учетной записи после ее создания.

    Примечание.

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

    Снимок экрана: страница новой учетной записи для Azure Cosmos DB.

  6. На вкладке Глобальное распределение настройте следующие сведения. При работе с этим кратким руководством можно оставить значения по умолчанию.

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

    Примечание.

    Следующие параметры недоступны, если вы выбрали значение Бессерверный для параметра Режим емкости:

    • Применить скидку бесплатного уровня
    • Геоизбыточность
    • Операции записи с поддержкой нескольких регионов

  7. При необходимости можно настроить дополнительные сведения на следующих вкладках.

  8. Выберите Review + create (Просмотреть и создать).

  9. Создание учетной записи занимает несколько минут. Дождитесь отображения поздравляем на портале! Ваша учетная запись Azure Cosmos DB для MongoDB готова .

    Снимок экрана: область уведомлений на портале Azure.

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

В этом приложении мы рассмотрим два способа создания коллекций в Azure Cosmos DB.

  • Хранение каждой объектной модели в отдельной коллекции. Мы рекомендуем создать базу данных с выделенной пропускной способностью. Использование этой модели емкости более экономично.

    Руководство по Node.js. Снимок экрана: на портале Azure демонстрируется создание базы данных, которая будет использоваться с модулем Mongoose Node, в обозревателе данных для учетной записи Azure Cosmos DB

  • Хранение всех объектных моделей в одной коллекции Azure Cosmos DB. Если вы предпочитаете хранить все модели в одной коллекции, можно просто создать новую базу данных без выбора параметра "Подготовка пропускной способности". При использовании этой модели емкости каждая коллекция будет создаваться с отдельной пропускной способностью для каждой объектной модели.

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

Настройка приложения Node.js

Примечание.

Если вы просто хотите ознакомиться с примером кода, а не настраивать приложение, клонируйте пример, используемый для этого руководства, и создайте приложение Mongoose на Node.js в Azure Cosmos DB.

  1. Чтобы создать приложение Node.js в выбранной папке, выполните следующую команду в командной строке узла.

    npm init

    Ответьте на вопросы, чтобы приступить к работе с проектом.

  2. Добавьте новый файл в папку и назовите его index.js.

  3. Установите необходимые пакеты, используя один из параметров npm install.

    • Mongoose: npm install mongoose --save

    Примечание.

    Дополнительные сведения о том, какая версия mongoose совместима с версией СЕРВЕРА API для MongoDB, см. в статье о совместимости Mongoose.

    • Dotenv (если вы хотите загрузить секреты из env-файла): npm install dotenv --save

      Примечание.

      Параметр --save позволяет добавить зависимость в файл package.json.

  4. Импортируйте зависимости в файл index.js.

    var mongoose = require('mongoose');
var env = require('dotenv').config();   //Use the .env file to load the variables

  5. Добавьте строка подключения Azure Cosmos DB и имя Azure Cosmos DB в .env файл. Замените заполнители {cosmos-account-name} и {dbname} собственным именем учетной записи Azure Cosmos DB и именем базы данных без символов фигурной скобки.

    // You can get the following connection details from the Azure portal. You can find the details on the Connection string pane of your Azure Cosmos DB account.

COSMOSDB_USER = "<Azure Cosmos DB account's user name, usually the database account name>"
COSMOSDB_PASSWORD = "<Azure Cosmos DB account password, this is one of the keys specified in your account>"
COSMOSDB_DBNAME = "<Azure Cosmos DB database name>"
COSMOSDB_HOST= "<Azure Cosmos DB Host name>"
COSMOSDB_PORT=10255

  6. Подключитесь к Azure Cosmos DB с помощью платформы Mongoose, добавив следующий код в конец файла index.js.

    mongoose.connect("mongodb://"+process.env.COSMOSDB_HOST+":"+process.env.COSMOSDB_PORT+"/"+process.env.COSMOSDB_DBNAME+"?ssl=true& replicaSet=globaldb", {
   auth: {
     username: process.env.COSMOSDB_USER,
     password: process.env.COSMOSDB_PASSWORD
   },
   useNewUrlParser: true,
   useUnifiedTopology: true,
   retryWrites: false
})
.then(() => console.log('Connection to CosmosDB successful'))
.catch((err) => console.error(err));

    Примечание.

    Здесь с помощью пакета npm dotenv загружаются переменные среды в виде process.env.{имя_переменной}.

    Подключившись к Azure Cosmos DB, вы можете приступить к настройке объектных моделей в Mongoose.

Рекомендации по использованию Mongoose с Azure Cosmos DB

Для каждой создаваемой вами модели Mongoose создает новую коллекцию. Для этого лучше всего использовать вариант пропускной способности на уровне базы данных, который обсуждался выше. Чтобы использовать одну коллекцию, вам потребуются дискриминаторы Mongoose. "Дискриминаторы" — это механизм наследования схемы. Он позволяет иметь несколько моделей с пересекающимися схемами поверх той же базовой коллекции MongoDB.

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

Одна коллекция на объектную модель

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

  1. Откройте index.js еще раз.

  2. Создайте определение схемы Family (семья).

    const Family = mongoose.model('Family', new mongoose.Schema({
    lastName: String,
    parents: [{
        familyName: String,
        firstName: String,
        gender: String
    }],
    children: [{
        familyName: String,
        firstName: String,
        gender: String,
        grade: Number
    }],
    pets:[{
        givenName: String
    }],
    address: {
        country: String,
        state: String,
        city: String
    }
}));

  3. Создайте объект Family (семья).

    const family = new Family({
    lastName: "Volum",
    parents: [
        { firstName: "Thomas" },
        { firstName: "Mary Kay" }
    ],
    children: [
        { firstName: "Ryan", gender: "male", grade: 8 },
        { firstName: "Patrick", gender: "male", grade: 7 }
    ],
    pets: [
        { givenName: "Buddy" }
    ],
    address: { country: "USA", state: "WA", city: "Seattle" }
});

  4. Наконец, сохраните объект в Azure Cosmos DB. При этом в фоновом режиме будет создана коллекция.

    family.save((err, saveFamily) => {
    console.log(JSON.stringify(saveFamily));
});

  5. Теперь создайте другие схему и объект. В этот раз создайте их для мест отдыха (VacationDestinations), которые могут заинтересовать семьи.

    1. Как и в прошлом примере, создайте схему.

      const VacationDestinations = mongoose.model('VacationDestinations', new mongoose.Schema({
 name: String,
 country: String
}));

    2. Создайте и сохраните пример объекта (к этой схеме можно добавить несколько объектов).

      const vacaySpot = new VacationDestinations({
 name: "Honolulu",
 country: "USA"
});

vacaySpot.save((err, saveVacay) => {
 console.log(JSON.stringify(saveVacay));
});

  6. Теперь при входе на портал Azure вы увидите две коллекции, созданные в Azure Cosmos DB.

    Руководство по Node.js. Снимок экрана: портал Azure с учетной записью Azure Cosmos DB и выделенными именами коллекций. База данных Node

  7. Наконец, выполните считывание данных с Azure Cosmos DB. Так как используется стандартная операционная модель Mongoose, операции чтения идентичны таким же операциям с Mongoose.

    Family.find({ 'children.gender' : "male"}, function(err, foundFamily){
    foundFamily.forEach(fam => console.log("Found Family: " + JSON.stringify(fam)));
});

Хранение данных в одной коллекции с помощью дискриминаторов Mongoose

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

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

  1. Настройте базовую конфигурацию и определите ключ дискриминатора.

    const baseConfig = {
    discriminatorKey: "_type", //If you've got a lot of different data types, you could also consider setting up a secondary index here.
    collection: "alldata"   //Name of the Common Collection
};

  2. Затем определите общую объектную модель.

    const commonModel = mongoose.model('Common', new mongoose.Schema({}, baseConfig));

  3. Теперь определите модель Family. Обратите внимание, что вместо mongoose.model используется commonModel.discriminator. Кроме того, к схеме Mongoose добавлена базовая конфигурация. Итак, FamilyType — это ключ дискриминатора.

    const Family_common = commonModel.discriminator('FamilyType', new     mongoose.Schema({
    lastName: String,
    parents: [{
        familyName: String,
        firstName: String,
        gender: String
    }],
    children: [{
        familyName: String,
        firstName: String,
       gender: String,
        grade: Number
    }],
    pets:[{
        givenName: String
    }],
    address: {
        country: String,
        state: String,
        city: String
    }
}, baseConfig));

  4. Аналогичным образом добавьте другую схему, на этот раз для VacationDestinations. В этом случае ключ дискриминатора — это VacationDestinationsType.

    const Vacation_common = commonModel.discriminator('VacationDestinationsType', new mongoose.Schema({
    name: String,
    country: String
}, baseConfig));

  5. Наконец, создайте объекты для модели и сохраните ее.

    1. Добавьте объекты к модели Family.

      const family_common = new Family_common({
 lastName: "Volum",
 parents: [
     { firstName: "Thomas" },
     { firstName: "Mary Kay" }
 ],
 children: [
     { firstName: "Ryan", gender: "male", grade: 8 },
     { firstName: "Patrick", gender: "male", grade: 7 }
 ],
 pets: [
     { givenName: "Buddy" }
 ],
 address: { country: "USA", state: "WA", city: "Seattle" }
});

family_common.save((err, saveFamily) => {
 console.log("Saved: " + JSON.stringify(saveFamily));
});

    2. Затем добавьте объекты к модели VacationDestinations и сохраните ее.

      const vacay_common = new Vacation_common({
 name: "Honolulu",
 country: "USA"
});

vacay_common.save((err, saveVacay) => {
 console.log("Saved: " + JSON.stringify(saveVacay));
});

  6. Теперь, если вернуться на портал Azure, вы заметите, что у вас есть лишь одна коллекция alldata с данными Family и VacationDestinations.

    Руководство по Node.js. Снимок экрана: портал Azure с учетной записью Azure Cosmos DB и выделенным именем коллекции. База данных Node

  7. Кроме того, обратите внимание, что каждый объект имеет еще один атрибут с именем __type, который позволяет различать две разные объектные модели.

  8. Наконец, выполните считывание данных, хранящихся в Azure Cosmos DB. Mongoose позволяет фильтровать данные на основе модели. Таким образом, вам не нужно будет выполнять другие действия при считывании данных. Просто укажите свою модель (в этом случае Family_common), и Mongoose выполнит фильтрацию по DiscriminatorKey.

    Family_common.find({ 'children.gender' : "male"}, function(err, foundFamily){
    foundFamily.forEach(fam => console.log("Found Family (using discriminator): " + JSON.stringify(fam)));
});

Как видите, работать с дискриминаторами Mongoose очень легко. Если у вас есть приложение, использующее платформу Mongoose, это руководство поможет настроить и запустить его с помощью API Azure Cosmos DB для MongoDB без большого количества изменений.

Очистка ресурсов

После завершения работы с приложением и учетной записью Azure Cosmos DB можно удалить созданные ресурсы Azure, чтобы избежать дополнительных расходов. Удаление ресурсов:

  1. На панели поиска портала Azure найдите и выберите Группы ресурсов.

  2. Выберите из списка группу ресурсов, созданную для этого краткого руководства.

    Выбор группы ресурсов для удаления

  3. На странице обзора группы ресурсов выберите Удалить группу ресурсов.

    Удаление группы ресурсов

  4. В следующем окне введите имя группы ресурсов, которую требуется удалить, и щелкните Удалить.

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