NoSQL 用 API の Azure Cosmos DB Node.js SDK: リリース ノートとリソース

適用対象: NoSQL

• .NET SDK v3
• .NET SDK v2
• .NET Core SDK v2
• .NET Change Feed SDK v2
• Node.js
• Java SDK v4
• Sync Java SDK v2
• Async Java SDK v2
• Spring Data v2
• Spring Data v3
• Spring Data v5
• Python
• Go
• REST
• REST リソース プロバイダー
• SQL
• Bulk Executor - .NET v2
• Bulk Executor - Java

リソース	Link
SDK のダウンロード	@azure/cosmos
API ドキュメント	JavaScript SDK リファレンス ドキュメント
SDK のインストール手順	npm install @azure/cosmos
SDK への参加	azure-sdk-for-js リポジトリの参加ガイド
サンプル	Node.js コード サンプル
概要チュートリアル	JavaScript SDK の開始
Web アプリ チュートリアル	Azure Cosmos DB を使用した Node.js Web アプリケーションの作成
現在サポートされている Node.js プラットフォーム	Node.js の LTS バージョン

リリース ノート

リリース履歴は azure-sdk-for-js リポジトリで管理されています。リリースの詳細なリストについては、changelog ファイルを参照してください。

破壊的変更のための移行ガイド

以前のバージョンの SDK を使用している場合は、3.0 バージョンへの移行をお勧めします。 このセクションでは、このバージョンで得られる機能強化と、3.0 バージョンで行われたバグ修正について詳しく説明します。

強化されたクライアント コンストラクター オプション

コンストラクター オプションが簡略化されました。

• masterKey はキーの名前が変更され、最上位レベルに移動されました
• 以前は 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

V2 には、クエリからの結果を反復処理または取得する方法が数多くありました。 v3 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 サービスでは、以前に固定コンテナーとして作成されたものも含め、すべてのコンテナー上でパーティション キーがサポートされるようになりました。 v3 SDK は、この変更を実装する最新の 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 オブジェクトがスローされていました。

新機能

ユーザーが取り消し可能な要求

内部でのフェッチへの移行により、ブラウザーの AbortController API を使用して、ユーザーが取り消し可能な操作をサポートできます。 複数の要求が進行中の可能性がある操作 (クロス パーティション クエリなど) の場合、操作に対するすべての要求が取り消されます。 最新ブラウザーのユーザーには、既に AbortController があります。 Node.js ユーザーはポリフィル ライブラリを使用する必要があります

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

db/コンテナー作成操作の一環としてのスループットの設定

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

@azure/cosmos-sign

ヘッダー トークンの生成が新しいライブラリ @azure/cosmos-sign に分割されました。 Azure Cosmos DB REST API を直接呼び出すすべてのユーザーは、これを使用して、内部の @azure/cosmos を呼び出したのと同じコードを使用してヘッダーに署名できます。

生成された ID の UUID

v2 には、項目 ID を生成するためのカスタム コードがありました。 既知の管理されたコミュニティ ライブラリ uuid に切り替えました。

Connection strings

Azure portal からコピーした接続文字列を渡すことができるようになりました。

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()

ブラウザー エクスペリエンスの向上

ブラウザー内で v2 SDK を使用することはできましたが、理想的なエクスペリエンスではありませんでした。 いくつかの Node.js 組み込みライブラリをポリフィルし、webpack やパーセルなどのバンドラーを使用する必要がありました。 v3 SDK を使用すると、ブラウザー ユーザーがすぐに利用できるエクスペリエンスが大幅に向上します。

• 要求の内部構造を fetch に置き換えました (#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)
• CI ビルドのための Azure Pipelines YAML (#298)

リリース日と提供終了日

Microsoft は、新しい/サポートされるバージョンに速やかに移行する目的で、SDK の提供終了を少なくともその 12 か月前に通知します。 新しい機能と最適化は現在の SDK にのみ追加されます。そのため、常に可能な限り最新の SDK バージョンにアップグレードすることをお勧めします。 詳細については、Microsoft の SDK サポート ポリシーに関するページを参照してください。

Version	リリース日	提供終了日
v3	2019 年 6 月 28 日	---
v2	2018 年 9 月 24 日	2021 年 9 月 24 日
v1	2015 年 4 月 8 日	2020 年 8 月 30 日

よく寄せられる質問

SDK の提供終了はどのような方法で通知されますか?

サポートされる SDK に速やかに移行できるように、提供終了となる SDK のサポート終了は 12 か月前に通知されます。 さらに、Azure portal、Azure の更新情報、担当サービス管理者への直接連絡など、さまざまな連絡手段で通知します。

その 12 か月間、提供終了予定の Azure Cosmos DB SDK でアプリケーションを作成できますか?

はい。12 か月の通知期間中も、提供終了予定の Azure Cosmos DB SDK でアプリケーションを作成、デプロイ、変更することができます。 この 12 か月の通知期間中、適宜、新しくサポートされるバージョンの Azure Cosmos DB SDK に移行することが推奨されます。

提供終了日以降、サポートされていない Azure Cosmos DB SDK を使用するアプリケーションはどうなりますか?

提供終了日以降、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 のサービス ページを参照してください。