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

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

Заметки о выпуске

История выпусков ведется в репозитории azure-sdk-for-js. Подробный список выпусков см. в файле журнала изменений.

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

Если у вас более старая версия 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 потребуется использовать библиотеку с полизаполнением

 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)

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

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

Вопросы и ответы

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

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

Могу ли я во время этого периода в 12 месяцев создавать приложения, используя пакет SDK для Azure Cosmos DB, поддержка которого будет прекращена?

Да, в течение 12-месячного периода уведомления вы сможете разрабатывать, развертывать и изменять приложения с помощью пакета SDK для Azure Cosmos DB, поддержка которого будет прекращена. Мы рекомендуем при удобной возможности перейти на новую поддерживаемую версию Azure Cosmos DB пакета SDK в течение 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 .