Azure Cosmos DB client library for JavaScript - version 4.9.3

/タイプスクリプト

ビルド状態最新の npm バッジを する

Azure Cosmos DBは、ドキュメント、キーバリュー、ワイドカラム、グラフデータベースをサポートする、グローバルに分散されたマルチモデルデータベースサービスです。 このパッケージは、JavaScript/TypeScript アプリケーションが、SQL API データベースおよびデータベースに含まれる JSON ドキュメントと対話することを目的としています。

• Cosmos DB データベースを作成し、その設定を変更する
• JSON ドキュメントのコレクションを格納するコンテナーを作成および変更する
• コンテナー内の項目 (JSON ドキュメント) を作成、読み取り、更新、および削除する
• SQL に似た構文を使用してデータベース内のドキュメントに対してクエリを実行する

主要なリンク:

• パッケージ (npm)
• API リファレンス ドキュメントの
• 製品のドキュメント

はじめ

前提 条件

Azure Subscription and Cosmos DB SQL API Account

このパッケージを使用するには、Azure Subscriptionと、Cosmos DBアカウント(SQL API)が必要です。

もしCosmos DB SQL APIアカウントが必要な場合は、Azure Cloud Shellを使って、以下のAzure CLIコマンドで作成できます:

az cosmosdb create --resource-group <resource-group-name> --name <cosmos-database-account-name>

またはAzure portal

NodeJSの

このパッケージは、LTS バージョン 使用して NodeJS にプレインストールされている npm 経由で配布されます。

CORS

ブラウザー用に開発する必要がある場合は、Cosmos DB アカウント クロスオリジン リソース共有 (CORS) 規則を設定する必要があります。 リンクされたドキュメントの指示に従って、Cosmos DB の新しい CORS ルールを作成します。

このパッケージをインストールする

npm install @azure/cosmos

アカウント資格情報の取得

Cosmos DB アカウント エンドポイントの と キーが必要です。 これらはAzure portalで見つけられるか、下記のAzure CLIスニペットをご利用ください。 スニペットは Bash シェル用に書式設定されています。

az cosmosdb show --resource-group <your-resource-group> --name <your-account-name> --query documentEndpoint --output tsv
az cosmosdb keys list --resource-group <your-resource-group> --name <your-account-name> --query primaryMasterKey --output tsv

CosmosClient のインスタンスを作成する

Cosmos DB との対話は、CosmosClient クラスのインスタンスで始まります

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

わかりやすくするために、key と endpoint をコードに直接含めますが、dotenv や環境変数からの読み込みなどのプロジェクトを使用してソース管理にないファイルから読み込む必要がある可能性があります。

本番環境では、鍵のような秘密はAzure Key Vault

主な概念

CosmosClientを初期化したら、Cosmos DB でプライマリ リソースの種類を操作できます。

• データベース: Cosmos DB アカウントには複数のデータベースを含めることができます。 データベースを作成する際には、そのドキュメントとやり取りする際に使いたいAPIを指定します:SQL、MongoDB、Gremlin、Cassandra、またはAzure Tableです。 Database オブジェクトを使用して、そのコンテナーを管理します。

• コンテナー: コンテナーは JSON ドキュメントのコレクションです。 Container オブジェクトのメソッドを使用して、コンテナー内の項目を作成 (挿入)、読み取り、更新、および削除します。

• 項目: 項目は、コンテナーに格納されている JSON ドキュメントです。 各項目には、コンテナー内の項目を一意に識別する値を持つ id キーを含める必要があります。 idを指定しないと、SDK によって自動的に生成されます。

これらのリソースの詳細については、Working with Azure Cosmos databases, containers and itemssをご覧ください。

例

次のセクションでは、次のような最も一般的な Cosmos DB タスクの一部をカバーするいくつかのコード スニペットを示します。

• データベース を作成する
• コンテナー を作成する
• パーティション キーの使用 の
• 項目 を挿入する
• クエリ ドキュメント
• アイテム を読み取る
• アイテム を削除する
• 階層的パーティション キー を使用してコンテナーで CRUD を する
• 除外された場所の使用

データベースを作成する

CosmosClientを認証したら、アカウント内の任意のリソースを操作できます。 次のコード スニペットでは、NOSQL API データベースが作成されます。

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

コンテナーを作成する

