クイックスタート: Node.js と Azure Cosmos DB を使って Table 用 API アプリを構築する

[アーティクル]
05/11/2023

適用対象: 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 アカウントを作成します。

手順	Screenshot
Azure portal で次の操作を行います。 Azure portal の上部の検索バーに「cosmos db」と入力します。検索バーの下に表示されるメニューの [サービス] で、「Azure Cosmos DB」とラベル付けされた項目を選択します。
[Azure Cosmos DB] ページで、[+作成] を選択します。
[API オプションの選択] ページで、[Azure テーブル] オプションを選択します。
[Azure Cosmos DB アカウントの作成] - [Azure テーブル] ページで、フォームに次のように入力します。 [リソースグループ] の下にある [新規作成] リンクを選択して、`rg-msdocs-tables-sdk-demo` という名前のストレージアカウントの新しいリソースグループを作成します。ストレージアカウントに、`cosmos-msdocs-tables-sdk-demo-XYZ` の名前を付けます。ここで XYZ は一意のアカウント名を作成するための任意のランダムな 3 文字です。 Azure Cosmos DB アカウント名の長さは 3 - 44 文字で、小文字、数字、またはハイフン (-) 文字のみを使用できます。ストレージアカウントのリージョンを選択します。 [標準] のパフォーマンスを選択します。 [容量モード] で、この例の [プロビジョニングされたスループット] を選択します。この例の [Free レベル割引の適用] で [適用] を選択します。画面の下部にある [確認と作成] ボタンを選択し、概要画面で [作成] を選択して、Azure Cosmos DB アカウントを作成します。このプロセスには数分かかることがあります。

Azure Cosmos DB アカウントを作成するには az cosmosdb create コマンドを使用します。 Azure Cosmos DB 内でテーブルストレージを有効にするため、--capabilities EnableTable オプションを含める必要があります。すべての Azure リソースが 1 つのリソースグループに含まれているようにする必要があるため、次のコードスニペットでは、Azure Cosmos DB アカウントのリソースグループも作成されます。

Azure Cosmos DB アカウント名の長さは 3 ～ 44 文字で、小文字、数字、ハイフン (-) 文字のみを使用できます。 Azure Cosmos DB アカウント名は、Azure 全体で一意である必要があります。

Azure CLI コマンドは、Azure Cloud Shell で、または Azure CLI がインストールされているワークステーション上で実行できます。

通常、Azure Cosmos DB アカウントの作成プロセスが完了するまでには数分かかります。

LOCATION='eastus'
RESOURCE_GROUP_NAME='rg-msdocs-tables-sdk-demo'
COSMOS_ACCOUNT_NAME='cosmos-msdocs-tables-sdk-demo-123'    # change 123 to a unique set of characters for a unique name
COSMOS_TABLE_NAME='WeatherData'

az group create \
    --location $LOCATION \
    --name $RESOURCE_GROUP_NAME

az cosmosdb create \
    --name $COSMOS_ACCOUNT_NAME \
    --resource-group $RESOURCE_GROUP_NAME \
    --capabilities EnableTable

Azure Cosmos DB アカウントを作成するには、New-AzCosmosDBAccount コマンドレットを使用します。 Azure Cosmos DB 内でテーブルストレージを有効にするため、-ApiKind "Table" オプションを含める必要があります。すべての Azure リソースが 1 つのリソースグループに含まれているようにする必要があるため、次のコードスニペットでは、Azure Cosmos DB アカウントのリソースグループも作成されます。

Azure PowerShell コマンドは、Azure Cloud Shell、または Azure PowerShell がインストールされているワークステーションで実行できます。

通常、Azure Cosmos DB アカウントの作成プロセスが完了するまでには数分かかります。

$location = 'eastus'
$resourceGroupName = 'rg-msdocs-tables-sdk-demo'
$cosmosAccountName = 'cosmos-msdocs-tables-sdk-demo-123'  # change 123 to a unique set of characters for a unique name

# Create a resource group
New-AzResourceGroup `
    -Location $location `
    -Name $resourceGroupName

# Create an Azure Cosmos DB 
New-AzCosmosDBAccount `
    -Name $cosmosAccountName `
    -ResourceGroupName $resourceGroupName `
    -Location $location `
    -ApiKind "Table"

2 - テーブルを作成する

次に、アプリケーションで使用するテーブルを Azure Cosmos DB アカウント内に作成する必要があります。従来のデータベースとは異なり、指定する必要があるのはテーブルの名前のみであり、テーブルのプロパティ (列) は指定する必要はありません。データがテーブルに読み込まれると、必要に応じてプロパティ (列) が自動的に作成されます。

Azure portal で次の手順を実行して、Azure Cosmos DB アカウント内にテーブルを作成します。

