クイックスタート: Node.js 用の Azure Cosmos DB for MongoDB ドライバー

[アーティクル]
08/15/2024

適用対象: MongoDB

MongoDB npm パッケージの使用を開始して、Azure Cosmos DB リソース内にデータベース、コレクション、ドキュメントを作成します。以下の手順に従って、パッケージをインストールし、基本タスクのコード例を試してみましょう。

MongoDB 用 API リファレンスドキュメント | MongoDB パッケージ (NuGet)packages/Microsoft.Azure.Cosmos) | Azure Developer CLI

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
GitHub アカウント

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
Azure Developer CLI
Docker Desktop

設定

このプロジェクトの開発コンテナーをお使いの環境にデプロイします。次に、Azure Developer CLI (azd) を使って、Azure Cosmos DB for MongoDB アカウントを作成し、コンテナー化されたサンプルアプリケーションをデプロイします。サンプルアプリケーションでは、クライアントライブラリを使って、サンプルデータの管理、作成、読み取り、クエリを実行します。

重要

GitHub アカウントには、ストレージとコア時間のエンタイトルメントが無料で含まれています。詳細については、GitHub アカウントに含まれるストレージとコア時間に関する記事を参照してください。

プロジェクトのルートディレクトリでターミナルを開きます。
azd auth login を使って Azure Developer CLI に対して認証します。ツールによって指示された手順に従って、任意の Azure 資格情報を使って CLI に対して認証します。
```
azd auth login
```
azd init を使ってプロジェクトを初期化します。
```
azd init --template cosmos-db-mongodb-nodejs-quickstart
```
Note

このクイックスタートでは、azure-samples/cosmos-db-mongodb-nodejs-quickstart テンプレート GitHub リポジトリを使用します。このプロジェクトがまだお使いのマシンにない場合は、Azure Developer CLI によって自動的にクローンされます。
初期化中に、一意の環境名を構成します。

ヒント

この環境名は、ターゲットリソースグループ名としても使用されます。このクイックスタートでは、msdocs-cosmos-db の使用を検討してください。
azd up を使って、Azure Cosmos DB アカウントをデプロイします。 Bicep テンプレートは、サンプル Web アプリケーションもデプロイします。
```
azd up
```
プロビジョニングプロセス中に、サブスクリプションと目的の場所を選択します。プロビジョニングプロセスが完了するまで待ちます。このプロセスには 5 分ほどかかる可能性があります。

Azure リソースのプロビジョニングが完了すると、実行中の Web アプリケーションへの URL が出力に含まれます。

Deploying services (azd deploy)

  (✓) Done: Deploying service web
- Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>

SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.

コンソールで URL を使って、ブラウザーで Web アプリケーションに移動します。実行中のアプリの出力を確認します。

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

MongoDB npm パッケージを JavaScript プロジェクトに追加します。 npm パッケージの名前を指定して npm install package コマンドを使用します。 dotenv パッケージは、ローカルでの開発中に .env ファイルから環境変数を読み取るために使用されます。

npm install mongodb dotenv

オブジェクトモデル

アプリケーションのビルドを開始する前に、Azure Cosmos DB のリソースの階層について説明します。 Azure Cosmos DB には、リソースの作成とアクセスに使用される特定のオブジェクトモデルがあります。 Azure Cosmos DB によって、アカウント、データベース、コレクション、ドキュメントで構成される階層内にリソースが作成されます。

アカウント、データベース、コレクション、ドキュメントを含む Azure Cosmos DB 階層の図。

これらのリソースとやり取りするには、以下の MongoDB クラスを使用します。

MongoClient - このクラスは、Azure Cosmos DB での MongoDB 用 API レイヤーに対するクライアント側の論理表現を提供します。このクライアントオブジェクトは、サービスに対する要求の構成と実行に使用されます。
Db - このクラスは、サービスに存在する場合も、まだ存在していない場合もあるデータベースへの参照です。データベースへのアクセスまたはデータベースに対する操作の実行を試みると、データベースはサーバー側で検証されます。
Collection - このクラスは、同様にサービスにまだ存在していない場合があるコレクションへの参照です。コレクションは、操作しようとすると、サーバー側で検証されます。

この記事で説明されているサンプルコードでは、products という名前のコレクションを使用して adventureworks という名前のデータベースを作成します。 products コレクションは、名前、カテゴリ、数量、販売インジケーターなどの製品の詳細が含まれるように設計されています。各製品には、一意の識別子も含まれています。

