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

リリース ノート

リリース履歴は 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 の削除

以前は、パーティション分割されていないコレクションに対してアップサートが許可されていましたが、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') }

既定のマルチリージョンの書き込み

Azure Cosmos DB構成でサポートされている場合、SDK は既定で複数のリージョンに書き込まれるようになります。 これは、以前はオプトイン動作でした。

適切なエラー オブジェクト

失敗した要求では、適切なエラーまたはエラーのサブクラスがスローされるようになりました。 以前は、プレーン JS オブジェクトがスローされていました。

新機能

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

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

接続文字列

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

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

ブラウザー内で 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 ビルドの YAML のAzure Pipelines (#298)

リリース日と提供終了日

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

FAQ

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

Microsoftは、サポート対象の SDK へのスムーズな移行を容易にするために、廃止された SDK のサポートが終了する前に 12 か月前に通知します。 Azure ポータル、Azureの更新、割り当てられたサービス管理者への直接の通信など、さまざまな通信チャネルを通じて通知されます。

12 か月の期間中に、to-be-retired Azure Cosmos DB SDK を使用してアプリケーションを作成できますか

はい。12 か月の通知期間中に、to-be-retired 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 サービス のページを参照してください。