JavaScript 用 Azure Cosmos DB クライアントライブラリ - バージョン 4.2.0

[アーティクル]
11/20/2024

/TypeScript

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

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

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

主要なリンク:

はじめ

前提条件

Azure サブスクリプションと Cosmos DB SQL API アカウント

このパッケージを使用するには、Azure サブスクリプションと、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 クラスのインスタンスで始まります

const { CosmosClient } = require("@azure/cosmos");

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

async function main() {
  // The rest of the README samples are designed to be pasted into this function body
}

main().catch((error) => {
  console.error(error);
});

わかりやすくするために、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 によって自動的に生成されます。

これらのリソースの詳細については、「Azure Cosmos データベース、コンテナー、および項目の操作」を参照してください。

例

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

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

データベースを作成する

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

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

コンテナーを作成する

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

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

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

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

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 つの値で構成されている場合は、リテラル値または配列として指定できます。

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

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

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 が自動的に生成されます。

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

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でクエリを実行するよりもコストの低い操作です。

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

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

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

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

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

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

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

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

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

const { resources } = await container.items
  .query("SELECT * from c WHERE c.active = true", {
          partitionKey: ["foo", 100],
        })
  .fetchAll();
for (const item of resources) {
  console.log(`${item.name}, ${item.address.zip} `);
}

アイテムを削除する

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

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

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

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

const { resources } = await container.items
  .query("SELECT * from c WHERE c.isCapitol = true")
  .fetchAll();
for (const city of resources) {
  console.log(`${city.name}, ${city.state} is a capitol `);
}

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

const { resources } = await container.items
  .query({
    query: "SELECT * from c WHERE c.isCapitol = @isCapitol",
    parameters: [{ name: "@isCapitol", value: true }]
  })
  .fetchAll();
for (const city of resources) {
  console.log(`${city.name}, ${city.state} is a capitol `);
}

SQL API を使用して Cosmos DB データベースに対してクエリを実行する方法の詳細については、「sql クエリを使用して Azure Cosmos DB データクエリを実行する」を参照してください。

変更フィードプルモデル

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

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

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

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

Beginning

// Signals the iterator to read changefeed from the beginning of time.
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Beginning(),
};
const iterator = container.getChangeFeedIterator(options);

Time

// Signals the iterator to read changefeed from a particular point of time.
const time = new Date("2023/09/11"); // some sample date
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Time(time),
};

Now

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

Continuation

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

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

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 状態の応答を受け取ります。

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

エラー処理

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

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

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

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 状態コードに対応します。

Azure Cosmos DB の HTTP 状態コードの

競合

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

try {
  await containers.items.create({ id: "existing-item-id" });
} catch (error) {
  if (error.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に設定します。または、@azure/loggerで setLogLevel を呼び出すことによって、実行時にログ記録を有効にすることもできます。 AZURE_LOG_LEVEL を使用している間は、ライブラリを初期化する前に必ず設定してください。 dotenv などのライブラリを使用する場合は、ライブラリをログ記録する前にそのようなライブラリが初期化されていることを確認する場合は、コマンドラインを介して渡すのが理想的です。

const { setLogLevel } = require("@azure/logger");
setLogLevel("info");

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

診断

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

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

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

プログラム的に

  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 で収集されます)

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

診断の使用

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

  // For point look up operations
  const { container, diagnostics: containerCreateDiagnostic } =
    await database.containers.createIfNotExists({
      id: containerId,
      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
  }

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

次の手順

その他のサンプルコード

SDK の GitHub リポジトリには、いくつかのサンプルが用意されています。これらのサンプルでは、Cosmos DB の使用中に一般的に発生するその他のシナリオのコード例を示します。

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

制限

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

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

DISTINCT サブクエリからの COUNT を使用したクエリ
TCP モードへの直接アクセス
並べ替え、カウント、個別など、パーティション間のクエリを集計しても、継続トークンはサポートされません。 SELECT * FROM などのストリーミング可能なクエリ WHERE では、継続トークンがサポートされます。継続トークンなしでストリーミング不可能なクエリを実行する場合は、「回避策」セクションを参照してください。
変更フィード: プロセッサ
変更フィード: 複数のパーティションのキー値を読み取ります
部分階層パーティションキーの変更フィードプルモデルのサポート #27059
混合型のクロスパーティション ORDER BY

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

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

回避策

クロスパーティションクエリの継続トークン

Side car patternを使用して、継続トークンのサポートを使用してクロスパーティションクエリを実現できます。このパターンにより、アプリケーションを異種コンポーネントとテクノロジで構成することもできます。

stremable 以外のクロスパーティションクエリの実行

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

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 querIterator = await container.items.query(querySpec, queryOptions);
while (querIterator.hasMoreResults()) {
  const { resources: result } = await querIterator.fetchNext();
  //Do something with result
}

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

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

通常は、Azure Portal 、Azure Cosmos DB リソースプロバイダー REST API、Azure CLI 、または PowerShell を使用して、コントロールプレーンでサポートされていない制限を使用できます。

その他のドキュメント

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

便利なリンク

Azure Cosmos DB へようこそ
クイックスタートの
チュートリアル
サンプル
Azure Cosmos DB Service のリソースモデルの概要
Azure Cosmos DB Service の SQL API の概要
パーティション分割の
API ドキュメントの

貢献

このライブラリに投稿する場合は、コードをビルドしてテストする方法の詳細については、投稿ガイドを参照してください。

インプレッション

次の方法で共有

JavaScript 用 Azure Cosmos DB クライアント ライブラリ - バージョン 4.2.0

はじめ

前提 条件