пакет SDK Azure Cosmos DB Node.js для API для NoSQL: заметки о выпуске и ресурсы

  • Применяется к: ✅ NoSQL
Resource Link
Скачивание пакета SDK @azure/cosmos
Документация по API Справочная документация по пакету SDK для JavaScript
Инструкции по установке пакета SDK npm install @azure/cosmos
Участие в разработке пакета SDK руководство по Contributing для репозитория azure-sdk-for-js
Руководство по началу работы Приступая к работе с пакетом SDK для JavaScript
Руководство по веб-приложениям Build веб-приложение Node.js с помощью Azure Cosmos DB
Поддерживаемые в настоящее время платформы Node.js Версии Node.js LTS

Примечания к релизу

Журнал выпусков хранится в репозитории azure-sdk-for-js, чтобы получить подробный список выпусков, см. в файле changelog.

Рекомендации по миграции для критических изменений

Если у вас более старая версия SDK, мы рекомендуем обновить ее до версии 3.0. В этом разделе описаны улучшения и исправления ошибок, которые вы получите в новой версии 3.0.

Улучшены параметры конструктора клиента

Упрощены параметры конструктора:

  • masterKey переименован в key и перемещен на верхний уровень
  • Свойства, которые ранее находились в разделе options.auth, перемещены на верхний уровень
// v2
const client = new CosmosClient({
    endpoint: "https://your-database.cosmos.azure.com",
    auth: {
        masterKey: "your-primary-key"
    }
})

// v3
const client = new CosmosClient({
    endpoint: "https://your-database.cosmos.azure.com",
    key: "your-primary-key"
})

Упрощен API итератора запросов

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

  • Удалены iterator.next() и iterator.current(). fetchNext() используется для получения страниц результатов.
  • Удален iterator.forEach(). Вместо него используются асинхронные итераторы.
  • iterator.executeNext() переименован в iterator.fetchNext()
  • iterator.toArray() переименован в iterator.fetchAll()
  • Страницы теперь являются правильными объектами ответа вместо простых объектов JS
  • const container = client.database(dbId).container(containerId)
// v2
container.items.query('SELECT * from c').toArray()
container.items.query('SELECT * from c').executeNext()
container.items.query('SELECT * from c').forEach(({ body: item }) => { console.log(item.id) })

// v3
container.items.query('SELECT * from c').fetchAll()
container.items.query('SELECT * from c').fetchNext()
for await(const { result: item } in client.databases.readAll().getAsyncIterator()) {
    console.log(item.id)
}

Фиксированные контейнеры теперь секционированы

Служба Azure Cosmos DB теперь поддерживает ключи секций для всех контейнеров, включая те, которые ранее были созданы в качестве фиксированных контейнеров. Пакет SDK версии 3 обновляется до последней версии API, реализующей это изменение, но не нарушается. Если ключ секции не предоставляется для операций, по умолчанию используется системный ключ, который работает со всеми существующими контейнерами и документами.

Из хранимых процедур удалена upsert

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

Операции чтения элементов не будут вызываться на 404

const container = client.database(dbId).container(containerId)

// v2
try {
    container.items.read(id, undefined)
} catch (e) {
    if (e.code === 404) { console.log('item not found') }
}

// v3
const { result: item }  = container.items.read(id, undefined)
if (item === undefined) { console.log('item not found') }

Операции записи в нескольких регионах по умолчанию

Пакет SDK будет записываться в несколько регионов по умолчанию, если ваша конфигурация Azure Cosmos DB поддерживает ее. Ранее это было необязательно.

Правильные объекты ошибок

Неудачные запросы теперь вызывают правильную ошибку или подклассы ошибки. Ранее они вызывали простые объекты JS.

Новые возможности

Запросы, отменяемые пользователем

Перемещение для внутренней выборки позволяет использовать API AbortController браузера для поддержки операций, отменяемых пользователем. Для операций, в которых потенциально выполняются несколько запросов (например, запросы между разделами), будут отменены сразу все запросы этой операции. Пользователям современных браузеров уже будет доступен API AbortController. Node.js пользователям необходимо использовать библиотеку Polyfill

 const controller = new AbortController()
 const {result: item} = await items.query('SELECT * from c', { abortSignal: controller.signal});
 controller.abort()

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

const { database }  = client.databases.create({ id: 'my-database', throughput: 10000 })
database.containers.create({ id: 'my-container', throughput: 10000 })

@azure/cosmos-sign

Операция создания маркера заголовка была разделена на новую библиотеку @azure/cosmos-sign. Любой пользователь, вызывающий REST API Azure Cosmos DB, может использовать это для подписывания заголовков с помощью того же кода, который мы вызываем внутри @azure/cosmos.

UUID для созданных идентификаторов

В версии 2 имеется настраиваемый код для создания идентификаторов элементов. Мы теперь используем хорошо известный и обслуживаемый идентификатор UUID библиотеки сообщества.

Строки подключения

Теперь можно передать строка подключения, скопированный на портале Azure:

