JavaScript を使用して Azure Cosmos DB for NoSQL の使用を開始する
適用対象: NoSQL
この記事では、JavaScript SDK を使用して Azure Cosmos DB for NoSQL に接続する方法を示します。 接続すると、データベース、コンテナー、および項目に対する操作を実行できます。
パッケージ (npm) | サンプル | API リファレンス | ライブラリ ソース コード | フィードバックを送る
前提条件
- アクティブなサブスクリプションが含まれる Azure アカウント。 無料でアカウントを作成できます。
- Azure Cosmos DB for NoSQL アカウント。 NoSQL 用 API アカウントを作成します。
- Node.js LTS
- Azure コマンド ライン インターフェイス (CLI) または Azure PowerShell
ローカル プロジェクトを設定する
Bash シェルで JavaScript プロジェクトの新しいディレクトリを作成します。
mkdir cosmos-db-nosql-javascript-samples && cd ./cosmos-db-nosql-javascript-samples
npm init
コマンドとコンソール テンプレートを使用して、新しい JavaScript アプリケーションを作成します。npm init -y
Azure Cosmos DB for NoSQL JavaScript SDK に必要な依存関係をインストールします。
npm install @azure/cosmos
Azure Cosmos DB for NoSQL に接続する
Azure Cosmos DB の NoSQL 用 API に接続するには、CosmosClient
クラスのインスタンスを作成します。 このクラスは、データベースに対するすべての操作を実行するための開始点です。 CosmosClient クラスを使用して NoSQL 用 API アカウントに接続する主な方法は次の 3 つです。
エンドポイントとキーを使用して接続する
CosmosClient の最も一般的なコンストラクターには、次の 2 つのパラメーターがあります。
パラメーター | 値の例 | 説明 |
---|---|---|
accountEndpoint |
COSMOS_ENDPOINT 環境変数 |
すべての要求に使用する NoSQL 用 API エンドポイント |
authKeyOrResourceToken |
COSMOS_KEY 環境変数 |
認証時に使用するアカウント キーまたはリソース トークン |
アカウント エンドポイントとキーを取得する
resourceGroupName のシェル変数を作成します。
# Variable for resource group name resourceGroupName="msdocs-cosmos-javascript-howto-rg"
az cosmosdb list
コマンドを使用して、リソース グループ内の最初の Azure Cosmos DB アカウントの名前を取得し、それを accountName シェル変数に格納します。# Retrieve most recently created account name accountName=$( az cosmosdb list \ --resource-group $resourceGroupName \ --query "[0].name" \ --output tsv )
az cosmosdb show
コマンドを使用して、アカウントの NoSQL 用 API エンドポイント URI を取得します。az cosmosdb show \ --resource-group $resourceGroupName \ --name $accountName \ --query "documentEndpoint"
az-cosmosdb-keys-list
コマンドを使用して、アカウントのキーの一覧から PRIMARY KEY を見つけます。az cosmosdb keys list \ --resource-group $resourceGroupName \ --name $accountName \ --type "keys" \ --query "primaryMasterKey"
URI と PRIMARY KEY の値を記録します。 これらの資格情報は後で使用します。
コード内で URI 値と PRIMARY KEY 値を使用するには、アプリケーションを実行しているローカル コンピューター上の新しい環境変数に保持します。
$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"
アカウント エンドポイントとキーを使用して CosmosClient を作成する
COSMOS_ENDPOINT
および COSMOS_KEY
環境変数をパラメーターとして使用し、CosmosClient クラスの新しいインスタンスを作成します。
const client = new CosmosClient({ endpoint, key });
接続文字列を使用して接続する
CosmosClient の別のコンストラクターには、1 つのパラメーターのみが含まれています。
パラメーター | 値の例 | 説明 |
---|---|---|
accountEndpoint |
COSMOS_ENDPOINT 環境変数 |
すべての要求に使用する NoSQL 用 API エンドポイント |
connectionString |
COSMOS_CONNECTION_STRING 環境変数 |
NoSQL 用 API アカウントへの接続文字列 |
アカウント接続文字列を取得する
az cosmosdb list
コマンドを使用して、リソース グループ内の最初の Azure Cosmos DB アカウントの名前を取得し、それを accountName シェル変数に格納します。# Retrieve most recently created account name accountName=$( az cosmosdb list \ --resource-group $resourceGroupName \ --query "[0].name" \ --output tsv )
az-cosmosdb-keys-list
コマンドを使用して、アカウントの接続文字列の一覧から "プライマリ接続文字列" を見つけます。az cosmosdb keys list \ --resource-group $resourceGroupName \ --name $accountName \ --type "connection-strings" \ --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"
コード内でプライマリ接続文字列値を使用するには、アプリケーションを実行しているローカル コンピューター上で新しい環境変数にそれを保持します。
$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"
接続文字列を使用して CosmosClient を作成する
COSMOS_CONNECTION_STRING
環境変数を唯一のパラメーターとして使用し、CosmosClient クラスの新しいインスタンスを作成します。
// New instance of CosmosClient class using a connection string
const cosmosClient = new CosmosClient(process.env.COSMOS_CONNECTION_STRING);
Microsoft ID プラットフォームを使用して接続する
Microsoft ID プラットフォームと Microsoft Entra ID を使用して NoSQL 用 API アカウントに接続するには、セキュリティ プリンシパルを使用します。 プリンシパルの正確な種類は、アプリケーション コードをホストする場所によって異なります。 次の表は、クイック リファレンス ガイドとして機能します。
アプリケーションの実行場所 | セキュリティ プリンシパル |
---|---|
ローカル コンピューター (開発とテスト) | ユーザー ID またはサービス プリンシパル |
Azure | マネージド ID |
Azure の外部にあるサーバーまたはクライアント | サービス プリンシパル |
@azure/identity をインポートする
@azure/identity npm パッケージには、すべての Azure SDK ライブラリ間で共有されるコア認証機能が含まれています。
npm install
コマンドを使用して、@azure/identity npm パッケージをインポートします。npm install @azure/identity
コード エディターで、依存関係を追加します。
const { DefaultAzureCredential } = require("@azure/identity");
既定の資格情報の実装を使用して CosmosClient を作成する
ローカル コンピューター上でテストする場合、またはマネージド ID を直接サポートする Azure サービス上でアプリケーションを実行する場合は、DefaultAzureCredential
インスタンスを作成して OAuth トークンを取得します。 次に、COSMOS_ENDPOINT
環境変数と TokenCredential オブジェクトをパラメーターとして使用して、CosmosClient クラスの新しいインスタンスを作成します。
const { CosmosClient } = require("@azure/cosmos");
const { DefaultAzureCredential } = require("@azure/identity");
const credential = new DefaultAzureCredential();
const cosmosClient = new CosmosClient({
endpoint,
aadCredentials: credential
});
カスタム資格情報の実装を使用して CosmosClient を作成する
Azure の外部のアプリケーションをデプロイする予定がある場合は、JavaScript 用の @azure/identity クライアント ライブラリの他のクラスを使用して、OAuth トークンを取得できます。 これらの他のクラスは、TokenCredential
クラスからも派生します。
この例では、クライアントとテナントの識別子、およびクライアント シークレットを使用して ClientSecretCredential
インスタンスを作成します。
アプリケーションを Microsoft Entra ID に登録するときに、クライアント ID、テナント ID、クライアント シークレットを取得できます。 Microsoft Entra アプリケーションの登録の詳細については、「Microsoft ID プラットフォームにアプリケーションを登録する」を参照してください。
COSMOS_ENDPOINT
環境変数と TokenCredential オブジェクトをパラメーターとして使用して、CosmosClient クラスの新しいインスタンスを作成します。
const { CosmosClient } = require("@azure/cosmos");
const { DefaultAzureCredential } = require("@azure/identity");
const credential = new ClientSecretCredential(
tenantId: process.env.AAD_TENANT_ID,
clientId: process.env.AAD_CLIENT_ID,
clientSecret: process.env.AAD_CLIENT_SECRET
);
const cosmosClient = new CosmosClient({
endpoint,
aadCredentials: credential
});
アプリケーションをビルドする
アプリケーションをビルドすると、コードは主に 4 種類のリソースと対話します。
NoSQL 用 API アカウント。これは、Azure Cosmos DB データに対する一意で最上位の名前空間です。
アカウント内のコンテナーを整理するデータベース。
データベース内の個々の項目のセットを含むコンテナー。
コンテナー内の JSON ドキュメントを表す項目。
次の図に、これらのリソースの関係を示します。
上部に Azure Cosmos DB アカウントを示す階層図。 アカウントには 2 つの子データベース ノードがあります。 一方のデータベース ノードには、2 つの子コンテナー ノードが含まれています。 もう一方のデータベース ノードには、1 つの子コンテナー ノードが含まれています。 その 1 つのコンテナー ノードには、3 つの子項目ノードがあります。
各種類のリソースは、1 つまたは複数の関連付けられたクラスによって表されます。 以下に最も一般的なクラスの一覧を示します。
クラス | 説明 |
---|---|
CosmosClient |
このクラスは、Azure Cosmos DB サービスのクライアント側の論理表現を提供します。 このクライアント オブジェクトは、サービスに対する要求の構成と実行に使用されます。 |
Database |
このクラスは、サービスにまだ存在する場合と存在しない場合があるデータベースへの参照です。 データベースへのアクセスまたはデータベースに対する操作の実行を試みると、データベースはサーバー側で検証されます。 |
Container |
このクラスは、まだサービスに存在しない可能性があるコンテナーへの参照です。 コンテナーを操作しようとすると、コンテナーはサーバー側で検証されます。 |
次のガイドでは、これらの各クラスを使ってアプリケーションをビルドする方法を示します。
ガイド | 説明 |
---|---|
データベースの作成 | データベースを作成する |
コンテナーの作成 | コンテナーを作成する |
アイテムの作成と読み取り | 特定の項目のポイント読み取り |
クエリ項目 | 複数の項目のクエリの実行 |
関連項目
次のステップ
これで NoSQL 用 API アカウントに接続したので、次のガイドを使用してデータベースを作成し、管理してください。