クイック スタート: Node.js 用の Azure Cosmos DB for MongoDB ドライバー
適用対象: 
MongoDB
MongoDB npm パッケージの使用を開始して、Azure Cosmos DB リソース内にデータベース、コレクション、ドキュメントを作成します。 以下の手順に従って、パッケージをインストールし、基本タスクのコード例を試してみましょう。
Note
コード スニペットの例は、JavaScript プロジェクトとして GitHub で入手できます。
MongoDB 用 API リファレンス ドキュメント | MongoDB パッケージ (NuGet)
前提条件
- アクティブなサブスクリプションが含まれる Azure アカウント。 無料でアカウントを作成できます。
- Node.js LTS
- Azure コマンド ライン インターフェイス (CLI) または Azure PowerShell
前提条件のチェック
- ターミナルまたはコマンド ウィンドウで
node --versionを実行して、Node.js がいずれかの LTS バージョンであることを確認します。 az --version(Azure CLI) またはGet-Module -ListAvailable AzureRM(Azure PowerShell) を実行して、適切な Azure コマンド ライン ツールがインストールされていることを確認します。
設定
このセクションでは、Azure Cosmos DB アカウントを作成し、MongoDB npm パッケージを使用するプロジェクトを設定する手順について説明します。
Azure Cosmos DB アカウントを作成する
このクイック スタートでは、MongoDB 用 API を使って Azure Cosmos DB アカウントを 1 つ作成します。
accountName、resourceGroupName、および location のシェル変数を作成します。
# Variable for resource group name resourceGroupName="msdocs-cosmos-quickstart-rg" location="westus" # Variable for account name with a randomnly generated suffix let suffix=$RANDOM*$RANDOM accountName="msdocs-$suffix"az loginコマンドを使用して Azure CLI にサインインします (まだ行っていない場合)。az group createコマンドを使用して、サブスクリプションに新しいリソース グループを作成します。az group create \ --name $resourceGroupName \ --location $locationaz cosmosdb createコマンドを使って、既定の設定で新しい Azure Cosmos DB for MongoDB アカウントを作成します。az cosmosdb create \ --resource-group $resourceGroupName \ --name $accountName \ --locations regionName=$location --kind MongoDB
MongoDB 接続文字列の取得
az cosmosdb keys listコマンドを使って、アカウントの接続文字列の一覧から MongoDB 用 API の接続文字列を見つけます。az cosmosdb keys list --type connection-strings \ --resource-group $resourceGroupName \ --name $accountName"主キー" の値を記録します。 これらの資格情報は後で使用します。
新しい JavaScript アプリを作成する
任意のターミナルを使用して、空のフォルダーに新しい JavaScript アプリケーションを作成します。 npm init コマンドを使用して、package.json ファイルを作成するためのプロンプトを開始します。 プロンプトの既定値をそのまま使用します。
npm init
パッケージをインストールする
MongoDB npm パッケージを JavaScript プロジェクトに追加します。 npm パッケージの名前を指定して npm install package コマンドを使用します。 dotenv パッケージは、ローカルでの開発中に .env ファイルから環境変数を読み取るために使用されます。
npm install mongodb dotenv
環境変数を構成する
コード内で接続文字列の値を使用するには、アプリケーションを実行しているローカル環境でこの値を設定します。 環境変数を設定するには、任意のターミナルを使用して次のコマンドを実行します。
$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"
オブジェクト モデル
アプリケーションのビルドを開始する前に、Azure Cosmos DB のリソースの階層について説明します。 Azure Cosmos DB には、リソースの作成とアクセスに使用される特定のオブジェクト モデルがあります。 Azure Cosmos DB によって、アカウント、データベース、コレクション、ドキュメントで構成される階層内にリソースが作成されます。
上部に Azure Cosmos DB アカウントを示す階層図。 このアカウントには 2 つの子データベース シャードがあります。 一方のデータベース シャードには、2 つの子コレクション シャードが含まれています。 もう一方のデータベース シャードには、1 つの子コレクション ノードが含まれています。 その 1 つのコレクション シャードには、3 つの子ドキュメント シャードがあります。
これらのリソースとやり取りするには、以下の 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
次のステップ
このクイックスタートでは、Azure Cosmos DB for MongoDB アカウントを作成し、MongoDB ドライバーを使用してデータベースとコンテナーを作成する方法を説明しました。 これで、Azure Cosmos DB for MongoDB の詳細を確認して、より多くのデータをインポートし、複雑なクエリを実行し、Azure Cosmos DB MongoDB リソースを管理できるようになりました。