Начало работы с Azure Cosmos DB для NoSQL с помощью JavaScript

  • Статья

ОБЛАСТЬ ПРИМЕНЕНИЯ: NoSQL

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

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

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

Настройка локального проекта

  1. Создайте каталог для проекта JavaScript в оболочке Bash.

    mkdir cosmos-db-nosql-javascript-samples && cd ./cosmos-db-nosql-javascript-samples

  2. Создайте новое приложение JavaScript с помощью npm init команды с шаблоном консоли .

    npm init -y

  3. Установите необходимую зависимость для пакета SDK JavaScript для Azure Cosmos DB для NoSQL.

    npm install @azure/cosmos

Подключение в Azure Cosmos DB для NoSQL

Чтобы подключиться к API для NoSQL Azure Cosmos DB, создайте экземпляр CosmosClient класса. Этот класс является начальной точкой для выполнения всех операций с базами данных. Существует три основных способа подключения к учетной записи API для NoSQL с помощью класса CosmosClient :

Подключение с помощью конечной точки и ключа

Наиболее распространенный конструктор для CosmosClient имеет два параметра:

Параметр Пример значения Description
accountEndpoint Переменная среды COSMOS_ENDPOINT. API для конечной точки NoSQL, используемой для всех запросов
authKeyOrResourceToken Переменная среды COSMOS_KEY. Ключ учетной записи или маркер ресурса для использования при проверке подлинности

Получение конечной точки и ключа учетной записи

  1. Создайте переменную оболочки для resourceGroupName.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-javascript-howto-rg"

  2. Используйте команду az cosmosdb list, чтобы получить имя первой учетной записи Azure Cosmos DB в группе ресурсов и сохранить его в переменной оболочки accountName.

    # Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

  3. URI конечной точки NoSQL для учетной записи с помощью az cosmosdb show команды.

    az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "documentEndpoint"

  4. Найдите PRIMARY KEY в списке ключей для учетной записи с помощью команды az-cosmosdb-keys-list.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

  5. Запишите значения URI и PRIMARY KEY. Эти учетные данные понадобятся позже.

Чтобы использовать значения URI и PRIMARY KEY в коде, сохраните их в новых переменных среды на локальном компьютере под управлением приложения.

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"

Создание CosmosClient с конечной точкой и ключом учетной записи

Создайте новый экземпляр класса CosmosClient с переменными среды COSMOS_ENDPOINT и COSMOS_KEY в качестве параметров.

const client = new CosmosClient({ endpoint, key });

Подключение с использованием строки подключения

Другой конструктор для CosmosClient содержит только один параметр:

Параметр Пример значения Description
accountEndpoint Переменная среды COSMOS_ENDPOINT. API для конечной точки NoSQL, используемой для всех запросов
connectionString Переменная среды COSMOS_CONNECTION_STRING. строка Подключение ion к учетной записи API для NoSQL

Получение строки подключения к учетной записи

  1. Используйте команду az cosmosdb list, чтобы получить имя первой учетной записи Azure Cosmos DB в группе ресурсов и сохранить его в переменной оболочки accountName.

    # Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

  2. Найдите PRIMARY CONNECTION STRING в списке строк подключения для учетной записи с помощью команды az-cosmosdb-keys-list.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "connection-strings" \
    --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"

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

$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"

Создание CosmosClient с помощью строки подключения

Создайте новый экземпляр класса CosmosClient с переменной среды COSMOS_CONNECTION_STRING в качестве единственного параметра.

// New instance of CosmosClient class using a connection string
const cosmosClient = new CosmosClient(process.env.COSMOS_CONNECTION_STRING);

Подключение с помощью платформа удостоверений Майкрософт

Чтобы подключиться к учетной записи API для NoSQL с помощью платформа удостоверений Майкрософт и идентификатора Microsoft Entra, используйте субъект безопасности. Точный тип субъекта зависит от того, где размещается код приложения. Приведенная ниже таблица служит кратким справочным руководством.