この例では、既定の設定でコンテナーを作成します

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });
const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

パーティション キーの使用

この例では、サポートされているさまざまな種類のパーティション キーを示します。

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

await container.item("id", "1").read(); // string type
await container.item("id", 2).read(); // number type
await container.item("id", true).read(); // boolean type
await container.item("id", {}).read(); // None type
await container.item("id", undefined).read(); // None type
await container.item("id", null).read(); // null type

パーティション キーが 1 つの値で構成されている場合は、リテラル値または配列として指定できます。

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

await container.item("id", "1").read();
await container.item("id", ["1"]).read();

パーティション キーが複数の値で構成されている場合は、配列として指定する必要があります。

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

await container.item("id", ["a", "b"]).read();
await container.item("id", ["a", 2]).read();
await container.item("id", [{}, {}]).read();
await container.item("id", ["a", {}]).read();
await container.item("id", [2, null]).read();

アイテムを挿入する

コンテナーに項目を挿入するには、データを含むオブジェクトを Items.upsertに渡します。 Azure Cosmos DBサービスでは、各アイテムに id キーが必要です。 指定しない場合、SDK によって id が自動的に生成されます。

次の使用例は、コンテナーに複数の項目を挿入します。

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

const cities = [
  { id: "1", name: "Olympia", state: "WA", isCapitol: true },
  { id: "2", name: "Redmond", state: "WA", isCapitol: false },
  { id: "3", name: "Chicago", state: "IL", isCapitol: false },
];
for (const city of cities) {
  await container.items.create(city);
}

アイテムの読み取り

コンテナーから 1 つの項目を読み取る場合は、Item.read使用します。 これは、SQL を使用して idでクエリを実行するよりもコストの低い操作です。

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

await container.item("1", "1").read();

階層パーティション キーを持つコンテナー上の CRUD

階層パーティション キーを使用してコンテナーを作成する

import { CosmosClient, PartitionKeyDefinitionVersion, PartitionKeyKind } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const containerDefinition = {
  id: "Test Container",
  partitionKey: {
    paths: ["/name", "/address/zip"],
    version: PartitionKeyDefinitionVersion.V2,
    kind: PartitionKeyKind.MultiHash,
  },
};
const { container } = await database.containers.createIfNotExists(containerDefinition);

階層パーティション キーが定義された項目を挿入する - ["/name", "/address/zip"]

import { CosmosClient, PartitionKeyDefinitionVersion, PartitionKeyKind } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const containerDefinition = {
  id: "Test Database",
  partitionKey: {
    paths: ["/name", "/address/zip"],
    version: PartitionKeyDefinitionVersion.V2,
    kind: PartitionKeyKind.MultiHash,
  },
};
const { container } = await database.containers.createIfNotExists(containerDefinition);

const item = {
  id: "1",
  name: "foo",
  address: {
    zip: 100,
  },
  active: true,
};
await container.items.create(item);

階層パーティション キーが定義されたコンテナーから 1 つの項目を読み取る方法 - ["/name", "/address/zip"],

import { CosmosClient, PartitionKeyDefinitionVersion, PartitionKeyKind } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const containerDefinition = {
  id: "Test Database",
  partitionKey: {
    paths: ["/name", "/address/zip"],
    version: PartitionKeyDefinitionVersion.V2,
    kind: PartitionKeyKind.MultiHash,
  },
};
const { container } = await database.containers.createIfNotExists(containerDefinition);

await container.item("1", ["foo", 100]).read();

階層パーティション キーが -["/name", "/address/zip"], として定義された階層パーティション キーを持つ項目に対してクエリを実行する

import { CosmosClient, PartitionKeyDefinitionVersion, PartitionKeyKind } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const containerDefinition = {
  id: "Test Database",
  partitionKey: {
    paths: ["/name", "/address/zip"],
    version: PartitionKeyDefinitionVersion.V2,
    kind: PartitionKeyKind.MultiHash,
  },
};
const { container } = await database.containers.createIfNotExists(containerDefinition);

const { resources } = await container.items
  .query("SELECT * from c WHERE c.active = true", {
    partitionKey: ["foo", 100],
  })
  .fetchAll();

アイテムを削除する

コンテナーから項目を削除するには、Item.delete使用します。

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

// Delete the first item returned by the query above
await container.item("1").delete();

データベースのクエリを実行する

