Быстрый старт: использование Azure Cosmos DB для NoSQL с Azure SDK для Node.js

В этом кратком руководстве описано, как развернуть базовое приложение Azure Cosmos DB для NoSQL с помощью пакета SDK Azure для Node.js. Azure Cosmos DB для NoSQL — это хранилище данных без схемы, позволяющее приложениям хранить неструктурированные данные в облаке. Запросите данные в ваших контейнерах и выполняйте обычные операции с отдельными элементами, используя Azure SDK для Node.js.

Справочная документация по API | Исходный код библиотеки | Пакет (npm) | Azure Developer CLI

Предварительные условия

• Azure Developer CLI
• Docker Desktop
• Node.js 22 или более поздней версии

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

Инициализация проекта

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

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

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

   azd auth login
   

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

   azd init --template cosmos-db-nosql-nodejs-quickstart
   

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

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-адрес консоли для перехода к веб-приложению в браузере. Просмотрите выходные данные запущенного приложения.

Установка клиентской библиотеки

Клиентская библиотека доступна через менеджер пакетов Node в виде пакета @azure/cosmos.

1. Откройте терминал и перейдите в папку /src .

   cd ./src
   

2. Если пакет еще не установлен, установите @azure/cosmos его с помощью npm install.

   npm install --save @azure/cosmos
   

3. Кроме того, установите @azure/identity пакет, если он еще не установлен.

   npm install --save @azure/identity
   

4. Откройте и просмотрите файл src/package.json, чтобы убедиться, что существуют записи azure-cosmos и azure-identity.

Импорт библиотек

import { DefaultAzureCredential } from '@azure/identity';
import { CosmosClient } from '@azure/cosmos';

import { PagedAsyncIterableIterator } from '@azure/core-paging';
import { DefaultAzureCredential, TokenCredential } from '@azure/identity';
import { Container, CosmosClient, Database, FeedResponse, ItemResponse, SqlQuerySpec } from '@azure/cosmos';

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

Примеры кода

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

Пример кода в шаблоне использует базу данных с именем cosmicworks и контейнером products. Контейнер products содержит такие сведения, как имя, категория, количество, уникальный идентификатор и флаг продажи для каждого продукта. Контейнер использует /category свойство в качестве ключа логического раздела.

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

В этом примере создается новый экземпляр CosmosClient типа и выполняется проверка подлинности с помощью экземпляра DefaultAzureCredential .

const credential = new DefaultAzureCredential();

const client = new CosmosClient({
    '<azure-cosmos-db-nosql-account-endpoint>',
    aadCredentials: credential
});

const credential: TokenCredential = new DefaultAzureCredential();

const client = new CosmosClient({
    '<azure-cosmos-db-nosql-account-endpoint>',
    aadCredentials: credential
});

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

Используется client.database для извлечения существующей базы данных с именем cosmicworks.

const database = client.database('cosmicworks');

const database: Database = client.database('cosmicworks');

Возьмите контейнер

Получение существующего products контейнера с помощью database.container.

const container = database.container('products');

const container: Container = database.container('products');

Создание элемента

Создайте новый объект со всеми элементами, которые необходимо сериализовать в JSON. В этом примере тип имеет уникальный идентификатор и поля для категории, имени, количества, цены и продажи. Создайте элемент в контейнере с помощью container.items.upsert. Этот метод "вставляет или обновляет" элемент, фактически заменяя элемент, если он уже существует.

const item = {
    'id': 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    'category': 'gear-surf-surfboards',
    'name': 'Yamba Surfboard',
    'quantity': 12,
    'price': 850.00,
    'clearance': false
};

let response = await container.items.upsert(item);

const item: Product = {
    'id': 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    'category': 'gear-surf-surfboards',
    'name': 'Yamba Surfboard',
    'quantity': 12,
    'price': 850.00,
    'clearance': false
};

let response: ItemResponse<Product> = await container.items.upsert<Product>(item);

Прочитайте элемент

Выполните операцию точечного чтения с помощью полей уникального идентификатора (id) и ключа раздела. Используйте container.item для получения указателя на элемент и item.read, чтобы эффективно извлечь конкретный элемент.

const id = 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb';
const partitionKey = 'gear-surf-surfboards';

let response = await container.item(id, partitionKey).read();
let read_item = response.resource;

const id = 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb';
const partitionKey = 'gear-surf-surfboards';

let response: ItemResponse<Product> = await container.item(id, partitionKey).read<Product>();
let read_item: Product = response.resource!;

Элементы запроса

Выполнение запроса по нескольким элементам в контейнере с помощью container.items.query. Найдите все элементы в указанной категории с помощью этого параметризованного запроса:

SELECT * FROM products p WHERE p.category = @category

Получение всех результатов запроса с помощью query.fetchAll. Прокрутите результаты запроса.

const querySpec = {
    query: 'SELECT * FROM products p WHERE p.category = @category',
    parameters: [
        {
            name: '@category',
            value: 'gear-surf-surfboards'
        }
    ]
};

let response = await container.items.query(querySpec).fetchAll();
for (let item of response.resources) {
    // Do something
}

const querySpec: SqlQuerySpec = {
    query: 'SELECT * FROM products p WHERE p.category = @category',
    parameters: [
        {
            name: '@category',
            value: 'gear-surf-surfboards'
        }
    ]
};

let response: FeedResponse<Product> = await container.items.query<Product>(querySpec).fetchAll();
for (let item of response.resources) {
    // Do something
}

Изучение данных

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

• Выполнение запросов с помощью блокнота или редактора запросов
• Изменение, обновление, создание и удаление элементов
• Импорт массовых данных из других источников
• Управление базами данных и контейнерами

Дополнительные сведения см. в разделе как использовать расширение Visual Studio Code для изучения NoSQL данных в Azure Cosmos DB.

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

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

azd down

Связанный контент

• Краткое руководство по .NET
• Краткое руководство для Java
• Краткое руководство по Python
• Быстрый старт с Go
• Краткое руководство по Rust