クイック スタート - .Node.js 用の Azure Cosmos DB for NoSQ クライアント ライブラリ

適用対象: NoSQL

JavaScript 用の Azure Cosmos DB クライアント ライブラリを使用して、アカウント内にデータベース、コンテナー、項目を作成します。 クレジット カードまたは Azure サブスクリプションがない場合は、無料の Azure Cosmos DB 試用版アカウントをセットアップできます。 以下の手順に従って、パッケージをインストールし、基本タスクのコード例を試してみましょう。

注意

コード スニペットの例は、Node.js プロジェクトとして GitHub 上で使用できます。

前提条件

前提条件のチェック

  • ターミナルまたはコマンド ウィンドウで node --version を実行して、Node.js バージョンが現在の長期サポート (LTS) バージョンの 1 つであることを確認します。
  • az --version (Azure CLI) または Get-Module -ListAvailable AzureRM (Azure PowerShell) を実行して、適切な Azure コマンド ライン ツールがインストールされていることを確認します。

設定

このセクションでは、Azure Cosmos アカウントを作成し、JavaScript 用 Azure Cosmos DB SQL API クライアント ライブラリを使用してリソースを管理するプロジェクトを設定する手順について説明します。

Azure Cosmos DB アカウントを作成する

ヒント

Azure サブスクリプションがない場合。 Azure Cosmos DB を無料で試すことができます。クレジット カードは必要ありません。 無料試用版を使用してアカウントを作成する場合は、「新しい JavaScript アプリを作成する」セクションに進むことができます。

このクイック スタートでは、NoSQL 用 API を使用して Azure Cosmos DB アカウントを 1 つ作成します。

ヒント

このクイック スタートでは、リソース グループ名 msdocs-cosmos-quickstart-rg を使用することをお勧めします。

  1. Azure portal にサインインします。

  2. Azure portal のメニューまたは [ホーム] ページで、 [リソースの作成] を選択します。

  3. [新規] ページで、 [Azure Cosmos DB] を検索して選択します。

  4. [API オプションの選択] ページで、[NoSQL] セクション内の [作成] オプションを選択します。 Azure Cosmos DB には、NoSQL、MongoDB、PostgreSQL、Apache Cassandra、Apache Gremlin、Table の 6 つの API があります。 NoSQL 用 API に関する詳細を参照してください

    Azure Cosmos DB の [API オプションの選択] ページのスクリーンショット。

  5. [Azure Cosmos DB アカウントの作成] ページで、次の情報を入力します。

    設定 説明
    サブスクリプション サブスクリプション名 この Azure Cosmos アカウントに使用する Azure サブスクリプションを選択します。
    リソース グループ リソース グループ名 リソース グループを選択するか、 [新規作成] を選択し、新しいリソース グループの一意の名前を入力します。
    アカウント名 一意の名前 自分の Azure Cosmos アカウントを識別するための名前を入力します。 名前は、サフィックスが documents.azure.com の完全修飾ドメイン名 (FQDN) の一部として使用されるため、グローバルに一意である必要があります。 名前に含めることができるのは、英小文字、数字、ハイフン (-) のみです。 また、名前の長さは 3 文字から 44 文字である必要があります。
    場所 ユーザーに最も近いリージョン Azure Cosmos DB アカウントをホストする地理的な場所を選択します。 データに最も高速にアクセスできるよう、お客様のユーザーに最も近い場所を使用します。
    容量モード プロビジョニング スループットまたはサーバーレス プロビジョニング スループット モードでアカウントを作成するには、 [Provisioned throughput](プロビジョニング スループット) を選択します。 サーバーレス モードでアカウントを作成するには、 [サーバーレス] を選択します。
    Apply Azure Cosmos DB free tier discount (Azure Cosmos DB Free レベル割引を適用する) [適用] または [適用しない] Azure Cosmos DB の Free レベルを有効にする Azure Cosmos DB Free レベルのアカウントでは、最初の 1000 RU/s と 25 GB のストレージを無料でご利用いただけます。 Free レベルの詳細を確認してください。

    Note

    Azure サブスクリプションにつき所有できる Free レベルの Azure Cosmos DB アカウントは 1 つまでです。また、アカウントの作成時にオプトインする必要があります。 Free レベルの割引を適用するオプションが表示されない場合は、サブスクリプション内の別のアカウントが Free レベルで既に有効になっていることを意味します。

    NoSQL 用 API の新しいアカウント ページのスクリーンショット。

  6. [確認と作成] を選択します。

  7. 指定した設定を確認し、[作成] を選択します。 アカウントの作成には数分かかります。 ポータル ページに "デプロイが完了しました" と表示されるまで待ってから移動します。

  8. [リソースに移動] を選択し、Azure Cosmos DB アカウント ページに移動します。

    NoSQL 用 API リソースのデプロイ ページのスクリーンショット。

  9. NoSQL 用 API アカウント ページで、[キー] ナビゲーション メニュー オプションを選択します。

    NoSQL 用 API アカウント ページのスクリーンショット。ナビゲーション メニューで [キー] オプションが強調表示されています。

  10. URI フィールドと PRIMARY KEY フィールドの値を記録します。 これらの値は、後の手順で使用します。

    NoSQL 用 API アカウントの各種資格情報を含む [キー] ページのスクリーンショット。

