JavaScript 用 Azure Tables クライアントライブラリ - バージョン 13.2.2

[アーティクル]
04/10/2023

Azure Tables は、構造化された NoSQL データを格納するクラウドベースのサービスであり、キー/属性ストアにスキーマレス設計を提供します。テーブルストレージを使用すると、開発者は Azure クラウドのすべての最良の部分で柔軟性とスケーラビリティを実現できます。

以下の場合にクライアントライブラリを使用します。

テーブルの作成/削除
エンティティのクエリ/作成/読み取り/更新/削除

Azure Cosmos DB には、Azure Table Storage 用に記述され、次のような Premium 機能が必要なアプリケーション用の Table API が用意されています。

ターンキーグローバル配信。
世界規模での専用スループット。
99 パーセンタイルで 10 ミリ秒未満の待ち時間。
高可用性の保証。
自動セカンダリインデックス作成。
Azure Tables クライアントライブラリは、コードを変更せず、Azure Table Storage または Azure Cosmos DB テーブルサービスエンドポイントをシームレスにターゲットにすることができます。

主要リンク:

作業の開始

前提条件

現在サポートされている環境:

LTS バージョンのNode.js
Safari、Chrome、Edge、Firefox の最新バージョン

このパッケージを使用するには、 Azure サブスクリプションとストレージアカウントまたは Azure CosmosDB データベースが必要です。

`@azure/data-tables` パッケージのインストール

JavaScript 用の Azure Tables クライアントライブラリをインストールする推奨される方法は、npm パッケージマネージャーを使用することです。ターミナルウィンドウに次のように入力します。

npm install @azure/data-tables

を認証する `TableServiceClient`

Azure Tables では、認証のいくつかの方法がサポートされています。 Azure Tables サービスを操作するには、Tables クライアント TableServiceClient のインスタンスを作成する必要があります。たとえば TableClient 、などです。認証の詳細については、を作成するためのTableServiceClientサンプルを参照してください。

注: Azure Active Directory (AAD) は、Azure Storage アカウントでのみサポートされています。

共有キーを持つサービスクライアント
Shared Access Signature を使用したサービスクライアント
TokenCredential (AAD) を使用したサービスクライアント
共有キーを持つテーブルクライアント
Shared Access Signature を使用したテーブルクライアント
TokenCredential (AAD) を使用したテーブルクライアント

以下の機能、インターフェイス、クラス、または関数は、Node.jsでのみ使用できます

アカウント名とアカウントキーに基づく共有キーの承認
- AzureNamedKeyCredential
- アカウント接続文字列。

JavaScript バンドル

ブラウザーでこのクライアントライブラリを使用するには、まず bundler を使用する必要があります。これを行う方法の詳細については、バンドルに関するドキュメントを参照してください。

CORS

ブラウザー用に開発する必要がある場合は、ストレージアカウントのクロスオリジンリソース共有 (CORS) ルールを設定する必要があります。 Azure portalに移動してAzure Storage Explorer、ストレージアカウントを見つけ、BLOB/キュー/ファイル/テーブルサービスの新しい CORS ルールを作成します。

たとえば、デバッグ用に次の CORS 設定を作成できます。ただし、運用環境の要件に合わせて設定を慎重にカスタマイズしてください。

許可される配信元: *
使用できる動詞: DELETE、GET、HEAD、MERGE、POST、OPTIONS、PUT
許可されるヘッダー: *
公開されているヘッダー: *
最大経過時間 (秒): 86400

主要な概念

TableServiceClient - テーブルの作成、一覧表示、削除など、Table Service レベルで対話する関数を提供するクライアント
TableClient - テーブル内のエンティティの作成、一覧表示、削除などのエンティティレベルで対話する関数を提供するクライアント。
Table - テーブルには、エンティティのコレクションとしてデータが格納されます。
Entity - エンティティは行に似ています。エンティティには、プライマリキーと一連のプロパティがあります。プロパティは名前と型指定された値のペアであり、列に似ています。

Table service の一般的な使用法を次に示します。

Web スケールアプリケーションにサービスを提供できる数テラバイトの構造化データを格納する
複雑な結合、外部キー、またはストアドプロシージャを必要とせず、高速アクセスのために正規化解除できるデータセットの格納
クラスター化インデックスを使用して高速なデータのクエリを実行する
OData プロトコルフィルター式を使用したデータへのアクセス

例

パッケージをインポートする
テーブルサービスクライアントを作成する
- アカウント内のテーブルを一覧表示する
- 新しいテーブルを作成する
テーブルクライアントを作成する
- テーブル内のエンティティを一覧表示する
- 新しいエンティティを作成してテーブルに追加する

パッケージをインポートする

