Краткое руководство: клиентская библиотека для Azure Cosmos DB для Apache Cassandra Node.js

Применимо к: ✅ Apache Cassanda

Начните работу с клиентской библиотекой Apache Cassandra для Azure Cosmos DB Node.js для сохранения, управления и выполнения запросов к неструктурированным данным. Выполните действия, описанные в этом руководстве, чтобы создать новую учетную запись, установить клиентскую библиотеку Node.js, подключиться к учетной записи, выполнить типичные операции и запросить результаты выборки данных.

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

Предпосылки

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

Последняя версия Azure CLI в Azure Cloud Shell.
- Если вы предпочитаете локально запускать справочные команды CLI, войдите в Azure CLI с помощью az login команды.

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

Настройка

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

Создать аккаунт

Сначала создайте API для учетной записи Apache Cassandra. После создания учетной записи создайте пространство ключей и ресурсы для таблицы.

Azure CLI
Портал Azure

Если у вас еще нет целевой группы ресурсов, используйте az group create команду для создания новой группы ресурсов в подписке.
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```
az cosmosdb create Используйте команду для создания новой учетной записи Azure Cosmos DB для Apache Cassandra с параметрами по умолчанию.
```
az cosmosdb create \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --locations "regionName=<location>" \
    --capabilities "EnableCassandra"
```

Создайте новое пространство ключей с именем az cosmosdb cassandra keyspace create с помощью cosmicworks.

az cosmosdb cassandra keyspace create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --name "cosmicworks"

Создайте новый объект JSON для представления схемы с помощью команды Bash с несколькими строками. Затем используйте az cosmosdb cassandra table create команду, чтобы создать новую таблицу с именем products.

schemaJson=$(cat <<EOF
{
  "columns": [
    {
      "name": "id",
      "type": "text"
    },
    {
      "name": "name",
      "type": "text"
    },
    {
      "name": "category",
      "type": "text"
    },
    {
      "name": "quantity",
      "type": "int"
    },
    {
      "name": "price",
      "type": "decimal"
    },
    {
      "name": "clearance",
      "type": "boolean"
    }
  ],
  "partitionKeys": [
    {
      "name": "id"
    }
  ]
}
EOF
)

az cosmosdb cassandra table create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --keyspace-name "cosmicworks" \
    --name "product" \
    --schema "$schemaJson"

Войдите на портал Azure (https://portal.azure.com).
Введите Azure Cosmos DB в глобальной строке поиска.
В службах выберите Azure Cosmos DB.
В области Azure Cosmos DB выберите "Создать", а затем Azure Cosmos DB для Apache Cassandra на вкладке "Другие ".
Выберите тип учетной записи учетная запись базы данных единицы запроса (RU).

В области "Основные сведения" настройте следующие параметры и нажмите кнопку "Проверить и создать".

	Ценность
Тип рабочей нагрузки	Обучение
Подписка	Выберите подписку Azure.
Группа ресурсов	Создание новой группы ресурсов или выбор существующей группы ресурсов
Имя аккаунта	Укажите глобально уникальное имя
Зоны доступности	Отключить
Местоположение	Выбор поддерживаемого региона Azure для подписки

Подсказка

Вы можете оставить любые не указанные параметры значениями по умолчанию. Вы также можете настроить учетную запись, чтобы ограничить общую пропускную способность учетной записи до 1000 единиц запросов в секунду (ЕЗ/с) или включить бесплатный уровень для минимизации затрат.

На панели "Проверка и создание" дождитесь успешной проверки учетной записи и нажмите кнопку "Создать".
Портал автоматически переходит в область развертывания. Дождитесь завершения развертывания.
После завершения развертывания выберите "Перейти к ресурсу" , чтобы перейти к новой учетной записи API для Apache Cassandra.
В меню ресурсов выберите параметр Обозревателя данных .
В обозревателе данных выберите +Создать таблицу.

В диалоговом окне "Добавить таблицу " настройте следующие параметры и нажмите кнопку "ОК".

	Ценность
Пространство ключей	Создать
Имя пространства ключей	`cosmicworks`
Имя таблицы	`product`
Схема таблицы	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

Подсказка

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

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

Теперь получите пароль для клиентской библиотеки для создания подключения к недавно созданной учетной записи.

Azure CLI
Портал Azure

Используйте az cosmosdb show, чтобы получить точку контакта и имя пользователя для учетной записи.
```
az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "{username:name,contactPoint:documentEndpoint}"
```
Запишите значение свойств contactPoint и username из вывода предыдущих команд. Эти свойства представляют собой контактную точку и имя пользователя , которое вы используете далее в этом руководстве для подключения к учетной записи с библиотекой.

Используйте az cosmosdb keys list для получения ключей для учетной записи.

az cosmosdb keys list \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --type "keys"

Запишите значение primaryMasterKey свойства из выходных данных предыдущих команд. Это значение свойства — это пароль , который вы используете далее в этом руководстве для подключения к учетной записи с библиотекой.

Подготовка среды разработки

Затем настройте среду разработки с новым проектом и клиентской библиотекой. Этот шаг является последним обязательным предварительным условием, прежде чем перейти к остальной части этого руководства.

Запустите пустую папку.
Инициализация нового модуля.
```
npm init es6 --yes
```
Установите пакет cassandra-driver с помощью менеджера пакетов Node (npm).
```
npm install --save cassandra-driver
```
Создайте файл index.js .

Начните в пустом каталоге.
Инициализация нового модуля.
```
npm init es6 --yes
```
Установите пакет typescript с помощью менеджера пакетов Node (npm).
```
npm install --save-dev typescript
```
Установите пакет tsx из npm.
```
npm install --save-dev tsx
```
Установите пакет cassandra-driver из npm.
```
npm install --save cassandra-driver
```
Инициализация проекта TypeScript с помощью компилятора (tsc).
```
npx tsc --init --target es2017 --module es2022 --moduleResolution nodenext
```
Создайте файл index.ts .

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

	Описание
`Client`	Представляет определенное подключение к кластеру
`Mapper`	Клиент языка запросов Cassandra (CQL), используемый для выполнения запросов

Проверка подлинности клиента

Начните с проверки подлинности клиента с помощью учетных данных, собранных ранее в этом руководстве.

Откройте файлindex.js в интегрированной среде разработки (IDE).
Импортируйте следующие типы из cassandra-driver модуля:
- cassandra
- cassandra.Client
- cassandra.mapping.Mapper
- cassandra.auth.PlainTextAuthProvider
```
import cassandra from 'cassandra-driver';