環境変数を構成する

コード内で URI 値と PRIMARY KEY 値を使用するには、アプリケーションを実行しているローカル コンピューター上の新しい環境変数に保持します。 環境変数を設定するには、任意のターミナルを使用して次のコマンドを実行します。

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"

新しい JavaScript プロジェクトを作成する

  1. 任意のターミナルを使用して、空のフォルダーに新しい Node.js アプリケーションを作成します。

    npm init -y
    
  2. "type": "module", エントリを追加して、ES6 モジュールを使用するように package.json ファイルを編集します。 この設定により、コードで最新の async/await 構文を使用できます。

    {
      "name": "azure-cosmos-db-sql-api-quickstart",
      "version": "1.0.0",
      "description": "Azure Cosmos DB for Core (SQL) quickstart with JavaScript",
      "main": "index",
      "type": "module",
      "scripts": {
        "start": "node index.js",
        "test": "echo \"Error: no test specified\" && exit 1"
      },
      "keywords": [
        "cosmos",
        "quickstart"
      ],
      "author": "diberry",
      "license": "MIT",
      "dependencies": {
        "@azure/cosmos": "^3.17.0",
        "dotenv": "^16.0.2"
      }
    }
    

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

  1. @azure/cosmos npm パッケージを Node.js プロジェクトに追加します。

    npm install @azure/cosmos
    
  2. .env ファイルから環境変数を読み取るための dotenv npm パッケージを追加します。

    npm install dotenv
    

ローカル開発環境ファイルを作成する

  1. .gitignore ファイルを作成し、次の値を追加して、環境ファイルと node_modules を無視します。 この構成ファイルにより、セキュリティで保護された関連ファイルのみがソース コードに確実にチェックインされます。

    .env
    node_modules
    
  2. 次の変数を含む .env ファイルを作成します。

    COSMOS_ENDPOINT=
    COSMOS_KEY=
    

コード ファイルを作成する

index.js を作成し、環境変数を読み取るために、次の定型コードをファイルに追加します。

// Get environment variables from .env
import * as dotenv from 'dotenv';
dotenv.config();

クライアント ライブラリに依存関係を追加する

index.js ファイルの末尾に次のコードを追加して、プログラムで Cosmos DB にアクセスするために必要な依存関係を含めます。

// Get Cosmos Client
import { CosmosClient } from "@azure/cosmos";

コード ファイルに環境変数を追加する

index.js ファイルの末尾に次のコードを追加して、必要な環境変数を含めます。 エンドポイントとキーは、アカウント作成手順の最後に見つかりました。

// Provide required connection from environment variables
const key = process.env.COSMOS_KEY;
// Endpoint format: https://YOUR-RESOURCE-NAME.documents.azure.com:443/
const endpoint = process.env.COSMOS_ENDPOINT;

名前用の変数を追加する

データベースとコンテナーの一意の名前とパーティション キー (pk) を管理するには、次の変数を追加します。

// Uniqueness for database and container
const timeStamp = + new Date();

// Set Database name and container name with unique timestamp
const databaseName = `contoso_${timeStamp}`;
const containerName = `products_${timeStamp}`;
const partitionKeyPath = ["/categoryName"]

この例では、このサンプル コードを複数回実行する場合に備えて、データベースとコンテナーに timeStamp を追加することを選択しました。

オブジェクト モデル

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

