クイックスタート: Node.js 用 Azure Cosmos DB for NoSQL ライブラリ

[アーティクル]
11/07/2024
適用対象:

✅ NoSQL

Node.js 用の Azure Cosmos DB for NoSQL クライアントライブラリを使用して、コンテナー内のデータのクエリを実行し、個々の項目で一般的な操作を実行できます。次の手順に従って、Azure Developer CLI を使用して最小限のソリューションを環境にデプロイしてください。

API リファレンスドキュメント | ライブラリのソースコード | パッケージ (npm) | Azure Developer CLI

前提条件

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

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

設定

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

重要

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

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

このクイックスタートでは、azure-samples/cosmos-db-nosql-dotnet-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 アプリケーションに移動します。実行中のアプリの出力を確認します。

クライアントライブラリをインストールする

クライアントライブラリは、ノードパッケージマネージャーを介して @azure/cosmos パッケージとして入手できます。

ターミナルを開き、/src フォルダーに移動します。
```
cd ./src
```
@azure/cosmos パッケージがまだインストールされていない場合は、npm install を使ってインストールします。
```
npm install --save @azure/cosmos
```
また、@azure/identity パッケージがまだインストールされていない場合はインストールします。
```
npm install --save @azure/identity
```
src/package.json ファイルを開いて確認し、azure-cosmos と azure-identity の両エントリが存在することを確認します。

オブジェクトモデル

名前	説明
`CosmosClient`	このクラスは主要なクライアントクラスであり、アカウント全体のメタデータやデータベースを管理するために使われます。
`Database`	このクラスはアカウント内のデータベースを表します。
`Container`	このクラスは主に、コンテナーまたはコンテナー内に格納されている項目の読み取り、更新、削除操作を実行するために使われます。
`PartitionKey`	このクラスは論理パーティションキーを表します。このクラスは、多くの一般的な操作やクエリに必要です。
`SqlQuerySpec`	このインターフェイスは、SQL クエリと任意のクエリパラメーターを表します。

テンプレートのサンプルコードでは、cosmicworks というデータベースと products というコンテナーを使います。 products コンテナーには、各製品の名前、カテゴリ、数量、一意識別子、販売フラグなどの詳細が含まれています。コンテナーでは、論理パーティションキーとして /category プロパティを使います。

クライアントを認証する

ほとんどの Azure サービスに対するアプリケーション要求は、承認される必要があります。アプリケーションと Azure Cosmos DB for NoSQL の間でパスワードレスの接続を実装するため、推奨される方法として、DefaultAzureCredential 型を使います。 DefaultAzureCredential は複数の認証方法をサポートしており、実行時に使用する方法が決定されます。

重要

パスワード、接続文字列、その他の資格情報を使用して、Azure サービスへの要求を直接承認することもできます。ただし、この方法は慎重に使用する必要があります。開発者は、安全でない場所にこれらのシークレットを公開しないように注意する必要があります。パスワードまたは秘密鍵へのアクセス権を取得したユーザーは誰でも、データベースサービスに対して認証を行うことができます。 DefaultAzureCredential では、アカウントキーよりも管理とセキュリティの利点が向上し、キーを保存するリスクなしでパスワードレス認証が可能になります。

このサンプルでは、CosmosClient 型の新しいインスタンスを作成し、DefaultAzureCredential インスタンスを使って認証します。

JavaScript
TypeScript

const credential = new DefaultAzureCredential();

const client = new CosmosClient({
    '<azure-cosmos-db-nosql-account-endpoint>',
    aadCredentials: credential
});

const credential: TokenCredential = new DefaultAzureCredential();

const client = new CosmosClient({
    '<azure-cosmos-db-nosql-account-endpoint>',
    aadCredentials: credential
});

データベースの取得

client.database を使って、cosmicworks という既存のデータベースを取得します。

JavaScript
TypeScript

const database = client.database('cosmicworks');

const database: Database = client.database('cosmicworks');

コンテナーの取得

database.container を使って既存の products コンテナーを取得します。

JavaScript
TypeScript

const container = database.container('products');

const container: Container = database.container('products');

項目を作成する

JSON にシリアル化するすべてのメンバーを含む新しいオブジェクトを構築します。この例では、型には一意識別子と、カテゴリ、名前、数量、価格、セールのフィールドがあります。 container.items.upsert を使ってコンテナー内に項目を作成します。このメソッドは "アップサート" を行い、項目が既に存在する場合は、それを効果的に置き換えます。

JavaScript
TypeScript

const item = {
    'id': 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    'category': 'gear-surf-surfboards',
    'name': 'Yamba Surfboard',
    'quantity': 12,
    'price': 850.00,
    'clearance': false
};

let response = await container.items.upsert(item);

const item: Product = {
    'id': 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    'category': 'gear-surf-surfboards',
    'name': 'Yamba Surfboard',
    'quantity': 12,
    'price': 850.00,
    'clearance': false
};

let response: ItemResponse<Product> = await container.items.upsert<Product>(item);

項目を読み取る

一意識別子 (id) フィールドとパーティションキーフィールドの両方を使用して、ポイント読み取り操作を実行できます。 container.item を使用して項目へのポインターを取得し、item.read を使って特定の項目を効率的に取得します。

JavaScript
TypeScript

const id = 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb';
const partitionKey = 'gear-surf-surfboards';

let response = await container.item(id, partitionKey).read();
let read_item = response.resource;

const id = 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb';
const partitionKey = 'gear-surf-surfboards';

let response: ItemResponse<Product> = await container.item(id, partitionKey).read<Product>();
let read_item: Product = response.resource!;

クエリ項目

container.items.query を使って、コンテナー内の複数の項目に対してクエリを実行します。次のパラメーター化クエリを使用して、指定されたカテゴリ内のすべての項目を検索します。

SELECT * FROM products p WHERE p.category = @category

query.fetchAll を使用してクエリのすべての結果を取り込みます。クエリの結果をループ処理します。

JavaScript
TypeScript

const querySpec = {
    query: 'SELECT * FROM products p WHERE p.category = @category',
    parameters: [
        {
            name: '@category',
            value: 'gear-surf-surfboards'
        }
    ]
};

let response = await container.items.query(querySpec).fetchAll();
for (let item of response.resources) {
    // Do something
}

const querySpec: SqlQuerySpec = {
    query: 'SELECT * FROM products p WHERE p.category = @category',
    parameters: [
        {
            name: '@category',
            value: 'gear-surf-surfboards'
        }
    ]
};

let response: FeedResponse<Product> = await container.items.query<Product>(querySpec).fetchAll();
for (let item of response.resources) {
    // Do something
}

次の方法で共有

クイックスタート: Node.js 用 Azure Cosmos DB for NoSQL ライブラリ

前提条件

設定

クライアントライブラリをインストールする

オブジェクトモデル

コード例

クライアントを認証する

データベースの取得

コンテナーの取得

項目を作成する

項目を読み取る

クエリ項目

フィードバック

その他のリソース

次の方法で共有

クイックスタート: Node.js 用 Azure Cosmos DB for NoSQL ライブラリ

前提条件

設定

クライアント ライブラリをインストールする

オブジェクト モデル

コード例

クライアントを認証する

データベースの取得

コンテナーの取得

項目を作成する

項目を読み取る

クエリ項目

関連するコンテンツ

フィードバック

その他のリソース

クライアントライブラリをインストールする

オブジェクトモデル