const { Client } = cassandra;
const { Mapper } = cassandra.mapping;
const { PlainTextAuthProvider } = cassandra.auth;
```
Создайте строковые постоянные переменные для учетных данных, собранных ранее в этом руководстве. Присвойте переменным usernamepasswordи contactPoint.
```
const username = '<username>';
const password = '<password>';
const contactPoint = '<contact-point>';
```
Создайте другую строковую переменную для региона, в котором вы создали учетную запись Azure Cosmos DB для Apache Cassandra. Присвойте этой переменной regionимя.
```
const region = '<azure-region>';
```
Создайте объект PlainTextAuthProvider с учетными данными, указанными на предыдущих шагах.
```
let authProvider = new PlainTextAuthProvider(
    username,
    password
);
```

Client Создайте объект с помощью учетных данных и переменных конфигурации, созданных на предыдущих шагах.

let client = new Client({
    contactPoints: [`${contactPoint}:10350`],
    authProvider: authProvider,
    localDataCenter: region,
    sslOptions: {
        secureProtocol: 'TLSv1_2_method'
    },
});

Асинхронное подключение к кластеру.
```
await client.connect();
```
Создайте новый mapper, ориентированный на пространство ключей cosmicworks и таблицу product. Назовите mapper Product.
```
const mapper = new Mapper(client, {
    models: {
        'Product': {
            tables: ['product'],
            keyspace: 'cosmicworks'
        }
    }
});
```
Создайте экземпляр маппера с использованием функции forModel и имени маппера Product.
```
const productMapper = mapper.forModel('Product');
```

Откройте файл index.ts в интегрированной среде разработки (IDE).
Импортируйте следующие типы из cassandra-driver модуля:
- cassandra.auth
- cassandra.mapping
- cassandra.types
- cassandra.Client
- cassandra.ClientOptions
- cassandra.mapping.Mapper
- cassandra.auth.PlainTextAuthProvider
```
import { auth, mapping, types, Client, ClientOptions } from 'cassandra-driver';

