Краткое руководство. Драйвер Azure Cosmos DB для MongoDB для Node.js

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

• .NET
• Python
• Java
• Node.js
• Go

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

Примечание.

Примеры фрагментов кода доступны на GitHub в виде проекта JavaScript.

Справочная документация | по API для MongoDB Package (NuGet) /Microsoft.Azure.Cosmos) | Интерфейс командной строки разработчика Azure

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

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
• Учетная запись GitHub

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
• Интерфейс командной строки разработчика Azure
• Docker Desktop

Установка

Разверните контейнер разработки этого проекта в вашей среде. Затем используйте интерфейс командной строки разработчика Azure (azd) для создания учетной записи Azure Cosmos DB для MongoDB и развертывания контейнерного примера приложения. Пример приложения использует клиентская библиотека для управления, создания, чтения и запроса примеров данных.

Внимание

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

1. Откройте терминал в корневом каталоге проекта.

2. Проверка подлинности в интерфейсе командной строки разработчика Azure с помощью azd auth login. Выполните действия, указанные средством для проверки подлинности в CLI с помощью предпочитаемых учетных данных Azure.

   azd auth login
   

3. Используется azd init для инициализации проекта.

   azd init
   

4. Во время инициализации настройте уникальное имя среды.

   Совет

   Имя среды также будет использоваться в качестве имени целевой группы ресурсов. В этом кратком руководстве рекомендуется использовать msdocs-cosmos-db.

5. Разверните учетную запись Azure Cosmos DB с помощью azd up. Шаблоны Bicep также развертывают пример веб-приложения.

   azd up
   

6. В процессе подготовки выберите подписку и нужное расположение. Дождитесь завершения процесса подготовки. Процесс может занять около пяти минут.

7. После завершения подготовки ресурсов Azure в выходные данные будет включен URL-адрес работающего веб-приложения.

   Deploying services (azd deploy)
   
     (✓) Done: Deploying service web
   - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>
   
   SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
   

8. Используйте URL-адрес консоли для перехода к веб-приложению в браузере. Просмотрите выходные данные запущенного приложения.

   

---

Установка пакета

Добавьте пакет npm для MongoDB в проект JavaScript. Используйте команду npm install package, указывающую имя пакета npm. Пакет dotenv используется для считывания переменных среды из файла .env во время локальной разработки.

npm install mongodb dotenv

Объектная модель

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

Иерархическая схема с учетной записью Azure Cosmos DB в верхней части. У учетной записи есть два дочерних сегмента базы данных. Один из сегментов базы данных включает два дочерних сегмента коллекции. Другой сегмент базы данных включает один дочерний узел коллекции. Этот сегмент одной коллекции содержит три дочерних сегмента документации.

Для взаимодействия с этими ресурсами вы будете использовать следующие классы MongoDB:

• MongoClient — Этот класс предоставляет логическое представление на стороне клиента для уровня API для MongoDB в Azure Cosmos DB. Этот клиентский объект позволяет настраивать и выполнять запросы к службе.
• Db — этот класс является ссылкой на базу данных, которая может еще не существовать в службе. База данных проверяется на стороне сервера при попытке доступа к ней или выполнении операции с ней.
• Collection — этот класс является ссылкой на коллекцию, которая может еще не существовать в службе. Коллекция проверяется на стороне сервера при попытке работы с ней.

Примеры кода

• аутентификация клиента;
• Получение экземпляра базы данных
• Получение экземпляра коллекции
• Цепочки экземпляров
• Создание индекса
• Создание документа
• Получение документа
• Запрашивание документов

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

Для этой процедуры база данных не будет использовать сегментирование.

аутентификация клиента;

1. В каталоге проекта создайте файл index.js. В редакторе добавьте инструкции require для ссылки на пакеты npm MongoDB и DotEnv.

   // Read .env file and set environment variables
   require('dotenv').config();
   const random = Math.floor(Math.random() * 100);
   
   // Use official mongodb driver to connect to the server
   const { MongoClient, ObjectId } = require('mongodb');
   

2. Определите новый экземпляр класса MongoClient, с помощью конструктора и process.env., чтобы считать созданную ранее переменную среды.

   // New instance of MongoClient with connection string
   // for Cosmos DB
   const url = process.env.COSMOS_CONNECTION_STRING;
   const client = new MongoClient(url);
   

Дополнительные сведения о различных способах создания экземпляра MongoClient см. в на странице по драйверу NodeJS для MongoDB.

Настройка асинхронных операций

В файле index.js добавьте следующий код для поддержки асинхронных операций:

async function main(){

// The remaining operations are added here
// in the main function

}

main()
  .then(console.log)
  .catch(console.error)
  .finally(() => client.close());

Для обработки синтаксиса async/await в функцию main нужно добавить следующие фрагменты кода.

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

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

// Use connect method to connect to the server
await client.connect();

Получение экземпляра базы данных

MongoClient.db возвращает ссылку на базу данных.

// Database reference with creation if it does not already exist
const db = client.db(`adventureworks`);
console.log(`New database:\t${db.databaseName}\n`);