Cosmos DB SQL API データベースでは、SQL に似た構文を使用して、Items.query を使用してコンテナー内の項目のクエリを実行できます。

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

const { resources } = await container.items
  .query("SELECT * from c WHERE c.isCapitol = true")
  .fetchAll();

パラメーターとその値を含むオブジェクトを Items.queryに渡して、パラメーター化されたクエリ 実行します。

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

const { resources } = await container.items
  .query({
    query: "SELECT * from c WHERE c.isCapitol = @isCapitol",
    parameters: [{ name: "@isCapitol", value: true }],
  })
  .fetchAll();

注: クエリで継続トークンを使用するには、クエリオプションで enableQueryControl が true に設定されていることを確認しましょう。 これにより、大規模な結果セットをページ化するためのクエリ継続トークンの取得が可能になります。

以下は enableQueryControlで継続トークンを使う例です:

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

const queryIterator = container.items.query("SELECT * from c", {
  maxItemCount: 10,
  enableQueryControl: true,
  forceQueryPlan: true,
});

let pageCount = 0;
while (queryIterator.hasMoreResults()) {
  pageCount++;
  const { resources, continuationToken } = await queryIterator.fetchNext();
  console.log(`Page ${pageCount} has ${resources.length} items`);
  // continuationToken can be saved and used later to resume from where you left off
}

特殊な場合:ORDER BY クエリ

ORDER BYクエリで enableQueryControl を使用する場合、継続トークンの動作には特別な処理が必要であることに注意してください。

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

const queryIterator = container.items.query("SELECT * from c ORDER BY c.id", {
  maxItemCount: 10,
  enableQueryControl: true,
  forceQueryPlan: true,
});

let pageCount = 0;
while (queryIterator.hasMoreResults()) {
  pageCount++;
  const { resources, continuationToken } = await queryIterator.fetchNext();
  if (resources.length > 0) {
    // Process results
    // Safe to use continuationToken after receiving data
    if (continuationToken) {
      // Can persist token for resuming later
    }
  }
}

大事な： ORDER BYクエリで enableQueryControl を使用する場合:

• resources配列やcontinuationTokenは空で、初期呼び出し時には繰り返しundefinedされることがあります
• これはクエリが返事を返す前にパーティション間で結果を統合する必要があるためです
• 継続トークンに頼る前に必ず確認resources.length > 0
• クエリオプションに forceQueryPlan: true を活用することで、パーティション間で一貫したクエリ実行動作を確保し、継続トークンの安定性を高めます

SQL APIを用いてCosmos DBデータベースをクエリする方法については、Query Azure Cosmos DB data with SQL queryをご覧ください。

変更フィード プル モデル

変更フィードは、パーティション キー、フィード範囲、またはコンテナー全体に対してフェッチできます。

変更フィードを処理するには、ChangeFeedPullModelIteratorのインスタンスを作成します。 ChangeFeedPullModelIteratorを最初に作成するときは、変更を読み取るための開始位置と、変更をフェッチするリソース (パーティション キーまたは FeedRange) の両方で構成される、changeFeedStartFrom 内に必要な ChangeFeedIteratorOptions 値を指定する必要があります。 必要に応じて、maxItemCount の ChangeFeedIteratorOptions を使用して、1 ページあたりに受信するアイテムの最大数を設定できます。

注: changeFeedStartFrom 値が指定されていない場合、Now() からコンテナー全体に対して changefeed がフェッチされます。

変更フィードには、次の 4 つの開始位置があります。

• Beginning

import { ChangeFeedStartFrom } from "@azure/cosmos";

const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Beginning(),
};

• Time

import { ChangeFeedStartFrom } from "@azure/cosmos";

const time = new Date("2023/09/11"); // some sample date
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Time(time),
};

• Now

import { ChangeFeedStartFrom } from "@azure/cosmos";

// Signals the iterator to read changefeed from this moment onward.
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Now(),
};

• Continuation

import { ChangeFeedStartFrom } from "@azure/cosmos";

// Signals the iterator to read changefeed from a saved point.
const continuationToken = "some continuation token received from previous request";
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Continuation(continuationToken),
};

パーティション キーの変更フィードをフェッチする例を次に示します。

