JavaScript 用 Azure Tables クライアント ライブラリ - バージョン 13.2.2
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)
);
アカウント内のテーブルを一覧表示する
関数を呼び出すインスタンスを使用して、アカウント内のテーブルをTableServiceClient
listTables
一覧表示できます。 この関数は、 を使用して使用できる を 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 に "ストレージ テーブル データ共同作成者" または "ストレージ テーブル データ閲覧者" ロールが必要です。
パッケージを @azure/identity
使用すると、開発環境と運用環境の両方で要求をシームレスに承認できます。
Azure Storage での Azure AD 統合の詳細については、Azure.Identity README に関するページを参照してください。
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) を使用する
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 { 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
listEntities
一覧表示できます。 この関数は、 を 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 宛てに質問またはコメントをお送りください。
このライブラリに投稿する場合、コードをビルドしてテストする方法の詳細については、投稿ガイドを参照してください。
Azure SDK for JavaScript