クライアントを使用するには、ファイルにパッケージをインポートします。

const AzureTables = require("@azure/data-tables");

または、必要な型のみを選択的にインポートします。

const { TableServiceClient, AzureNamedKeyCredential } = require("@azure/data-tables");

Table service クライアントを作成する

には TableServiceClient 、テーブルサービスへの URL とアクセス資格情報が必要です。また、必要に応じて、パラメーターの一部の設定を options 受け入れます。

`TableServiceClient` AzureNamedKeyCredential を使用する

account-name と account-key を引数として渡すことで、を使用AzureNamedKeyCredentialしてをインスタンス化TableServiceClientできます。 (アカウント名とアカウントキーは、Azure portal から取得できます)。[NODE.JS ランタイムでのみ使用できます]

const { TableServiceClient, AzureNamedKeyCredential } = require("@azure/data-tables");

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const serviceClient = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  credential
);

`TableServiceClient` TokenCredential (AAD) を使用する

Azure Tables では、ストレージエンドポイントを対象とする場合に Table サービスへの要求を ID ベースで認証するために、Azure Active Directory (Azure AD) との統合が提供されます。 Azure AD では、ロールベースのアクセス制御 (RBAC) を使用して、Azure Table リソースへのアクセス権をユーザー、グループ、またはアプリケーションに付与できます。

を使用 TokenCredentialしてテーブルリソースにアクセスするには、認証された ID に "ストレージテーブルデータ共同作成者" または "ストレージテーブルデータ閲覧者" ロールが必要です。

パッケージを @azure/identity 使用すると、開発環境と運用環境の両方で要求をシームレスに承認できます。 Azure Storage での Azure AD 統合の詳細については、Azure.Identity README に関するページを参照してください。

const { TableServiceClient } = require("@azure/data-tables");
const { DefaultAzureCredential } = require("@azure/identity");

// DefaultAzureCredential expects the following three environment variables:
// - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
// - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
// - AZURE_CLIENT_SECRET: The client secret for the registered application
const credential = new DefaultAzureCredential();
const account = "<account name>";

const clientWithAAD = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  credential
);

`TableServiceClient` SAS トークンを使用する

また、Shared Access Signature (SAS) を使用してをインスタンス化 TableServiceClient することもできます。 SAS トークンは、Azure Portal から取得できます。

const { TableServiceClient, AzureSASCredential } = require("@azure/data-tables");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";

const serviceClientWithSAS = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  new AzureSASCredential(sas)
);

アカウント内のテーブルを一覧表示する

関数を呼び出すインスタンスを使用して、アカウント内のテーブルをTableServiceClientlistTables一覧表示できます。この関数は、を使用して使用できるを PageableAsyncIterator 返します。 for-await-of

const { TableServiceClient, AzureNamedKeyCredential } = require("@azure/data-tables");

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const serviceClient = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  credential
);

async function main() {
  let tablesIter = serviceClient.listTables();
  let i = 1;
  for await (const table of tablesIter) {
    console.log(`Table${i}: ${table.name}`);
    i++;
    // Output:
    // Table1: testTable1
    // Table1: testTable2
    // Table1: testTable3
    // Table1: testTable4
    // Table1: testTable5
  }
}

main();

新しいテーブルを作成する

関数を呼び出すインスタンスを TableServiceClient 使用してテーブルを createTable 作成できます。この関数は、作成するテーブルの名前をパラメーターとして受け取ります。テーブルが createTable 既に存在する場合、エラーはスローされません。

const { TableServiceClient, AzureNamedKeyCredential } = require("@azure/data-tables");

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const serviceClient = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  credential
);

async function main() {
  const tableName = `newtable`;
  // If the table 'newTable' already exists, createTable doesn't throw
  await serviceClient.createTable(tableName);
}

main();

テーブルの作成時にテーブルが既に存在するかどうかをテストする方法を示すサンプルを次に示します。

const { TableServiceClient, AzureNamedKeyCredential } = require("@azure/data-tables");

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const serviceClient = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  credential
);

async function main() {
  const tableName = `newtable${new Date().getTime()}`;
  await serviceClient.createTable(tableName, {
    onResponse: (response) => {
      if (response.status === 409) {
        console.log(`Table ${tableName} already exists`);
      }
    }
  });
}

main();

テーブルクライアントを作成する

TableClientは、と同様の方法TableServiceClientで作成され、テーブル名をパラメーターとして受け取る違いTableClientがあります。

`AzureNamedKeyCredential` を含む `TableClient`

account-name と account-key を TableClient 引数として渡すことで、を使用 AzureNamedKeyCredential してをインスタンス化できます。 (アカウント名とアカウントキーは、Azure portal から取得できます)。[NODE.JS ランタイムでのみ使用可能]