const client = new CosmosClient("AccountEndpoint=https://test-account.documents.azure.com:443/;AccountKey=c213asdasdefgdfgrtweaYPpgoeCsHbpRTHhxuMsTaw==;")
Add DISTINCT and LIMIT/OFFSET queries (#306)
 const { results } = await items.query('SELECT DISTINCT VALUE r.name FROM ROOT').fetchAll()
 const { results } = await items.query('SELECT * FROM root r OFFSET 1 LIMIT 2').fetchAll()

Улучшенная работа с браузером

Хотя было возможно использовать пакет SDK версии 2 в браузере, он не был идеальным интерфейсом. Необходимо было заполнить несколько встроенных библиотек Node.js и использовать такие пакеты, как Webpack или Parcel. Пакет SDK версии 3 делает работу с браузером более удобной для пользователей.

  • Замена внутренних компонентов запроса выборкой (№ 245)
  • Удаление использования буфера (№ 330)
  • Удаление встроенного использования узла универсальными пакетами и интерфейсами API (№ 328)
  • Переключение на node-abort-controller (№ 294)

Исправленные ошибки

  • Исправление чтения предложения и возврат тестов предложения (№ 224)
  • Исправление EnableEndpointDiscovery (№ 207)
  • Исправление отсутствующих RU для результатов разбивки на страницы (№ 360)
  • Расширение типа параметра запроса SQL (№ 346)
  • Добавление ttl в ItemDefinition (№ 341)
  • Исправление метрик запроса CP (№ 311)
  • Добавление activityId в FeedResponse (№ 293)
  • Переключение типа _ts со строкового на числовой (№ 252)(№ 295)
  • Исправление агрегирования запросов оплаты (№ 289)
  • Разрешены пустые значения ключей разделов строки (№ 277)
  • Добавление строки в тип запроса конфликта (№ 237)
  • Добавление uniqueKeyPolicy в контейнер (№ 234)

Системы проектирования

Не всегда самые заметные изменения, однако они помогают нашей команде быстрее поставлять более эффективный код.

  • Использование свертки для рабочих сборок (№ 104)
  • Обновление до TypeScript 3.5 (№ 327)
  • Преобразование в ссылки проекта TS. Извлечение тестовой папки (№ 270)
  • Включение noUnusedLocals и noUnusedParameters (№ 275)
  • Azure Pipelines YAML для сборок CI (#298)

Даты выпуска и выбытия

Microsoft предоставляет уведомление по крайней мере 12 месяцев заранее после выхода пакета SDK, чтобы сгладить переход на более новую или поддерживаемую версию. Новые функции и функции и оптимизации добавляются только в текущий пакет SDK, поэтому рекомендуется всегда обновлять последнюю версию пакета SDK как можно раньше. Дополнительные сведения см. в политике служба поддержки Майкрософт для пакетов SDK.

Version Дата выпуска Дата выхода на пенсию
версия 3 28 июня 2019 г. ---
версия 2 24 сентября 2018 г. 24 сентября 2021 г.
версия 1 8 апреля 2015 г. 30 августа 2020 г.

FAQ

Как меня уведомят о прекращении поддержки пакета SDK?

Microsoft предоставьте предварительное уведомление 12 месяцев до окончания поддержки пакета SDK для выхода на пенсию, чтобы упростить переход на поддерживаемый пакет SDK. Мы уведомим вас через различные каналы коммуникации: портал Azure, обновления Azure и прямой обмен данными с назначенными администраторами служб.

Can I author application by using a to-be-retired Azure Cosmos DB SDK в течение 12-месячного периода?

Да, вы сможете создавать, развертывать и изменять приложения с помощью пакета SDK Azure Cosmos DB to-beв течение 12-месячного периода уведомления. Рекомендуется перейти на более новую поддерживаемую версию пакета SDK Azure Cosmos DB в течение 12-месячного периода уведомления.

После даты выхода на пенсию приложения, использующие неподдерживаемый пакет SDK для Azure Cosmos DB?

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

Какие версии пакета SDK получат последние функции и обновления?

Новые функции и обновления получит только последняя дополнительная версия последней основной поддерживаемой версии пакета SDK. Мы рекомендуем всегда работать с последней версией, чтобы вы имели доступ к новым функциям, улучшениям производительности и исправлениям ошибок. Если вы используете старую, не удаляемую версию пакета SDK, ваши запросы на Azure Cosmos DB по-прежнему будут работать, но у вас нет доступа к новым возможностям.

Что делать, если не удается обновить приложение до даты прекращения поддержки?

Рекомендуется как можно раньше выполнить обновление до последней версии SDK. После уведомления о том, что поддержка пакета SDK будет прекращена, у вас будет 12 месяцев на обновление приложения. Если вы не сможете обновиться по дате выхода на пенсию, запросы, отправленные из устаревших версий пакета SDK, будут по-прежнему обслуживаться Azure Cosmos DB, поэтому запущенные приложения будут продолжать функционировать. Но Azure Cosmos DB больше не исправлять ошибки, добавлять новые функции или предоставлять поддержку устаревших версий пакета SDK.

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

Как запросить добавление компонентов в пакет SDK или соединитель?

Новые функции не всегда добавляются во все пакеты SDK или соединители сразу. Если вам хотелось бы добавить функцию, которая в настоящее время не поддерживается, напишите об этом на нашем форуме сообщества.

См. также

Дополнительные сведения о Azure Cosmos DB см. на странице службы Microsoft Azure Cosmos DB.

  • Last updated on