Место выполнения приложения Субъект безопасности
Локальный компьютер (разработка и тестирование) Удостоверение пользователя или субъект-служба
Azure Управляемое удостоверение
Серверы или клиенты вне Azure Субъект-служба

Импорт @azure/identity

Пакет npm @azure/identity содержит основные функции проверки подлинности, общие для всех библиотек пакета SDK Azure.

  1. Импортируйте пакет npm @azure/identity с помощью npm install команды.

    npm install @azure/identity

  2. В редакторе кода добавьте зависимости.

    const { DefaultAzureCredential } = require("@azure/identity");

Создание CosmosClient с реализацией учетных данных по умолчанию

Если вы тестируете на локальном компьютере или приложение будет выполняться в службах Azure с прямой поддержкой управляемых удостоверений, получите маркер OAuth, создав экземпляр DefaultAzureCredential. Затем создайте новый экземпляр класса CosmosClient с COSMOS_ENDPOINT переменной среды и объектом TokenCredential в качестве параметров.

const { CosmosClient } = require("@azure/cosmos");
const { DefaultAzureCredential } = require("@azure/identity");

const credential = new DefaultAzureCredential();

const cosmosClient = new CosmosClient({ 
    endpoint, 
    aadCredentials: credential
});

Создание CosmosClient с пользовательской реализацией учетных данных

Если вы планируете развернуть приложение из Azure, вы можете получить маркер OAuth с помощью других классов в клиентской библиотеке @azure/удостоверений для JavaScript. Эти другие классы также являются производными от класса TokenCredential.

В данном примере мы создадим экземпляр ClientSecretCredential с помощью идентификаторов клиента и арендатора, а также секрета клиента.

При регистрации приложения в Microsoft Entra ID можно получить идентификатор клиента, идентификатор клиента и секрет клиента. Дополнительные сведения о регистрации приложений Microsoft Entra см. в разделе "Регистрация приложения с помощью платформа удостоверений Майкрософт".

Создайте новый экземпляр класса CosmosClient с переменной среды COSMOS_ENDPOINT и объектом TokenCredential в качестве параметров.

const { CosmosClient } = require("@azure/cosmos");
const { DefaultAzureCredential } = require("@azure/identity");

const credential = new ClientSecretCredential(
    tenantId: process.env.AAD_TENANT_ID,
    clientId: process.env.AAD_CLIENT_ID,
    clientSecret: process.env.AAD_CLIENT_SECRET
);

const cosmosClient = new CosmosClient({ 
    endpoint, 
    aadCredentials: credential
});

Сборка приложения

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

  • Учетная запись API для NoSQL, которая является уникальным пространством имен верхнего уровня для данных Azure Cosmos DB.

  • Базы данных, которые упорядочивают контейнеры в учетной записи.

  • Контейнеры, содержащие набор отдельных элементов в базе данных.

  • Элементы, представляющие документ JSON в контейнере.

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

Diagram of the Azure Cosmos DB hierarchy including accounts, databases, containers, and items.

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

Класс Description
CosmosClient Этот класс является логическим представлением службы Azure Cosmos DB на стороне клиента. Этот клиентский объект позволяет настраивать и выполнять запросы к службе.
Database Этот класс является ссылкой на базу данных, которая может еще не существовать в службе. База данных проверяется на стороне сервера при попытке доступа к ней или выполнении операции с ней.
Container Этот класс представляет собой ссылку на контейнер, который тоже может еще не существовать в службе. Контейнер проверяется на стороне сервера при попытке работы с ним.

Сведения об использовании каждого из этих классов для создания приложения приведены в следующих руководствах.

Руководство Description
Создание базы данных Создание баз данных
Создание контейнера Создание контейнеров
Создание и чтение элемента Точечное чтение определенного элемента
Запрос элементов Запрос нескольких элементов

См. также

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

Теперь, когда вы подключились к учетной записи API для NoSQL, используйте следующее руководство для создания баз данных и управления ими.

Создание базы данных в Azure Cosmos DB для NoSQL с помощью JavaScript