この手順では、データベースでシャーディングを使用しません。

クライアントを認証する

プロジェクトディレクトリから、index.js ファイルを作成します。エディターで、MongoDB と DotEnv npm パッケージを参照する require ステートメントを追加します。

// Read .env file and set environment variables
require('dotenv').config();
const random = Math.floor(Math.random() * 100);

// Use official mongodb driver to connect to the server
const { MongoClient, ObjectId } = require('mongodb');

コンストラクターを使用して MongoClient, クラスの新しいインスタンスと process.env. を定義し、先ほど作成した環境変数を読み取ります。
```
// New instance of MongoClient with connection string
// for Cosmos DB
const url = process.env.COSMOS_CONNECTION_STRING;
const client = new MongoClient(url);
```

MongoClient インスタンスを作成するさまざまな方法の詳細については、MongoDB NodeJS ドライバーのクイックスタートに関するページをご覧ください。

非同期操作を設定する

index.js ファイルに次のコードを追加して、非同期操作をサポートします。

async function main(){

// The remaining operations are added here
// in the main function

}

main()
  .then(console.log)
  .catch(console.error)
  .finally(() => client.close());

async/await 構文を処理するために、main 関数に次のコードスニペットを追加する必要があります。

データベースに接続する

MongoClient.connect メソッドを使用して、Azure Cosmos DB for MongoDB リソースに接続します。この接続メソッドは、データベースへの参照を返します。

// Use connect method to connect to the server
await client.connect();

データベースインスタンスを取得する

MongoClient.db を使用してデータベースへの参照を取得します。

// Database reference with creation if it does not already exist
const db = client.db(`adventureworks`);
console.log(`New database:\t${db.databaseName}\n`);

コレクションインスタンスの取得

MongoClient.Db.collection はコレクションへの参照を取得します。

// Collection reference with creation if it does not already exist
const collection = db.collection('products');
console.log(`New collection:\t${collection.collectionName}\n`);

連結されたインスタンス

クライアント、データベース、およびコレクションを連結できます。連結は、複数のデータベースまたはコレクションにアクセスする必要がある場合に便利です。

const db = await client.db(`adventureworks`).collection('products').updateOne(query, update, options)

インデックスを作成する

Collection.createIndex を使用して、MongoDB の FindCursor.sort メソッドでの並べ替えに使用するドキュメントのプロパティにインデックスを作成します。

// create index to sort by name
const indexResult = await collection.createIndex({ name: 1 });
console.log(`indexResult: ${JSON.stringify(indexResult)}\n`);

ドキュメントを作成する

adventureworks データベースの product プロパティを使用してドキュメントを作成します。

製品の一意識別子の _id プロパティ。
category プロパティ。このプロパティは、論理パーティションキーとして使用できます。
name プロパティ。
インベントリの quantity プロパティ。
sale プロパティ。製品が販売されているかどうかを示します。

// Create new doc and upsert (create or replace) to collection
const product = {
    category: "gear-surf-surfboards",
    name: `Yamba Surfboard-${random}`,
    quantity: 12,
    sale: false
};
const query = { name: product.name};
const update = { $set: product };
const options = {upsert: true, new: true};

// Insert via upsert (create or replace) doc to collection directly
const upsertResult1 = await collection.updateOne(query, update, options);
console.log(`upsertResult1: ${JSON.stringify(upsertResult1)}\n`);

// Update via upsert on chained instance
const query2 = { _id: ObjectId(upsertResult1.upsertedId) };
const update2 = { $set: { quantity: 20 } };
const upsertResult2 = await client.db(`adventureworks`).collection('products').updateOne(query2, update2, options);
console.log(`upsertResult2: ${JSON.stringify(upsertResult2)}\n`);

Collection.UpdateOne を呼び出して、コレクションにドキュメントを作成します。このサンプルコードを複数回実行する場合に備えて、この例では新しいドキュメントを "作成" するのではなく、"アップサート" することを選択しました。

ドキュメントを取得する

Azure Cosmos DB では、一意識別子 (_id) とパーティションキー (category) の両方を使用して、低コストのポイント読み取り操作を実行できます。

// Point read doc from collection:
// - without sharding, should use {_id}
// - with sharding,    should use {_id, partitionKey }, ex: {_id, category}
const foundProduct = await collection.findOne({
    _id: ObjectId(upsertResult1.upsertedId), 
    category: "gear-surf-surfboards"
});
console.log(`foundProduct: ${JSON.stringify(foundProduct)}\n`);