アカウント、データベース、コンテナー、項目を含む Azure Cosmos DB 階層の図。

上部に Azure Cosmos DB アカウントを示す階層図。 アカウントには 2 つの子データベース ノードがあります。 一方のデータベース ノードには、2 つの子コンテナー ノードが含まれています。 もう一方のデータベース ノードには、1 つの子コンテナー ノードが含まれています。 その 1 つのコンテナー ノードには、3 つの子項目ノードがあります。

さまざまなリソースの階層の詳細については、Azure Cosmos DB のデータベース、コンテナー、および項目の操作に関する記事を参照してください。

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

  • CosmosClient - このクラスは、Azure Cosmos DB サービスのクライアント側の論理表現を提供します。 このクライアント オブジェクトは、サービスに対する要求の構成と実行に使用されます。
  • Database - このクラスは、サービスに存在する (または、まだ存在しない) 場合があるデータベースへの参照です。 データベースへのアクセスまたはデータベースに対する操作の実行を試みると、データベースはサーバー側で検証されます。
  • Container - このクラスは、まだサービスに存在しない可能性があるコンテナーへの参照です。 コンテナーを操作しようとすると、コンテナーはサーバー側で検証されます。
  • SqlQuerySpec - このインターフェイスは、SQL クエリと任意のクエリ パラメーターを表します。
  • QueryIterator<> - このクラスは、結果の現在のページを追跡し、結果の新しいページを取得できる反復子を表します。
  • FeedResponse<> - このクラスは、反復子からの応答の 1 ページを表します。

コード例

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

このサンプル コードでは、コンテナーは論理パーティション キーとしてカテゴリを使用します。

クライアントを認証する

index.js で、リソース エンドポイントキーを使用して Cosmos DB に対する認証を行う次のコードを追加します。 CosmosClient クラスの新しいインスタンスを定義します。

// Authenticate to Azure Cosmos DB
const cosmosClient = new CosmosClient({ endpoint, key });

データベースを作成します。

次のコードを追加して、CosmosClient.Databases.createDatabaseIfNotExists メソッドを使用して新しいデータベースを作成します (まだ存在しない場合)、 このメソッドは、既存または新しく作成されたデータベースへの参照を返します。

// Create database if it doesn't exist
const { database } = await cosmosClient.databases.createIfNotExists({ id: databaseName });
console.log(`${database.id} database ready`);

コンテナーの作成

次のコードを追加して、Database.Containers.createContainerIfNotExistsAsync メソッドを使用してコンテナーを作成します。 このメソッドは、コンテナーへの参照を返します。

// Create container if it doesn't exist
const { container } = await database.containers.createIfNotExists({
    id: containerName,
    partitionKey: {
        paths: partitionKeyPath
    }
});
console.log(`${container.id} container ready`);

項目を作成する

次のコードを追加して、データ セットを提供します。 各 "製品" には、一意の ID、名前、カテゴリ名 (パーティション キーとして使用) その他のフィールドがあります。

// Data items
const items = [
    {
        "id": "08225A9E-F2B3-4FA3-AB08-8C70ADD6C3C2",
        "categoryId": "75BF1ACB-168D-469C-9AA3-1FD26BB4EA4C",
        "categoryName": "Bikes, Touring Bikes",
        "sku": "BK-T79U-50",
        "name": "Touring-1000 Blue, 50",
        "description": "The product called \"Touring-1000 Blue, 50\"",
        "price": 2384.0700000000002,
        "tags": [
            {
                "_id": "27B7F8D5-1009-45B8-88F5-41008A0F0393",
                "name": "Tag-61"
            }
        ]
    },
    {
        "id": "2C981511-AC73-4A65-9DA3-A0577E386394",
        "categoryId": "75BF1ACB-168D-469C-9AA3-1FD26BB4EA4C",
        "categoryName": "Bikes, Touring Bikes",
        "sku": "BK-T79U-46",
        "name": "Touring-1000 Blue, 46",
        "description": "The product called \"Touring-1000 Blue, 46\"",
        "price": 2384.0700000000002,
        "tags": [
            {
                "_id": "4E102F3F-7D57-4CD7-88F4-AC5076A42C59",
                "name": "Tag-91"
            }
        ]
    },
    {
        "id": "0F124781-C991-48A9-ACF2-249771D44029",
        "categoryId": "56400CF3-446D-4C3F-B9B2-68286DA3BB99",
        "categoryName": "Bikes, Mountain Bikes",
        "sku": "BK-M68B-42",
        "name": "Mountain-200 Black, 42",
        "description": "The product called \"Mountain-200 Black, 42\"",
        "price": 2294.9899999999998,
        "tags": [
            {
                "_id": "4F67013C-3B5E-4A3D-B4B0-8C597A491EB6",
                "name": "Tag-82"
            }
        ]
    }
];