const { Mapper } = mapping;
const { PlainTextAuthProvider } = auth;
```
Создайте строковые постоянные переменные для учетных данных, собранных ранее в этом руководстве. Присвойте переменным usernamepasswordи contactPoint.
```
const username: string = '<username>';
const password: string = '<password>';
const contactPoint: string = '<contact-point>';
```
Создайте другую строковую переменную для региона, в котором вы создали учетную запись Azure Cosmos DB для Apache Cassandra. Присвойте этой переменной regionимя.
```
const region: string = '<azure-region>';
```
Создайте объект PlainTextAuthProvider с учетными данными, указанными на предыдущих шагах.
```
let authProvider = new PlainTextAuthProvider(
    username,
    password
);
```
Создайте анонимный объект с параметрами, обеспечивающими использование протокола TLS 1.2.
```
let sslOptions = {
    secureProtocol: 'TLSv1_2_method'
};
```
ClientOptions Создайте объект с помощью учетных данных и переменных конфигурации, созданных на предыдущих шагах.
```
let clientOptions: ClientOptions = {
    contactPoints: [`${contactPoint}:10350`],
    authProvider: authProvider,
    localDataCenter: region,
    sslOptions: sslOptions
};
```
Client Создайте объект с помощью переменной clientOptions в конструкторе.
```
let client = new Client(clientOptions);
```
Асинхронное подключение к кластеру.
```
await client.connect();
```
Создайте новый mapper, ориентированный на пространство ключей cosmicworks и таблицу product. Назовите mapper Product.
```
const mapper = new Mapper( client, {
    models: {
        'Product': {
            tables: ['product'],
            keyspace: 'cosmicworks'
        }
    }
});
```
Создайте экземпляр маппера с использованием функции forModel и имени маппера Product.
```
const productMapper = mapper.forModel('Product');
```

Предупреждение

Полная проверка уровня транспорта (TLS) отключена в этом руководстве для упрощения проверки подлинности. Для рабочих развертываний полностью включите проверку.

Обновление-вставка данных

Затем переведите новые данные в таблицу. Upserting гарантирует, что данные создаются или заменяются соответствующим образом в зависимости от того, существуют ли те же данные в таблице.

Создайте новый объект в переменной с именем product.

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

Асинхронно вызовите функцию insert, передавая переменную product, созданную на предыдущем шаге.
```
await productMapper.insert(product);
```

Определите новый интерфейс Product с полями, соответствующими таблице, созданной ранее в этом руководстве.

Тип

Id string

Name string

Category string

Quantity int

Price decimal

Clearance bool
```
interface Product {
    id: string;
    name: string;
    category: string;
    quantity: number;
    price: number;
    clearance: boolean;
}
```
Подсказка

В Node.jsможно создать этот тип в другом файле или создать его в конце существующего файла.

	Тип
`Id`	`string`
`Name`	`string`
`Category`	`string`
`Quantity`	`int`
`Price`	`decimal`
`Clearance`	`bool`

Создайте новый объект типа Product. Сохраните объект в переменной с именем product.

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

Асинхронно вызовите функцию insert, передавая переменную product, созданную на предыдущем шаге.
```
await productMapper.insert(product);
```

Чтение данных

Затем считывайте данные, которые ранее были добавлены в таблицу.

Создайте анонимный объект с именем filter. В этом объекте добавьте свойство id с таким же значением, как и продукт, созданный ранее в этом руководстве.
```
const filter = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};
```
get Вызовите функцию объекта mapper, передаваемого filter в переменную. Сохраните результат в переменной под названием matchedProduct.
```
let matchedProduct = await productMapper.get(filter);
```

Создайте анонимный объект с именем filter. В этом объекте добавьте свойство id с таким же значением, как и продукт, созданный ранее в этом руководстве.
```
const filter = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};
```
get Вызовите функцию объекта mapper, передаваемого filter в переменную. Сохраните результат в переменной с именем matchedProduct типа Product.
```
let matchedProduct: Product = await productMapper.get(filter);
```

Запрос данных

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

Создайте новую строковую переменную с именем query, содержащую CQL-запрос, который выбирает элементы с тем же полем category.
```
const query = `
SELECT
    *
FROM
    cosmicworks.product
WHERE
    category = :category
ALLOW FILTERING
`;
```
Создайте анонимный объект с именем params. В этом объекте добавьте свойство category с таким же значением, как и продукт, созданный ранее в этом руководстве.
```
const params = {
    category: 'gear-surf-surfboards'
};
```
Асинхронно вызвать функцию execute, передав в качестве аргументов переменные query и params. Сохраните свойство результата rows в виде переменной с именем matchedProducts.
```
let { rows: matchedProducts } = await client.execute(query, params);
```
Выполните итерацию результатов запроса путем вызова foreach метода в массиве продуктов.
```
matchedProducts.forEach(product => {
    // Do something here with each result
});
```

Создайте новую строковую переменную с именем query, содержащую CQL-запрос, который выбирает элементы с тем же полем category.
```
const query: string = `
SELECT
    *
FROM
    cosmicworks.product
WHERE
    category = :category
ALLOW FILTERING
`;
```
Создайте анонимный объект с именем params. В этом объекте добавьте свойство category с таким же значением, как и продукт, созданный ранее в этом руководстве.
```
const params = {
    category: 'gear-surf-surfboards'
};
```
Асинхронно вызвать функцию execute, передав в качестве аргументов переменные query и params. Сохраните результат в переменной с именем result типа types.ResultSet.
```
let result: types.ResultSet = await client.execute(query, params);
```
Сохраните свойство результата rows в виде переменной matchedProductsтипаProduct[].
```
let matchedProducts: Product[] = result.rows;
```
Выполните итерацию результатов запроса путем вызова foreach метода в массиве продуктов.
```
matchedProducts.forEach((product: Product) => {
    // Do something here with each result
});
```

Запустите код

Запустите созданное приложение с помощью терминала в каталоге приложения.

node index.js

npx tsx index.ts

Очистите ресурсы

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

Azure CLI
Портал Azure

az cosmosdb delete \
    --resource-group "<resource-group-name>" \
    --name "<account-name>"

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

Обзор Azure Cosmos DB для Apache Cassandra

Обратная связь

Была ли эта страница полезна?

Last updated on 2025-07-21