const { TableClient, AzureNamedKeyCredential } = require("@azure/data-tables");

// Enter your storage account name and shared key
const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

// Use AzureNamedKeyCredential with storage account and account key
// AzureNamedKeyCredential is only available in Node.js runtime, not in browsers
const credential = new AzureNamedKeyCredential(account, accountKey);
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

`TableClient` と `TokenCredential` (Azure Active Directory)

Azure Tables では、ストレージエンドポイントをターゲットとする場合に Table サービスへの要求を ID ベースで認証するために、Azure Active Directory (Azure AD) との統合が提供されます。 Azure AD では、ロールベースのアクセス制御 (RBAC) を使用して、Azure Table リソースへのアクセスをユーザー、グループ、またはアプリケーションに付与できます。

を使用して TokenCredentialテーブルリソースにアクセスするには、認証された ID に "ストレージテーブルデータ共同作成者" または "ストレージテーブルデータ閲覧者" ロールが必要です。

const { TableClient } = require("@azure/data-tables");
const { DefaultAzureCredential } = require("@azure/identity");

// DefaultAzureCredential expects the following three environment variables:
// - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
// - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
// - AZURE_CLIENT_SECRET: The client secret for the registered application
const credential = new DefaultAzureCredential();
const account = "<account name>";
const tableName = "<tableName>";

const clientWithAAD = new TableClient(
  `https://${account}.table.core.windows.net`,
  tableName,
  credential
);

`TableClient` SAS トークンを使用する

Shared Access Signature (SAS) を使用してをインスタンス化 TableClient できます。 SAS トークンは、Azure Portal から取得できます。

const { TableClient, AzureSASCredential } = require("@azure/data-tables");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const tableName = "<tableName>";

const clientWithSAS = new TableClient(
  `https://${account}.table.core.windows.net`,
  tableName,
  new AzureSASCredential(sas)
);

`TableClient` TokenCredential (AAD) を使用する

const { TableClient } = require("@azure/data-tables");
const { DefaultAzureCredential } = require("@azure/identity");

// DefaultAzureCredential expects the following three environment variables:
// - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
// - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
// - AZURE_CLIENT_SECRET: The client secret for the registered application
const credential = new DefaultAzureCredential();
const account = "<account name>";
const tableName = "<tableName>";

const clientWithAAD = new TableClient(
  `https://${account}.table.core.windows.net`,
  tableName,
  credential
);

テーブル内のエンティティを一覧表示する

関数を呼び出すインスタンスを使用して、テーブル内のエンティティをTableClientlistEntities一覧表示できます。この関数は、を PageableAsyncIterator 使用して使用できるを返します。 for-await-of

const { TableClient, AzureNamedKeyCredential } = require("@azure/data-tables");

const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

async function main() {
  let entitiesIter = client.listEntities();
  let i = 1;
  for await (const entity of entitiesIter) {
    console.log(`Entity${i}: PartitionKey: ${entity.partitionKey} RowKey: ${entity.rowKey}`);
    i++;
    // Output:
    // Entity1: PartitionKey: P1 RowKey: R1
    // Entity2: PartitionKey: P2 RowKey: R2
    // Entity3: PartitionKey: P3 RowKey: R3
    // Entity4: PartitionKey: P4 RowKey: R4
  }
}

main();

新しいエンティティを作成してテーブルに追加する

関数を呼び出すインスタンスを使用して TableClient 、テーブルに新しい Entity を createEntity 作成できます。この関数は、挿入するエンティティをパラメーターとして受け取ります。エンティティにはとがrowKey含まれているpartitionKey必要があります。

const { TableClient, AzureNamedKeyCredential } = require("@azure/data-tables");

const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

async function main() {
  const testEntity = {
    partitionKey: "P1",
    rowKey: "R1",
    foo: "foo",
    bar: 123
  };
  await client.createEntity(testEntity);
}

main();

Azurite と Storage Emulator

Azure Tables Client SDK は、Azure Storage と Tables API 互換のサーバーエミュレーターである Azurite でも動作します。使用を開始する方法については、(Azurite リポジトリ) を参照してください。

接続文字列ショートカットを使用して Azurite に接続する

アプリケーションから Azurite に接続する最も簡単な方法は、ショートカット UseDevelopmentStorage=trueを参照する接続文字列を構成することです。ショートカットは、エミュレーターの完全な接続文字列と同じです。この接続文字列では、各 Azure Storage サービスのアカウント名、アカウントキー、エミュレーターエンドポイントを指定します (詳細を参照)。このショートカットを使用すると、Azure Tables Client SDK によって、既定の接続文字列と allowInsecureConnection クライアントオプションが設定されます。