import {
  CosmosClient,
  PartitionKeyDefinitionVersion,
  PartitionKeyKind,
  ChangeFeedStartFrom,
} from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const containerDefinition = {
  id: "Test Database",
  partitionKey: {
    paths: ["/name", "/address/zip"],
    version: PartitionKeyDefinitionVersion.V2,
    kind: PartitionKeyKind.MultiHash,
  },
};
const { container } = await database.containers.createIfNotExists(containerDefinition);

const partitionKey = "some-partition-Key-value";
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Beginning(partitionKey),
};

const iterator = container.items.getChangeFeedIterator(options);

while (iterator.hasMoreResults) {
  const response = await iterator.readNext();
  // process this response
}

変更フィードは、将来のすべての書き込みと更新を含む項目の無限のリストであるため、hasMoreResults の値は常に true。 変更フィードを読み取ろうとしたときに、新しい変更が使用できない場合は、NotModified 状態の応答を受け取ります。

詳細な使用ガイドラインと変更フィードの例については、こちら 参照してください。

除外された場所の使用

リクエストレベルのexcludedLocationsオプションでは、リクエストの提供から除外すべき1つ以上のAzure領域を指定することができます。 これは、コンプライアンス、待機時間、または可用性の懸念により、ユーザーが特定のリージョンを回避したいシナリオに役立ちます。 設定すると、Cosmos DB は要求を他の使用可能なリージョンにルーティングし、データ所在地とフェールオーバー動作の制御を改善します。

excludedLocations enableEndPointDiscoveryが true に設定されている場合にのみ適用されます。

この例では、除外された場所をサポートするさまざまな API を示しています。

import { CosmosClient, ChangeFeedStartFrom } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

const city = { id: "1", name: "Olympia", state: "WA" };
await container.items.upsert(city, { excludedLocations: ["Test Region"] });

const iterator = container.items.getChangeFeedIterator({
  excludedLocations: ["Test Region"],
  maxItemCount: 1,
  changeFeedStartFrom: ChangeFeedStartFrom.Beginning(),
});

const response = await iterator.readNext();

エラー処理

SDK では、操作中に発生する可能性があるさまざまな種類のエラーが生成されます。

1. ErrorResponse は、操作の応答からエラー コード >=400 が返された場合にスローされます。
2. タイムアウトのために Abort が内部的に呼び出されると、TimeoutError がスローされます。
3. AbortError は、ユーザーが渡したシグナルによって中止が発生した場合にスローされます。
4. RestError は、ネットワークの問題が原因で基になるシステム呼び出しが失敗した場合にスローされます。
5. devDependencies によって生成されたエラー。 例: @azure/identity パッケージは CredentialUnavailableErrorをスローする可能性があります。

ErrorResponse、TimeoutError、AbortError、および RestErrorのエラーを処理する例を次に示します。

import { ErrorResponse, RestError } from "@azure/cosmos";

try {
  // some code
} catch (err) {
  if (err instanceof ErrorResponse) {
    // some specific error handling.
  } else if (err instanceof RestError) {
    // some specific error handling.
  }
  // handle other type of errors in similar way.
  else {
    // for any other error.
  }
}

これらのエラーを適切に処理して、アプリケーションが障害から正常に復旧し、期待どおりに機能し続けられるようにすることが重要です。 これらのエラーとその考えられる解決策の詳細については、こちら 参照してください。

トラブルシューティング

全般

サービスによって返される Cosmos DB エラーと対話する場合は、REST API 要求に対して返されるのと同じ HTTP 状態コードに対応します。

HTTPステータスコード Azure Cosmos DB

競合

たとえば、Cosmos DB データベースで既に使用されている id を使用して項目を作成しようとすると、競合を示す 409 エラーが返されます。 次のスニペットでは、例外をキャッチし、エラーに関する追加情報を表示することで、エラーが正常に処理されます。

import { CosmosClient, ErrorResponse, RestError } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

try {
  await container.items.create({ id: "existing-item-id" });
} catch (error) {
  const err = error as ErrorResponse | RestError;
  if (err.code === 409) {
    console.log("There was a conflict with an existing item");
  }
}

トランスパイル

Azure SDKはES5のJavaScript構文とLTS版の Node.jsをサポートするよう設計されています。 Internet ExplorerやNode 6のような初期のJavaScriptランタイムのサポートが必要な場合は、ビルドプロセスの一部としてSDKコードをトランスパイルする必要があります。

