クイックスタート: Node.js と Azure Cosmos DB を使って Table 用 API アプリを構築する
適用対象: Table
このクイックスタートでは、Azure Cosmos DB for Table アカウントを作成し、データ エクスプローラーと GitHub からクローンした Node.js アプリを使用してテーブルとエンティティを作成します。 Azure Cosmos DB は、マルチモデル データベース サービスです。グローバルな分散と水平方向のスケーリング機能により、ドキュメント データベースやテーブル データベース、キーと値のデータベース、グラフ データベースをすばやく作成し、クエリを実行することができます。
前提条件
- アクティブなサブスクリプションが含まれる Azure アカウント。 無料で作成できます。
- Node.js 0.10.29 以上。
- Git.
サンプル アプリケーション
このチュートリアルのサンプル アプリケーションは、リポジトリ (https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js) からクローンまたはダウンロードできます。 サンプル リポジトリには、スターターと完成したアプリの両方が含まれています。
git clone https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js
サンプル アプリケーションでは、気象データを例に Table 用 API の機能を説明しています。 気象観測を表すオブジェクトの格納と取得には Table 用 API が使用されます。これには、Table 用 API のスキーマレス機能を示すために追加のプロパティを持つオブジェクトを格納する操作が含まれます。
1 - Azure Cosmos DB アカウントを作成する
まず、自分のアプリケーションで使用するテーブルが組み込まれる Azure Cosmos DB Tables API アカウントを作成します。 これを行うには、Azure portal、Azure CLI、または Azure PowerShell を使用します。
Azure portal にログインし、次の手順に従って Azure Cosmos DB アカウントを作成します。
2 - テーブルを作成する
次に、アプリケーションで使用するテーブルを Azure Cosmos DB アカウント内に作成する必要があります。 従来のデータベースとは異なり、指定する必要があるのはテーブルの名前のみであり、テーブルのプロパティ (列) は指定する必要はありません。 データがテーブルに読み込まれると、必要に応じてプロパティ (列) が自動的に作成されます。
Azure portal で次の手順を実行して、Azure Cosmos DB アカウント内にテーブルを作成します。
3 - Azure Cosmos DB 接続文字列を取得する
Azure Cosmos DB 内のテーブルにアクセスするには、アプリに CosmosDB Storage アカウントのテーブル接続文字列が必要です。 この接続文字列は、Azure portal、Azure CLI、または Azure PowerShell を使用して取得できます。
手順 | Screenshot |
---|---|
Azure Cosmos DB アカウント ページの左側にある [設定] ヘッダーの下で [接続文字列] という名前のメニュー項目を見つけて選択します。 Azure Cosmos DB アカウントの接続文字列を取得できるページが表示されます。 | |
[プライマリ接続文字列] の値をコピーして、アプリケーションで使用します。 |
4 - Azure Data Tables SDK for JS をインストールする
nodejs アプリケーションから Azure Cosmos DB for Table にアクセスするには、Azure Data Tables SDK パッケージをインストールします。
npm install @azure/data-tables
5 - env.js file で Table クライアントを構成する
Azure portal から Azure Cosmos DB または Storage アカウントの接続文字列をコピーし、コピーした接続文字列を使用して TableServiceClient オブジェクトを作成します。 フォルダー 1-strater-app
または 2-completed-app
に切り替え。 次に、対応する環境変数の値を configure/env.js
ファイルに追加します。
const env = {
connectionString:"A connection string to an Azure Storage or Azure Cosmos DB account.",
tableName: "WeatherData",
};
Azure SDK は、クライアント オブジェクトを使用して Azure と通信し、Azure に対してさまざまな操作を実行します。 この TableClient
クラスは、Azure Cosmos DB for Table と通信するために使用されるクラスです。 通常、アプリケーションではテーブルごとに 1 つの serviceClient
オブジェクトが作成され、アプリケーション全体で使用されます。
const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
env.connectionString,
env.tableName
);
6 - Azure Cosmos DB テーブル操作を実装する
サンプル アプリの Azure Cosmos DB テーブル操作は、Services ディレクトリの tableClient.js
ファイルにある serviceClient
オブジェクトにすべて実装されます。
const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
env.connectionString,
env.tableName
);
テーブルから行を取得する
serviceClient
オブジェクトに含まれている listEntities
メソッドにより、テーブルから行を選択できるようになります。 この例では、このメソッドにパラメーターが渡されないため、テーブルからすべての行が選択されます。
const allRowsEntities = serviceClient.listEntities();
テーブルから返された行をフィルター処理する
テーブルから返された行をフィルター処理するには、OData スタイルのフィルター文字列を listEntities
メソッドに渡します。 たとえば、2021 年 7 月 1 日午前 0 時から 2021 年 7 月 2 日午前 0 時 (午前 0 時を含む) までの Chicago の気象記録をすべて取得するには、次のフィルター文字列を渡します。
PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00' and RowKey le '2021-07-02 12:00'
すべての OData フィルター演算子については、OData Web サイトの Filter System Query Option に関するセクションで確認できます。
この request.args パラメータが serviceClient
クラスの listEntities
メソッドに渡されると、null 以外のプロパティ値ごとにフィルター文字列が作成されます。 次に、"and" 句を使用してすべての値を結合することで、結合フィルター文字列が作成されます。 この結合フィルター文字列は serviceClient
オブジェクトの listEntities
メソッドに渡され、フィルター文字列に一致する行だけが返されます。 同様のメソッドをコード内で使用して、各自のアプリケーションで必要に応じて適切なフィルター文字列を作成できます。
const filterEntities = async function (option) {
/*
You can query data according to existing fields
option provides some conditions to query,eg partitionKey, rowKeyDateTimeStart, rowKeyDateTimeEnd
minTemperature, maxTemperature, minPrecipitation, maxPrecipitation
*/
const filterEntitiesArray = [];
const filters = [];
if (option.partitionKey) {
filters.push(`PartitionKey eq '${option.partitionKey}'`);
}
if (option.rowKeyDateTimeStart) {
filters.push(`RowKey ge '${option.rowKeyDateTimeStart}'`);
}
if (option.rowKeyDateTimeEnd) {
filters.push(`RowKey le '${option.rowKeyDateTimeEnd}'`);
}
if (option.minTemperature !== null) {
filters.push(`Temperature ge ${option.minTemperature}`);
}
if (option.maxTemperature !== null) {
filters.push(`Temperature le ${option.maxTemperature}`);
}
if (option.minPrecipitation !== null) {
filters.push(`Precipitation ge ${option.minPrecipitation}`);
}
if (option.maxPrecipitation !== null) {
filters.push(`Precipitation le ${option.maxPrecipitation}`);
}
const res = serviceClient.listEntities({
queryOptions: {
filter: filters.join(" and "),
},
});
for await (const entity of res) {
filterEntitiesArray.push(entity);
}
return filterEntitiesArray;
};
TableEntity オブジェクトを使用してデータを挿入する
テーブルにデータを追加する最も簡単な方法は TableEntity
オブジェクトを使用する方法です。 この例では、データが入力モデル オブジェクトから TableEntity
オブジェクトにマップされます。 入力オブジェクトで観測所名と観測日時を表すプロパティは、PartitionKey
および RowKey
プロパティにそれぞれマップされ、これらによりテーブル内の行の一意のキーが形成されます。 その後、入力モデル オブジェクトの追加プロパティが TableEntity オブジェクトのディクショナリ プロパティにマップされます。 最後に serviceClient
オブジェクトの createEntity
メソッドを使用して、テーブルにデータが挿入されます。
サンプル アプリケーションの insertEntity
関数を変更して、次のコードを含めます。
const insertEntity = async function (entity) {
await serviceClient.createEntity(entity);
};
TableEntity オブジェクトを使用してデータをアップサートする
テーブルに既に存在するパーティション キーと行キーの組み合わせでそのテーブルに行を挿入しようとすると、エラーが発生します。 このため多くの場合、テーブルに行を追加するときには createEntity
メソッドの代わりに upsertEntity
を使用することが推奨されます。 指定されたパーティション キーと行キーの組み合わせがテーブルに既に存在する場合は、upsertEntity
メソッドにより既存の行が更新されます。 それ以外の場合は行がテーブルに追加されます。
const upsertEntity = async function (entity) {
await serviceClient.upsertEntity(entity, "Merge");
};
可変プロパティを使用してデータを挿入またはアップサートする
Azure Cosmos DB for Table を使用する利点の 1 つは、テーブルに読み込まれるオブジェクトに新しいプロパティが含まれている場合、それらのプロパティがテーブルに自動的に追加され、値が Azure Cosmos DB に格納されることです。 従来のデータベースのように、ALTER TABLE などの DDL ステートメントを実行して列を追加する必要はありません。
このモデルを使用すると、時間の経過とともに取り込む必要があるデータを追加または変更する可能性のあるデータ ソースを扱う場合や、異なる入力によりアプリケーションに異なるデータを提供する場合に、アプリケーションに柔軟性が加わります。 サンプル アプリケーションでは、基本的な気象データの他にいくつかの追加の値も送信する観測所をシミュレートできます。 このような新しいプロパティを持つオブジェクトが初めてテーブルに格納されるときに、対応するプロパティ (列) がテーブルに自動的に追加されます。
Table 用 API を使用してこのようなオブジェクトを挿入またはアップサートするには、展開可能なオブジェクトのプロパティを TableEntity
オブジェクトにマップし、必要に応じて serviceClient
オブジェクトの createEntity
または upsertEntity
メソッドを使用します。
サンプル アプリケーションでは、upsertEntity
関数は、変数プロパティを持つデータの挿入またはアップサートの関数を実装することもできます
const insertEntity = async function (entity) {
await serviceClient.createEntity(entity);
};
const upsertEntity = async function (entity) {
await serviceClient.upsertEntity(entity, "Merge");
};
エンティティを更新する
エンティティを更新するには、serviceClient
オブジェクトの updateEntity
メソッドを呼び出します。
サンプル アプリケーションでは、このオブジェクトは serviceClient
オブジェクトの upsertEntity
メソッドに渡されます。 そのエンティティ オブジェクトを更新し、upsertEntity
メソッドを使用して更新内容をデータベースに保存します。
const updateEntity = async function (entity) {
await serviceClient.updateEntity(entity, "Replace");
};
7 - コードを実行する
サンプル アプリケーションを実行して、Azure Cosmos DB for Table を操作します。 アプリケーションを初めて実行する場合にはテーブルが空であるため、データがありません。 アプリケーションの上部にあるいずれかのボタンを使用して、テーブルにデータを追加します。
[Insert using Table Entity](テーブル エンティティを使用して挿入) ボタンを選択すると、TableEntity
オブジェクトを使用して新しい行を挿入またはアップサートできるダイアログが開きます。
[Insert using Expandable Data](展開可能なデータを使用して挿入) ボタンを選択すると、カスタム プロパティを持つオブジェクトを挿入できるダイアログが表示され、Azure Cosmos DB for Table によって必要に応じてプロパティ (列) がテーブルに自動的に追加される方法が示されます。 [カスタム フィールドの追加] ボタンを使用して、1 つ以上の新しいプロパティを追加し、この機能を示します。
[サンプル データを挿入] ボタンを使用して、一部のサンプル データを Azure Cosmos DB テーブルに読み込みます。
上部のメニューの [Filter Results](結果のフィルター処理) 項目を選択すると、[Filter Results](結果のフィルター処理) ページが表示されます。 フィルター句を作成して Azure Cosmos DB for Table に渡す方法を示すため、このページでフィルター条件を入力します。
リソースをクリーンアップする
サンプル アプリケーションの使用が完了したら、この記事に関連するすべての Azure リソースを Azure アカウントから削除する必要があります。 このためには、リソース グループを削除します。
Azure portal を使用してリソース グループを削除するには、次の手順を実行します。
次のステップ
このクイック スタートでは、Azure Cosmos DB アカウントを作成し、データ エクスプローラーを使用してテーブルを作成し、アプリを実行する方法を説明しました。 これで、Table 用 API を使用してデータに対してクエリを実行できるようになりました。