ループで Container.Items.create を呼び出して、コンテナーにいくつかの項目を作成します。

// Create all items
for (const item of items) {
    
    const { resource } = await container.items.create(item);
    console.log(`'${resource.name}' inserted`);
}

アイテムを取得する

Azure Cosmos DB では、一意識別子 (id) フィールドとパーティション キー フィールドの両方を使用して、ポイント読み取り操作を実行できます。 SDK では、両方の値を渡して Container.item().read を呼び出し、項目を返します。

パーティション キーはコンテナーに固有です。 この Contoso Products コンテナーでは、カテゴリ名 categoryName がパーティション キーとして使用されます。

// Read item by id and partitionKey - least expensive `find`
const { resource } = await container.item(items[0].id, items[0].categoryName).read();
console.log(`${resource.name} read`);

クエリ項目

次のコードを追加して、特定のフィルターに一致するすべての項目のクエリを実行します。 パラメーター化クエリ式を作成し、Container.Items.query メソッドを呼び出します。 このメソッドは、結果のページを管理する QueryIterator を返します。 次に、whilefor のループの組み合わせを使用して結果のページの fetchNextFeedResponse として実行し、個々のデータ オブジェクトを反復処理します。

このクエリはプログラムによって SELECT * FROM todo t WHERE t.partitionKey = 'Bikes, Touring Bikes' に構成されます。

// Query by SQL - more expensive `find`
// find all items with same categoryName (partitionKey)
const querySpec = {
    query: "select * from products p where p.categoryName=@categoryName",
    parameters: [
        {
            name: "@categoryName",
            value: items[2].categoryName
        }
    ]
};

// Get items 
const { resources } = await container.items.query(querySpec).fetchAll();

for (const item of resources) {
    console.log(`${item.id}: ${item.name}, ${item.sku}`);
}

FeedResponse から返されたこのデータを "項目" として使用する場合は、Container.Items.read メソッドを使用して Item を作成する必要があります。

項目を削除する

ID とパーティション キーを使用して項目を取得し、削除するために必要な次のコードを追加して、項目を削除します。 この例では、Container.Item.delete メソッドを使用して項目を削除します。

// Delete item
const { statusCode } = await container.item(items[2].id, items[2].categoryName).delete();
console.log(`${items[2].id} ${statusCode==204 ? `Item deleted` : `Item not deleted`}`);

コードの実行

このアプリは、AZURE Cosmos DB SQL API データベースとコンテナーを作成します。 次に、この例では項目を作成し、その項目を読み取ります。 最後に、この例では、特定のカテゴリに一致する項目のみを返すクエリを発行します。 この例では、各ステップで、実行したステップに関するメタデータをコンソールに出力します。

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

node index.js

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

contoso_1663276732626 database ready
products_1663276732626 container ready
'Touring-1000 Blue, 50' inserted
'Touring-1000 Blue, 46' inserted
'Mountain-200 Black, 42' inserted
Touring-1000 Blue, 50 read
08225A9E-F2B3-4FA3-AB08-8C70ADD6C3C2: Touring-1000 Blue, 50, BK-T79U-50
2C981511-AC73-4A65-9DA3-A0577E386394: Touring-1000 Blue, 46, BK-T79U-46
0F124781-C991-48A9-ACF2-249771D44029 Item deleted

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

NoSQL 用 API アカウントが不要になったら、対応するリソース グループを削除できます。

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

    ヒント

    このクイックスタートでは、msdocs-cosmos-quickstart-rg という名前にするようにお勧めしました。

  2. [リソース グループの削除] を選択します。

    リソース グループのナビゲーション バーにある [リソースグループの削除] オプションのスクリーンショット。

  3. [削除しますか] のダイアログで、リソース グループの名前を入力し、[削除] を選択します。

    リソース グループの [削除の確認] ページのスクリーンショット。

次の手順

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