手順	Screenshot
次の Azure portal で、Azure Cosmos DB アカウントの概要ページに移動します。 Azure Cosmos DB アカウントの概要ページに移動するには、上部の検索バーに Azure Cosmos DB アカウントの名前 (cosmos-msdocs-tables-sdk-demo-XYZ) を入力し、リソース見出しの下を確認します。ご自分の Azure Cosmos DB アカウントの名前を選択して概要ページに移動します。
[概要] ページで、[+テーブルの追加] を選択します。 [新しいテーブル] ダイアログがページの右側からスライドアウトします。
[新しいテーブル] ダイアログで、次のようにフォームに記入します。テーブル ID として「WeatherData」という名前を入力します。これがテーブルの名前になります。この例では "テーブルスループット (自動スケール) " の下で [手動] を選択します。推定 RU/秒で既定値の 400 を使用します。 [OK] ボタンを選択してテーブルを作成します。

Azure Cosmos DB にテーブルを作成するには az cosmosdb table create コマンドを使用します。

COSMOS_TABLE_NAME='WeatherData'

az cosmosdb table create \
    --account-name $COSMOS_ACCOUNT_NAME \
    --resource-group $RESOURCE_GROUP_NAME \
    --name $COSMOS_TABLE_NAME \
    --throughput 400

Azure Cosmos DB にテーブルを作成するには New-AzCosmosDBTable コマンドレットを使用します。

$cosmosTableName = 'WeatherData'

# Create the table for the application to use
New-AzCosmosDBTable `
    -Name $cosmosTableName `
    -AccountName $cosmosAccountName `
    -ResourceGroupName $resourceGroupName

3 - Azure Cosmos DB 接続文字列を取得する

Azure Cosmos DB 内のテーブルにアクセスするには、アプリに CosmosDB Storage アカウントのテーブル接続文字列が必要です。この接続文字列は、Azure portal、Azure CLI、または Azure PowerShell を使用して取得できます。

手順	Screenshot
Azure Cosmos DB アカウントページの左側にある [設定] ヘッダーの下で [接続文字列] という名前のメニュー項目を見つけて選択します。 Azure Cosmos DB アカウントの接続文字列を取得できるページが表示されます。
[プライマリ接続文字列] の値をコピーして、アプリケーションで使用します。

Azure CLI を使用して主テーブルストレージ接続文字列を取得するには、オプション --type connection-strings を指定した az cosmosdb keys list コマンドを使用します。このコマンドは、JMESPath クエリを使用して主テーブル接続文字列のみを表示します。

# This gets the primary Table connection string
az cosmosdb keys list \
    --type connection-strings \
    --resource-group $RESOURCE_GROUP_NAME \
    --name $COSMOS_ACCOUNT_NAME \
    --query "connectionStrings[?description=='Primary Table Connection String'].connectionString" \
    --output tsv

Azure PowerShell を使用して主テーブルストレージ接続文字列を取得するには、Get-AzCosmosDBAccountKey コマンドレットを使用します。

# This gets the primary Table connection string
$(Get-AzCosmosDBAccountKey `
    -ResourceGroupName $resourceGroupName `
    -Name $cosmosAccountName `
    -Type "ConnectionStrings")."Primary Table Connection String"

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 を使用してリソースグループを削除するには、次の手順を実行します。

手順	Screenshot
リソースグループに進むには、検索バーにリソースグループの名前を入力します。次に [リソースグループ] タブで、リソースグループの名前を選択します。
リソースグループページの上部のツールバーから [リソースグループの削除] を選択します。
リソースグループの削除を確認するダイアログが画面の右側に表示されます。テキストボックスにリソースグループの名前を完全に入力し、指示に従って削除を確認します。ページ下部の [削除] ボタンを選択します。

Azure CLI を使用してリソースグループを削除するには、削除するリソースグループの名前を指定した az group delete コマンドを使用します。リソースグループを削除すると、そのリソースグループに含まれているすべての Azure リソースも削除されます。

az group delete --name $RESOURCE_GROUP_NAME

Azure PowerShell を使用してリソースグループを削除するには、削除するリソースグループの名前を指定した Remove-AzResourceGroup コマンドを使用します。リソースグループを削除すると、そのリソースグループに含まれているすべての Azure リソースも削除されます。

Remove-AzResourceGroup -Name $resourceGroupName

次のステップ

このクイックスタートでは、Azure Cosmos DB アカウントを作成し、データエクスプローラーを使用してテーブルを作成し、アプリを実行する方法を説明しました。これで、Table 用 API を使用してデータに対してクエリを実行できるようになりました。

Table 用 API を使って Azure Cosmos DB に対するクエリを実行する