JavaScript and TypeScript 向け Azure クライアントライブラリの使用

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

Azure サービスにプログラムでアクセスするには、JavaScript 用の Azure クライアントライブラリを使用します。通常、これらのライブラリは、azure-sdkによって発行された @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 から自由に利用できます。必要に応じて、個々の SDK をインストールします。各 SDK には TypeScript 定義が用意されています。

クライアントまたはブラウザーを使用する場合は、バンドルプロセスに Azure クライアントライブラリを追加する必要があります。

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

各パッケージには、パッケージの使用をすぐに開始するためのドキュメントが用意されています。使用する特定の 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 の例では、.pollUntildone() を使用して LRO が完了するまで待機してから続行する方法を示しています。

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 のバンドルについては、以下を参照してください。

次の方法で共有

JavaScript and TypeScript 向け Azure クライアントライブラリの使用

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

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

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

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

認証資格情報を指定する

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

結果の非同期ページング

長時間の操作

非同期操作の取り消し

SDK からの詳細ログ

バンドル

次のステップ

フィードバック

その他のリソース

次の方法で共有

JavaScript and TypeScript 向け Azure クライアント ライブラリの使用

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

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

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

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

認証資格情報を指定する

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

結果の非同期ページング

長時間の操作

非同期操作の取り消し

SDK からの詳細ログ

バンドル

次のステップ

フィードバック

その他のリソース

JavaScript and TypeScript 向け Azure クライアントライブラリの使用

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

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