import { TableClient } from "@azure/data-tables";

const connectionString = "UseDevelopmentStorage=true";
const client = TableClient.fromConnectionString(connectionString, "myTable");

接続文字列ショートカットなしで Azurite に接続する

サービス URL AzureNamedKeyCredential やカスタム接続文字列を指定することで、接続文字列ショートカットを使用せずに azurite に手動で接続できます。ただし、 allowInsecureConnection Azurite がエンドポイントで実行される場合は、手動で設定する http 必要があります。

import { TableClient, AzureNamedKeyCredential } from "@azure/data-tables";

const client = new TableClient(
  "<Azurite-http-table-endpoint>",
  "myTable",
  new AzureNamedKeyCredential("<Azurite-account-name>", "<Azurite-account-key>"),
  { allowInsecureConnection: true }
);

トラブルシューティング

全般

Javascript/Typescript SDK を使用して Tables サービスを操作する場合、サービスによって返されるエラーは、REST API 要求に対して返されるのと同じ HTTP 状態コードに対応します。 Storage Table Service エラーコード

ログの記録

ログの記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、環境変数 AZURE_LOG_LEVEL を info に設定します。または、@azure/logger で setLogLevel を呼び出して、実行時にログ記録を有効にすることもできます。

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

次のステップ

その他のコードサンプルが近日公開予定問題#10531

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。詳細については、 https://cla.microsoft.com を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。ボットによって提供される手順にそのまま従ってください。この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープンソースの倫理規定を採用しています。詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

このライブラリに投稿する場合、コードをビルドしてテストする方法の詳細については、投稿ガイドを参照してください。

インプレッション数

JavaScript 用 Azure Tables クライアントライブラリ - バージョン 13.2.2

作業の開始

前提条件

`@azure/data-tables` パッケージのインストール

を認証する `TableServiceClient`

以下の機能、インターフェイス、クラス、または関数は、Node.jsでのみ使用できます

JavaScript バンドル

CORS

主要な概念

例

パッケージをインポートする

Table service クライアントを作成する

`TableServiceClient` AzureNamedKeyCredential を使用する

`TableServiceClient` TokenCredential (AAD) を使用する

`TableServiceClient` SAS トークンを使用する

アカウント内のテーブルを一覧表示する

新しいテーブルを作成する

テーブルクライアントを作成する

`AzureNamedKeyCredential` を含む `TableClient`

`TableClient` と `TokenCredential` (Azure Active Directory)

`TableClient` SAS トークンを使用する

`TableClient` TokenCredential (AAD) を使用する

テーブル内のエンティティを一覧表示する

新しいエンティティを作成してテーブルに追加する

Azurite と Storage Emulator

接続文字列ショートカットを使用して Azurite に接続する

接続文字列ショートカットなしで Azurite に接続する

トラブルシューティング

全般

ログの記録

次のステップ

共同作成

フィードバック

その他のリソース

JavaScript 用 Azure Tables クライアント ライブラリ - バージョン 13.2.2

作業の開始

前提条件

@azure/data-tables パッケージのインストール

を認証する TableServiceClient

以下の機能、インターフェイス、クラス、または関数は、Node.jsでのみ使用できます

JavaScript バンドル

CORS

主要な概念

例

パッケージをインポートする

Table service クライアントを作成する

TableServiceClient AzureNamedKeyCredential を使用する

TableServiceClient TokenCredential (AAD) を使用する

TableServiceClient SAS トークンを使用する

アカウント内のテーブルを一覧表示する

新しいテーブルを作成する

テーブル クライアントを作成する

AzureNamedKeyCredential を含む TableClient

TableClient と TokenCredential (Azure Active Directory)

TableClient SAS トークンを使用する

TableClient TokenCredential (AAD) を使用する

テーブル内のエンティティを一覧表示する

新しいエンティティを作成してテーブルに追加する

Azurite と Storage Emulator

接続文字列ショートカットを使用して Azurite に接続する

接続文字列ショートカットなしで Azurite に接続する

トラブルシューティング

全般

ログの記録

次のステップ

共同作成

フィードバック

その他のリソース

JavaScript 用 Azure Tables クライアントライブラリ - バージョン 13.2.2

`@azure/data-tables` パッケージのインストール

を認証する `TableServiceClient`

`TableServiceClient` AzureNamedKeyCredential を使用する

`TableServiceClient` TokenCredential (AAD) を使用する

`TableServiceClient` SAS トークンを使用する

テーブルクライアントを作成する

`AzureNamedKeyCredential` を含む `TableClient`

`TableClient` と `TokenCredential` (Azure Active Directory)

`TableClient` SAS トークンを使用する

`TableClient` TokenCredential (AAD) を使用する