JavaScript と TypeScript に Azure クライアント ライブラリを使用する
プログラムで Azure サービスにアクセスするには、JavaScript 用の Azure クライアント ライブラリを使用します。 通常、これらのライブラリは、microsoft1esによって発行された @azure npm パッケージ スコープでスコープされます。
クライアント ライブラリと REST API の違い
次の情報を使用して、どの種類のアクセスを使用するかを理解します。
- Azure クライアント ライブラリ は、Azure サービスにアクセスするための推奨される方法です。 これらのライブラリは、認証、再試行、ログ記録などのクラウドベースの Azure プラットフォーム REST 要求を管理するために必要な定型コードを抽象化します。
- Azure REST API は、次のような場合に推奨される方法です。
- Azure クライアント ライブラリを使用できないプレビュー サービスの操作。 コードをプレビューと見なします。これは、サービスがクライアント ライブラリで一般公開されている場合に更新する必要があります。
- SDK 全体で 1 つの REST API を使用したくないか、HTTP 要求をより詳細に制御する必要があるため、REST 呼び出しを直接行いたい。
Azure クライアントと管理ライブラリ
Azure クライアント ライブラリ リリース は、次の方法で利用できます。
- 管理: 管理ライブラリを使用すると、Azure リソースを作成および管理できます。 これらのライブラリは、パッケージ名に
arm-
することで認識できます。arm
という用語は、Azure Resource Manager を示します。 - クライアント: Azure リソースが既に存在する場合は、クライアント ライブラリを使用して使用し、操作します。
- 各パッケージ README.md には、ドキュメントとサンプルが含まれています。
Azure npm パッケージをインストールする
Azure クライアント ライブラリは、NPM と Yarnから自由に利用できます。 必要に応じて個々の SDK をインストールします。 各 SDK には TypeScript 定義が用意されています。
クライアント/ブラウザーを使用するには、Azure クライアント ライブラリを バンドル プロセスに追加する必要があります。
Azure npm パッケージのサンプル コードを使用する
各パッケージには、パッケージの使用をすぐに開始するためのドキュメントが含まれています。 使用方法については、使用する特定のパッケージのドキュメントを参照してください。
認証資格情報を指定する
Azure クライアント ライブラリには、Azure プラットフォーム に対する認証に資格情報が必要です。 @azure/identity によって提供される資格情報クラスには、いくつかの利点があります。
- 迅速な導入
- 最も安全な方法
- 認証メカニズムをコードから分離します。 これにより、資格情報が異なる場合に、ローカルと Azure プラットフォームで同じコードを使用できます。
- 複数のメカニズムを使用できるように、チェーン認証を提供します。
SDK クライアントを作成し、メソッドを呼び出す
プログラムによって資格情報を作成したら、その資格情報を Azure クライアントに渡します。 クライアントには、サブスクリプション ID やサービス エンドポイントなどの追加情報が必要な場合があります。 これらの値は、リソースの Azure portal で使用できます。
次のコード例では、DefaultAzureCredential と arm
サブスクリプション クライアント ライブラリを使用して、この資格情報が読み取りアクセスできるサブスクリプションを一覧表示します。
const {
ClientSecretCredential,
DefaultAzureCredential,
} = require("@azure/identity");
const { SubscriptionClient } = require("@azure/arm-subscriptions");
require("dotenv").config();
let credentials = null;
const tenantId = process.env["AZURE_TENANT_ID"];
const clientId = process.env["AZURE_CLIENT_ID"];
const secret = process.env["AZURE_CLIENT_SECRET"];
if (process.env.NODE_ENV && process.env.NODE_ENV === "production") {
// production
credentials = new DefaultAzureCredential();
} else {
// development
if (tenantId && clientId && secret) {
console.log("development");
credentials = new ClientSecretCredential(tenantId, clientId, secret);
} else {
credentials = new DefaultAzureCredential();
}
}
async function listSubscriptions() {
try {
// use credential to authenticate with Azure SDKs
const client = new SubscriptionClient(credentials);
// get details of each subscription
for await (const item of client.subscriptions.list()) {
const subscriptionDetails = await client.subscriptions.get(
item.subscriptionId
);
/*
Each item looks like:
{
id: '/subscriptions/123456',
subscriptionId: '123456',
displayName: 'YOUR-SUBSCRIPTION-NAME',
state: 'Enabled',
subscriptionPolicies: {
locationPlacementId: 'Internal_2014-09-01',
quotaId: 'Internal_2014-09-01',
spendingLimit: 'Off'
},
authorizationSource: 'RoleBased'
},
*/
console.log(subscriptionDetails);
}
} catch (err) {
console.error(JSON.stringify(err));
}
}
listSubscriptions()
.then(() => {
console.log("done");
})
.catch((ex) => {
console.log(ex);
});
結果の非同期ページング
SDK メソッドは、非同期の結果を可能にするために、PagedAsyncIterableIterator 非同期反復子を返すことができます。 結果では、ページングトークンと継続トークンを使用して結果セットを分割できます。
次の JavaScript の例 は、非同期ページングを示しています。 コードは、デバッグでサンプル コードを実行するときにプロセスをすばやく視覚的に示すために、人為的に短いページング サイズを 2 に設定します。
const { BlobServiceClient } = require("@azure/storage-blob");
const blobAccountConnectionString = "REPLACE-WITH-YOUR-STORAGE-CONNECTION-STRING";
const blobAccountContainerName = "REPLACE-WITH-YOUR-STORAGE-CONTAINER-NAME";
const pageSize = 2;
const list = async () => {
console.log(`List`);
let continuationToken = "";
let currentPage = 1;
let containerClient=null;
let currentItem = 1;
// Get Blob Container - need to have items in container before running this code
const blobServiceClient = BlobServiceClient.fromConnectionString(blobAccountConnectionString);
containerClient = blobServiceClient.getContainerClient(blobAccountContainerName);
do {
// Get Page of Blobs
iterator = (continuationToken != "")
? containerClient.listBlobsFlat().byPage({ maxPageSize: pageSize, continuationToken })
: containerClient.listBlobsFlat().byPage({ maxPageSize: pageSize });
page = (await iterator.next()).value;
// Display list
if (page.segment?.blobItems) {
console.log(`\tPage [${currentPage}] `);
for (const blob of page.segment.blobItems) {
console.log(`\t\tItem [${currentItem++}] ${blob.name}`);
}
};
// Move to next page
continuationToken = page.continuationToken;
if (continuationToken) {
currentPage++;
}
} while (continuationToken != "")
}
list(() => {
console.log("done");
}).catch((ex) =>
console.log(ex)
);
Azure でのページングと反復子の詳細については、以下を参照してください。
実行時間の長い操作
SDK メソッドは、実行時間の長い操作 (LRO) の raw 応答を返すことができます。 この応答には、次のような情報が含まれます。
- 要求が完了しました
- 要求はまだ処理中です
次の JavaScript の例 は、続行する前に LRO が完了するのを待機する方法を示しています (.pollUntildone()
)。
const { BlobServiceClient } = require("@azure/storage-blob");
const blobAccountConnectionString = "REPLACE-WITH-YOUR-STORAGE-CONNECTION-STRING";
const blobAccountContainerName = `test-${Date.now().toString()}`;
const files = [
{
"url": "https://github.com/Azure/azure-sdk-for-js/blob/main/README.md",
"fileName": "README.md"
},
{
"url": "https://github.com/Azure/azure-sdk-for-js/blob/main/gulpfile.ts",
"fileName": "gulpfile.ts"
},
{
"url": "https://github.com/Azure/azure-sdk-for-js/blob/main/rush.json",
"fileName": "rush.json"
},
{
"url": "https://github.com/Azure/azure-sdk-for-js/blob/main/package.json",
"fileName": "package.json"
},
{
"url": "https://github.com/Azure/azure-sdk-for-js/blob/main/tsdoc.json",
"fileName": "tsdoc.json"
},
];
const upload = async() => {
// get container client
const blobServiceClient = BlobServiceClient.fromConnectionString(blobAccountConnectionString);
// get container's directory client
const containerClient = blobServiceClient.getContainerClient(blobAccountContainerName);
files.forEach(async(file) =>{
await (
await containerClient
.getBlobClient(file.fileName)
.beginCopyFromURL(file.url)
).pollUntilDone();
})
}
upload(() => {
console.log("done");
}).catch((ex) =>
console.log(ex)
);
Azure での実行時間の長い操作の詳細については、以下をご覧ください。
非同期操作の取り消し
@azure/abort-controller パッケージには、AbortController クラスと AbortSignal クラスが用意されています。 AbortController を使用して AbortSignal を作成し、Azure SDK 操作に渡して保留中の作業を取り消すことができます。 Azure SDK の操作は次のとおりです。
- 独自のロジックに基づいて中止される
- タイム アウト制限に基づいて中止
- 親タスクのシグナルに基づいて中止される
- 親タスクのシグナルまたはタイム アウト制限に基づいて中止
詳細情報:
- Azure SDK for JavaScript/TypeScript で中止シグナルを使用して操作を取り消す方法
SDK からの詳細ログ
Azure SDK を使用している場合は、アプリケーションをデバッグする必要がある場合があります。
ビルド時 でログ記録を有効にするには、AZURE_LOG_LEVEL環境変数を
info
に設定します。実行時のログを有効にするには、@azure/logger パッケージを使用します。
import { setLogLevel } from "@azure/logger"; setLogLevel("info");
バンドル
Azure SDK とのバンドルについて説明します。
次の手順
- @azure/arm-subscriptions SDK のサブスクリプション リスト
- @azure/arm-monitor SDK を使用して最近のリソース操作を一覧表示する