再試行による一時的なエラーの処理

Cosmos DB の操作中に、サービスによって適用 レート制限や、ネットワークの停止などの一時的な問題が原因で一時的な障害が発生する可能性があります。 これらの種類の障害の処理については、「クラウド 設計パターン ガイド 再試行パターン と、関連する サーキット ブレーカー パターン」を参照してください。

伐採

ログ記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、AZURE_LOG_LEVEL 環境変数を infoに設定します。 または、setLogLevelで @azure/logger を呼び出すことによって、実行時にログ記録を有効にすることもできます。 AZURE_LOG_LEVEL を使用している間は、ライブラリを初期化する前に必ず設定してください。 dotenv などのライブラリを使用する場合は、ライブラリをログ記録する前にそのようなライブラリが初期化されていることを確認する場合は、コマンド ラインを介して渡すのが理想的です。

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

ログを有効にする方法の詳細については、@azure/logger パッケージドキュメントを参照してください。

診断

Cosmos Diagnostics 機能を使用すると、すべてのクライアント操作に関する分析情報が強化されます。 CosmosDiagnostics オブジェクトは、すべてのクライアント操作の応答に追加されます。 とか

• ポイント検索操作の応答 - item.read()、container.create()、database.delete()
• クエリ操作の応答 -queryIterator.fetchAll()、
• 一括操作とバッチ操作 -item.batch()。
• エラー/例外応答オブジェクト。

CosmosDiagnostics オブジェクトは、すべてのクライアント操作の応答に追加されます。 3 つの Cosmos 診断レベル、情報、デバッグ、デバッグセーフがあります。 実稼働システム用の情報のみであり、デバッグとデバッグアンセーフは、開発およびデバッグ中に使用されることを意図しています。これは、大幅に多くのリソースを消費するためです。 Cosmos 診断レベルは 2 つの方法で設定できます

• プログラム的に

import { CosmosClient, CosmosDbDiagnosticLevel } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({
  endpoint,
  key,
  diagnosticLevel: CosmosDbDiagnosticLevel.debug,
});

• 環境変数の使用。 (環境変数によって設定された診断レベルは、クライアント オプションを使用して設定するよりも優先度が高くなります)。

  export AZURE_COSMOSDB_DIAGNOSTICS_LEVEL="debug"

Cosmos Diagnostic には 3 つのメンバーがあります

• ClientSideRequestStatistics の種類: メタデータの参照、再試行、接続されたエンドポイント、ペイロードのサイズや期間などの要求と応答の統計情報など、診断の詳細を集計します。 (常に収集され、運用システムで使用できます)。

• DiagnosticNode: 詳細な診断情報をキャプチャするツリーのような構造です。 ブラウザーに存在する har 記録に似ています。 この機能は既定で無効になっており、非運用環境のデバッグのみを目的としています。 (診断レベルのデバッグと debug-unsafe で収集されます)

• ClientConfig: クライアントの初期化中にクライアントの構成設定に関連する重要な情報をキャプチャします。 (診断レベルのデバッグと debug-unsafe で収集されます)

このレベルは要求と応答のペイロードをキャプチャ debug-unsafe、ログに記録する場合 (既定では CosmosDiagnostics レベルで @azure/logger ログに記録されるため)、運用環境で診断レベルを verbose に設定しないでください。 これらのペイロードは、ログ シンクにキャプチャされる場合があります。

診断の使用

• diagnostics はすべての Response オブジェクトに追加されるためです。 CosmosDiagnostic には、次のようにプログラムでアクセスできます。

import {
  CosmosClient,
  CosmosDbDiagnosticLevel,
  OperationInput,
  BulkOperationType,
} from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({
  endpoint,
  key,
  diagnosticLevel: CosmosDbDiagnosticLevel.debug,
});

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });
// For point look up operations

const { container, diagnostics: containerCreateDiagnostic } =
  await database.containers.createIfNotExists({
    id: "<container-id>",
    partitionKey: {
      paths: ["/key1"],
    },
  });

// For Batch operations
const operations: OperationInput[] = [
  {
    operationType: BulkOperationType.Create,
    resourceBody: { id: "A", key: "A", school: "high" },
  },
];

const response = await container.items.batch(operations, "A");

// For query operations
const queryIterator = container.items.query("select * from c");
const { resources, diagnostics } = await queryIterator.fetchAll();

