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

[アーティクル]
11/19/2024

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

クライアントライブラリを使用して、次の手順を実行します。

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

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

ターンキーグローバル分散。
世界中の専用スループット。
99 パーセンタイルでの 1 桁ミリ秒の待機時間。
高可用性が保証されます。
セカンダリインデックスの自動作成。
Azure Tables クライアントライブラリは、コードを変更せず、Azure Table Storage または Azure Cosmos DB Table Service エンドポイントをシームレスにターゲットにすることができます。

主要なリンク:

はじめ

前提条件

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

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

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

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

JavaScript 用の Azure Tables クライアントライブラリをインストールする場合は、npm パッケージマネージャーを使用することをお勧めします。ターミナルウィンドウに次のように入力します。

npm install @azure/data-tables

`TableServiceClient` を認証する

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

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

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

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

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

JavaScript バンドル

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

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 スケールアプリケーションに対応できる構造化データの TB の格納
複雑な結合、外部キー、またはストアドプロシージャを必要とせず、高速アクセスのために正規化解除できるデータセットの格納
クラスター化インデックスを使用したデータの迅速なクエリ
OData プロトコルフィルター式を使用したデータへのアクセス

例

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

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

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

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

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

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

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

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

AzureNamedKeyCredential を使用した `TableServiceClient`

アカウント名とアカウントキーを引数として渡すことで、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
);

TokenCredential (AAD) を使用した `TableServiceClient`

Azure Tables は、ストレージエンドポイントを対象とする場合に Table Service への要求を 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
);

SAS トークンを使用した `TableServiceClient`

また、共有アクセス署名 (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)
);

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

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

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 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();

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

createTable 関数を呼び出す TableServiceClient インスタンスを使用してテーブルを作成できます。この関数は、パラメーターとして作成するテーブルの名前を受け取ります。テーブルが既に存在する場合、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 は、テーブル名をパラメーターとして受け取る TableClient 違いを持つ TableServiceClient と同様の方法で作成されます

`AzureNamedKeyCredential` を使用した `TableClient`

アカウント名とアカウントキーを引数として渡すことで、AzureNamedKeyCredential を使用して TableClient をインスタンス化できます。 (アカウント名とアカウントキーは、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);

`TokenCredential` を使用した `TableClient` (Azure Active Directory)

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
);

SAS トークンを使用した `TableClient`

共有アクセス署名 (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)
);

TokenCredential (AAD) を使用した `TableClient`

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
);

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

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

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 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();

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

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

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 とストレージエミュレーター

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 に手動で接続できます。ただし、Azurite が http エンドポイントで実行される場合は、allowInsecureConnection を手動で設定する必要があります。

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) に同意する必要があります。詳細については、https://cla.microsoft.comを参照してください。

プル要求を送信すると、CLA ボットは、CLA を提供し、PR を適切に装飾する必要があるかどうかを自動的に判断します (ラベル、コメントなど)。ボットによって提供される指示に従うだけです。これは、CLA を使用するすべてのリポジトリで 1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープンソースの行動規範を採用しています。詳細については、行動規範に関する FAQ を参照するか、その他の質問やコメントを opencode@microsoft.com にお問い合わせください。

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

インプレッション

次の方法で共有

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

はじめ

前提条件

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

`TableServiceClient` を認証する

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

JavaScript バンドル

CORS

主な概念

例

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

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

AzureNamedKeyCredential を使用した `TableServiceClient`

TokenCredential (AAD) を使用した `TableServiceClient`

SAS トークンを使用した `TableServiceClient`

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

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

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

`AzureNamedKeyCredential` を使用した `TableClient`

`TokenCredential` を使用した `TableClient` (Azure Active Directory)

SAS トークンを使用した `TableClient`

TokenCredential (AAD) を使用した `TableClient`

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

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

Azurite とストレージエミュレーター

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

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

トラブルシューティング

全般

伐採

次の手順

貢献

その他のリソース

次の方法で共有

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

はじめ

前提 条件

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

TableServiceClient を認証する

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

JavaScript バンドル

CORS

主な概念

例

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

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

AzureNamedKeyCredential を使用した TableServiceClient

TokenCredential (AAD) を使用した TableServiceClient

SAS トークンを使用した TableServiceClient

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

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

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

AzureNamedKeyCredential を使用した TableClient

TokenCredential を使用した TableClient (Azure Active Directory)

SAS トークンを使用した TableClient

TokenCredential (AAD) を使用した TableClient

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

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

Azurite とストレージ エミュレーター

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

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

トラブルシューティング

全般

伐採

次の手順

貢献

その他のリソース

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

前提条件

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

`TableServiceClient` を認証する

AzureNamedKeyCredential を使用した `TableServiceClient`

TokenCredential (AAD) を使用した `TableServiceClient`

SAS トークンを使用した `TableServiceClient`

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

`AzureNamedKeyCredential` を使用した `TableClient`

`TokenCredential` を使用した `TableClient` (Azure Active Directory)

SAS トークンを使用した `TableClient`

TokenCredential (AAD) を使用した `TableClient`

Azurite とストレージエミュレーター