Получение экземпляра коллекции

MongoClient.Db.collection возвращает ссылку на коллекцию.

// Collection reference with creation if it does not already exist
const collection = db.collection('products');
console.log(`New collection:\t${collection.collectionName}\n`);

Цепочки экземпляров

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

const db = await client.db(`adventureworks`).collection('products').updateOne(query, update, options)

Создание индекса

Используйте Collection.createIndex, чтоб создать индекс для свойств документа, которые вы планируете использовать для сортировки с помощью метода MongoDB FindCursor.sort.

// create index to sort by name
const indexResult = await collection.createIndex({ name: 1 });
console.log(`indexResult: ${JSON.stringify(indexResult)}\n`);

Создание документа

Создайте документ со свойствами продукта для базы данных adventureworks:

• Свойство _id для уникального идентификатора продукта.
• Свойство category. Это свойство можно использовать в качестве ключа логической секции.
• Свойство name.
• Свойство quantity для инвентаризации.
• Свойство sale, указывающее, участвует ли продукт в распродаже.

// Create new doc and upsert (create or replace) to collection
const product = {
    category: "gear-surf-surfboards",
    name: `Yamba Surfboard-${random}`,
    quantity: 12,
    sale: false
};
const query = { name: product.name};
const update = { $set: product };
const options = {upsert: true, new: true};

// Insert via upsert (create or replace) doc to collection directly
const upsertResult1 = await collection.updateOne(query, update, options);
console.log(`upsertResult1: ${JSON.stringify(upsertResult1)}\n`);

// Update via upsert on chained instance
const query2 = { _id: ObjectId(upsertResult1.upsertedId) };
const update2 = { $set: { quantity: 20 } };
const upsertResult2 = await client.db(`adventureworks`).collection('products').updateOne(query2, update2, options);
console.log(`upsertResult2: ${JSON.stringify(upsertResult2)}\n`);

Создайте документ в коллекции путем вызова Collection.UpdateOne. В этом примере мы выбрали операцию upsert вместо create для нового документа на тот случай, если вы запускаете этот пример кода несколько раз.

Получение документа

В Azure Cosmos DB можно выполнить менее требовательную к ресурсам операцию точечного чтения, используя уникальный идентификатор (_id) и ключа секции (category).

// Point read doc from collection:
// - without sharding, should use {_id}
// - with sharding,    should use {_id, partitionKey }, ex: {_id, category}
const foundProduct = await collection.findOne({
    _id: ObjectId(upsertResult1.upsertedId), 
    category: "gear-surf-surfboards"
});
console.log(`foundProduct: ${JSON.stringify(foundProduct)}\n`);

Запрашивание документов

После вставки документа можно выполнить запрос, чтобы получить все документы, соответствующие определенному фильтру. В этом примере выполняется поиск всех документов, соответствующих определенной категории: gear-surf-surfboards. После определения запроса вызовите Collection.find, чтобы получить результат FindCursor. Преобразуйте курсор в массив для использования методов массива JavaScript.

// select all from product category
const allProductsQuery = { 
    category: "gear-surf-surfboards" 
};

// get all documents, sorted by name, convert cursor into array
const products = await collection.find(allProductsQuery).sort({name:1}).toArray();
products.map((product, i ) => console.log(`${++i} ${JSON.stringify(product)}`));

Устранение неполадок:

• Если возникает ошибка, например The index path corresponding to the specified order-by item is excluded., убедитесь, что вы создали индекс.

Выполнение кода

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

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

node index.js

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

New database:   adventureworks

New collection: products

upsertResult1: {"acknowledged":true,"modifiedCount":0,"upsertedId":"62b1f492ff69395b30a03169","upsertedCount":1,"matchedCount":0}

upsertResult2: {"acknowledged":true,"modifiedCount":1,"upsertedId":null,"upsertedCount":0,"matchedCount":1}

foundProduct: {"_id":"62b1f492ff69395b30a03169","name":"Yamba Surfboard-93","category":"gear-surf-surfboards","quantity":20,"sale":false}

indexResult: "name_1"

1 {"_id":"62b1f47dacbf04e86c8abf25","name":"Yamba Surfboard-11","category":"gear-surf-surfboards","quantity":20,"sale":false}
done

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

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

Azure CLI

Используйте команду az group delete, чтобы удалить группу ресурсов.

az group delete --name $resourceGroupName

PowerShell

Используйте командлет Remove-AzResourceGroup, чтобы удалить группу ресурсов.

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters

Портал

1. На портале Azure перейдите к ранее созданной группе ресурсов.

   Совет

   В этом кратком руководстве рекомендуется использовать имя msdocs-cosmos-javascript-quickstart-rg.

2. Выберите команду Удалить группу ресурсов.

   

3. В диалоговом окне Вы действительно хотите удалить введите имя группы ресурсов и выберите Удалить.

   

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

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

Перенос MongoDB в Azure Cosmos DB для MongoDB в автономном режиме