// While error handling
try {
  // Some operation that might fail
} catch (err) {
  const diagnostics = err.diagnostics;
}

• diagnosticsを使用して @azure/logger をログに記録することもできます。診断は常に @azure/logger レベルで verbose を使用してログに記録されます。 そのため、診断レベルを debug または debug-unsafe に設定し、@azure/logger レベルを verboseに設定すると、diagnostics がログに記録されます。

次の手順

その他のサンプル コード

Several Samples はSDKのGitHubリポジトリで利用可能です。 これらのサンプルでは、Cosmos DB の使用中に一般的に発生するその他のシナリオのコード例を示します。

• データベース操作
• コンテナー操作
• アイテム操作
• インデックス作成の構成
• コンテナー変更フィードの読み取り
• ストアド プロシージャ
• データベース/コンテナーのスループット設定の変更
• 複数リージョンの書き込み操作

制限

現在、以下の機能 サポートされていません。 代替オプションについては、以下の「回避策 セクション」を参照してください。

• クライアント側の暗号化は、現在ブラウザー環境ではサポートされていません。

データ プレーンの制限事項:

• DISTINCT サブクエリからの COUNT を使用したクエリ
• TCP モードへの直接アクセス
• 並べ替え、カウント、個別など、パーティション間のクエリを集計しても、継続トークンはサポートされません。 SELECT * FROM などのストリーミング可能なクエリ WHERE <条件>は、継続トークンをサポートします。 継続トークンなしでストリーミング不可能なクエリを実行する場合は、「回避策」セクションを参照してください。
• 変更フィード: プロセッサ
• 変更フィード: 複数のパーティションのキー値を読み取ります
• 混合型のクロスパーティション ORDER BY
• ページ化に継続トークンを使うために最新のSDKへのアップグレードを推奨します。 複数のパーティションをスキャンするクロスパーティションクエリで enableQueryControl 付きの継続トークンを使用する場合は、クエリオプションの forceQueryPlan: true を設定して決定論的な実行計画を強制するようにしてください。 これがなければ、クエリの実行動作がパーティション間で異なり、継続トークンの一貫性に影響を及ぼします。

コントロール プレーンの制限事項:

• CollectionSizeUsage、DatabaseUsage、DocumentUsage のメトリックを取得する
• 地理空間インデックスを作成する
• 自動スケールスループットを更新する

回避策

クロスパーティションクエリのための継続トークン 古いバージョン(< 4.9.0)

4.9.0以前の古いバージョンでは、継続トークン対応のクロスパーティションクエリをSide car patternで実現できます。 このパターンにより、アプリケーションを異種コンポーネントとテクノロジで構成することもできます。

非ストリーム化可能なクロスパーティションクエリの実行

継続トークンを使用せずにストリーミング不可能なクエリを実行するには、必要なクエリの仕様とオプションを含むクエリ反復子を作成できます。 次のサンプル コードは、クエリ反復子を使用して、継続トークンを必要とせずにすべての結果をフェッチする方法を示しています。

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

const querySpec = {
  query: "SELECT c.status, COUNT(c.id) AS count FROM c GROUP BY c.status",
};
const queryOptions = {
  maxItemCount: 10, // maximum number of items to return per page
  enableCrossPartitionQuery: true,
};
const queryIterator = container.items.query(querySpec, queryOptions);
while (queryIterator.hasMoreResults()) {
  const { resources: result } = await queryIterator.fetchNext();
  // process results
}

この方法は、ストリーミング可能なクエリにも使用できます。

コントロール プレーン操作

通常、制御プレーンの非サポート制限には、Azure portal、Azure Cosmos DB Resource Provider REST API、Azure CLI、またはPowerShellを利用できます。

その他のドキュメント

Cosmos DBサービスに関するより詳細なドキュメントについては、learn.microsoft.com のAzure Cosmos DBドキュメントを参照してください。

便利なリンク

• ようこそAzure Cosmos DB
• クイック スタート の
• チュートリアル
• Samples
• リソースモデルAzure Cosmos DB
• Introduction to SQL API of Azure Cosmos DB Service
• パーティション分割 の
• API ドキュメントの

貢献

このライブラリに貢献したい場合は、コードのビルドやテスト方法について詳しく知るために、contributing guideをお読みください。