次の方法で共有


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

適用対象: MongoDB

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

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

前提条件

設定

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

GitHub codespaces で開く

開発コンテナーで開く

重要

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

  1. プロジェクトのルート ディレクトリでターミナルを開きます。

  2. azd auth login を使って Azure Developer CLI に対して認証します。 ツールによって指示された手順に従って、任意の Azure 資格情報を使って CLI に対して認証します。

    azd auth login
    
  3. azd init を使ってプロジェクトを初期化します。

    azd init --template cosmos-db-mongodb-nodejs-quickstart
    

    Note

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

  4. 初期化中に、一意の環境名を構成します。

    ヒント

    この環境名は、ターゲット リソース グループ名としても使用されます。 このクイックスタートでは、msdocs-cosmos-db の使用を検討してください。

  5. azd up を使って、Azure Cosmos DB アカウントをデプロイします。 Bicep テンプレートは、サンプル Web アプリケーションもデプロイします。

    azd up
    
  6. プロビジョニング プロセス中に、サブスクリプションと目的の場所を選択します。 プロビジョニング プロセスが完了するまで待ちます。 このプロセスには 5 分ほどかかる可能性があります。

  7. 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.
    
  8. コンソールで URL を使って、ブラウザーで Web アプリケーションに移動します。 実行中のアプリの出力を確認します。

    実行中の 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 階層の図。

上部に Azure Cosmos DB アカウントを示す階層図。 このアカウントには 2 つの子データベース シャードがあります。 一方のデータベース シャードには、2 つの子コレクション シャードが含まれています。 もう一方のデータベース シャードには、1 つの子コレクション ノードが含まれています。 その 1 つのコレクション シャードには、3 つの子ドキュメント シャードがあります。

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

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

コード例

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

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

クライアントを認証する

  1. プロジェクト ディレクトリから、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');
    
  2. コンストラクターを使用して 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 リソースを管理できるようになりました。