ドキュメントにクエリを実行する

ドキュメントを挿入した後、クエリを実行して、特定のフィルターに一致するすべてのドキュメントを取得できます。この例では、特定のカテゴリ gear-surf-surfboards に一致するすべてのドキュメントを検索します。クエリを定義したら、Collection.find を呼び出して、FindCursor の結果を取得します。 JavaScript 配列メソッドを使用するには、カーソルを配列に変換します。

// select all from product category
const allProductsQuery = { 
    category: "gear-surf-surfboards" 
};

// get all documents, sorted by name, convert cursor into array
const products = await collection.find(allProductsQuery).sort({name:1}).toArray();
products.map((product, i ) => console.log(`${++i} ${JSON.stringify(product)}`));

トラブルシューティング:

The index path corresponding to the specified order-by item is excluded. などのエラーが発生した場合は、インデックスを作成していることを確認してください。

コードの実行

このアプリは、MongoDB 用 API データベースとコレクションを作成し、ドキュメントを作成してから、まったく同じドキュメントを読み戻します。最後に、この例では、その 1 つのドキュメントのみを返すクエリを発行します。この例では、各ステップで、実行したステップに関する情報がコンソールに出力されます。

アプリを実行するには、ターミナルを使用してアプリケーションディレクトリに移動し、アプリケーションを実行します。

node index.js

アプリの出力は次の例のようになります。

New database:   adventureworks

New collection: products

upsertResult1: {"acknowledged":true,"modifiedCount":0,"upsertedId":"62b1f492ff69395b30a03169","upsertedCount":1,"matchedCount":0}

upsertResult2: {"acknowledged":true,"modifiedCount":1,"upsertedId":null,"upsertedCount":0,"matchedCount":1}

foundProduct: {"_id":"62b1f492ff69395b30a03169","name":"Yamba Surfboard-93","category":"gear-surf-surfboards","quantity":20,"sale":false}

indexResult: "name_1"

1 {"_id":"62b1f47dacbf04e86c8abf25","name":"Yamba Surfboard-11","category":"gear-surf-surfboards","quantity":20,"sale":false}
done

リソースをクリーンアップする

Azure Cosmos DB for MongoDB アカウントが不要になった場合、対応するリソースグループは削除してかまいません。

az group delete コマンドを使用して、リソースグループを削除します。

az group delete --name $resourceGroupName

Remove-AzResourceGroup コマンドレットを使用して、リソースグループを削除します。

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters

Azure portal で先ほど作成したリソースグループに移動します。

ヒント

このクイックスタートでは、msdocs-cosmos-javascript-quickstart-rg という名前にするようにお勧めしました。
[リソースグループの削除] を選択します。
[削除しますか] のダイアログで、リソースグループの名前を入力し、[削除] を選択します。

次のステップ

このクイックスタートでは、Azure Cosmos DB for MongoDB アカウントを作成し、MongoDB ドライバーを使用してデータベースとコンテナーを作成する方法を説明しました。これで、Azure Cosmos DB for MongoDB の詳細を確認して、より多くのデータをインポートし、複雑なクエリを実行し、Azure Cosmos DB MongoDB リソースを管理できるようになりました。

オフラインで MongoDB を Azure Cosmos DB for MongoDB に移行する

次の方法で共有

クイックスタート: Node.js 用の Azure Cosmos DB for MongoDB ドライバー

前提条件

設定

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

オブジェクトモデル

コード例

クライアントを認証する

非同期操作を設定する

データベースに接続する

データベースインスタンスを取得する

コレクションインスタンスの取得

連結されたインスタンス

インデックスを作成する

ドキュメントを作成する

ドキュメントを取得する

ドキュメントにクエリを実行する

コードの実行

リソースをクリーンアップする

次のステップ

フィードバック

その他のリソース

次の方法で共有

クイック スタート: Node.js 用の Azure Cosmos DB for MongoDB ドライバー

前提条件

設定

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

オブジェクト モデル

コード例

クライアントを認証する

非同期操作を設定する

データベースに接続する

データベース インスタンスを取得する

コレクション インスタンスの取得

連結されたインスタンス

インデックスを作成する

ドキュメントを作成する

ドキュメントを取得する

ドキュメントにクエリを実行する

コードの実行

リソースをクリーンアップする

次のステップ

フィードバック

その他のリソース

クイックスタート: Node.js 用の Azure Cosmos DB for MongoDB ドライバー

オブジェクトモデル

データベースインスタンスを取得する

コレクションインスタンスの取得