JavaScript と TypeScript に Azure クライアントライブラリを使用する

[アーティクル]
03/11/2025

プログラムで 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 でのページングと反復子の詳細については、以下を参照してください。

Azure SDK for JavaScript/TypeScript の非同期反復子

実行時間の長い操作

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/core-lro

非同期操作の取り消し

@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 を使用して最近のリソース操作を一覧表示する

次の方法で共有

JavaScript と TypeScript に Azure クライアントライブラリを使用する

クライアントライブラリと REST API の違い

Azure クライアントと管理ライブラリ

Azure npm パッケージをインストールする

Azure npm パッケージのサンプルコードを使用する

認証資格情報を指定する

SDK クライアントを作成し、メソッドを呼び出す

結果の非同期ページング

実行時間の長い操作

非同期操作の取り消し

SDK からの詳細ログ

バンドル

次の手順

フィードバック

その他のリソース

次の方法で共有

JavaScript と TypeScript に Azure クライアント ライブラリを使用する

クライアント ライブラリと REST API の違い

Azure クライアントと管理ライブラリ

Azure npm パッケージをインストールする

Azure npm パッケージのサンプル コードを使用する

認証資格情報を指定する

SDK クライアントを作成し、メソッドを呼び出す

結果の非同期ページング

実行時間の長い操作

非同期操作の取り消し

SDK からの詳細ログ

バンドル

次の手順

フィードバック

その他のリソース

JavaScript と TypeScript に Azure クライアントライブラリを使用する

クライアントライブラリと REST API の違い

Azure npm パッケージのサンプルコードを使用する