クイックスタート: Azure SDK for Node.js で Azure Cosmos DB for Table を使用する
このクイックスタートでは、Azure SDK for Node.js を使用して、基本的な Azure Cosmos DB for Table アプリケーションを展開します。 Azure Cosmos DB for Table はスキーマレス データ ストアであり、これによりアプリケーションは構造化されたテーブル データをクラウドに保存できます。 Azure SDK for Node.js を使用して、Azure Cosmos DB リソース内でテーブル、行を作成し、基本的なタスクを実行する方法について説明します。
API リファレンス ドキュメント | ライブラリのソース コード | パッケージ (npm) | Azure Developer CLI
前提条件
- Azure Developer CLI
- Docker Desktop
- Node.js 22 以降
Azure アカウントをお持ちでない場合は、開始する前に無料アカウントを作成してください。
プロジェクトを初期化する
Azure Developer CLI (azd) を使用して、Azure Cosmos DB for Table アカウントを作成し、コンテナー化されたサンプル アプリケーションをデプロイします。 サンプル アプリケーションでは、クライアント ライブラリを使って、サンプル データの管理、作成、読み取り、クエリを実行します。
空のディレクトリでターミナルを開きます。
まだ認証されていない場合は、
azd auth loginを使用して Azure Developer CLI に対して認証します。 ツールによって指示された手順に従って、任意の Azure 資格情報を使って CLI に対して認証します。azd auth loginazd initを使ってプロジェクトを初期化します。azd init --template cosmos-db-table-nodejs-quickstart初期化中に、一意の環境名を構成します。
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/data-tables パッケージとして npm 経由で使用できます。
ターミナルを開き、
/src/tsフォルダーに移動します。cd ./src/ts@azure/data-tablesパッケージがまだインストールされていない場合は、npm installを使ってインストールします。npm install --save @azure/data-tablessrc/ts/package.json ファイルを開いて確認し、
@azure/data-tablesエントリが存在することを確かめます。
ターミナルを開き、
/src/jsフォルダーに移動します。cd ./src/js@azure/data-tablesパッケージがまだインストールされていない場合は、npm installを使ってインストールします。npm install --save @azure/data-tablessrc/js/package.json ファイルを開いて確認し、
@azure/data-tablesエントリが存在することを確かめます。
オブジェクト モデル
| 名前 | 説明 |
|---|---|
TableServiceClient |
この種類は主要なクライアントの種類であり、アカウント全体のメタデータやデータベースを管理するために使われます。 |
TableClient |
この種類は、アカウント内のテーブルのクライアントを表します。 |
コード例
テンプレート内のサンプル コードでは、cosmicworks-products という名前のテーブルを使用します。 cosmicworks-products テーブルには、各製品の名前、カテゴリ、数量、価格、一意識別子、販売フラグなどの詳細が含まれています。 コンテナーでは、行キーとして "一意識別子"* を使用し、パーティション キーとして "カテゴリ" を使用します。
クライアントを認証する
このサンプルでは、TableServiceClient 型の新しいインスタンスを作成します。
let client: TableServiceClient = new TableServiceClient("<azure-cosmos-db-table-account-endpoint>", "<credential>");
const credential = new DefaultAzureCredential();
let client = new TableServiceClient("<azure-cosmos-db-table-account-endpoint>", credential);
テーブルを取得
このサンプルでは、TableServiceClient 型の GetTableClient 関数を使用して TableClient 型のインスタンスを作成します。
let table: TableClient = new TableClient("<azure-cosmos-db-table-account-endpoint>", "<azure-cosmos-db-table-name>", credential);
let table = new TableClient("<azure-cosmos-db-table-account-endpoint>", "<azure-cosmos-db-table-name>", credential);
エンティティの作成
テーブルに新しいエンティティを作成する最も簡単な方法は、TableEntity から新しいインターフェイスを派生させて、その型の新しいオブジェクトを作成することです。
export interface Product extends TableEntity {
name: string;
quantity: number;
price: number;
clearance: boolean;
}
const entity: Product = {
rowKey: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
partitionKey: 'gear-surf-surfboards',
name: 'Yamba Surfboard',
quantity: 12,
price: 850.00,
clearance: false
};
テーブルに新しい項目を作成する最も簡単な方法は、JSON オブジェクトを作成することです。
const entity = {
rowKey: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
partitionKey: 'gear-surf-surfboards',
name: 'Yamba Surfboard',
quantity: 12,
price: 850.00,
clearance: false
};
TableService インスタンスから upsertEntity メソッドを使用して、テーブル内にエンティティを作成します。
await table.upsertEntity<Product>(entity, "Replace");
await table.upsertEntity(entity, "Replace");
エンティティを取得する
getEntity メソッド、エンティティの行キー、エンティティのパーティション キーを使用して、テーブルから特定のエンティティを取得できます。
const response: GetTableEntityResponse<TableEntityResult<Product>> = await table.getEntity<Product>(partitionKey, rowKey);
const entity: Product = response as Product;
const entity = await table.getEntity(partitionKey, rowKey);
エンティティを照会する
エンティティを挿入した後、listEntities と OData フィルターを使用して、特定のフィルターに一致するすべてのエンティティを取得するクエリを実行することもできます。
const partitionKey: string = 'gear-surf-surfboards';
const filter: string = `PartitionKey eq '${partitionKey}'`
const queryOptions: TableEntityQueryOptions = { filter: filter }
const entities: PagedAsyncIterableIterator<TableEntityResult<Product>, TableEntityResultPage<Product>> = table.listEntities<Product>({ queryOptions: queryOptions });
const partitionKey = 'gear-surf-surfboards';
const entities = table.listEntities({
queryOptions: {
filter: `PartitionKey eq '${partitionKey}'`
}
});
entities のページ分割されたセットに対して非同期 for await ループを使用して、クエリのページ分割された結果を解析します。
for await(const entity of entities) {
// Do something
}
for await(const entity of entities) {
// Do something
}
リソースをクリーンアップする
サンプル アプリケーションやリソースが不要になったら、対応するデプロイとすべてのリソースを削除します。
azd down