JavaScript および TypeScript 用の Azure SDK を使用する

[アーティクル]
02/01/2024

Azure サービスにプログラムでアクセスするには、JavaScript 用の Azure SDK を使用します。通常、これらの SDK は、azure-sdk によって発行された @azure npm パッケージスコープでスコープが設定されています。

SDK と REST API の違い

どちらの種類のアクセスメカニズムをいつ使用するかを理解するには、次の情報を使用してください。

Azure SDK は、Azure サービスにアクセスする場合に推奨される方法です。 Azure SDK は、認証、再試行、ログ記録などのクラウドベースの Azure プラットフォーム REST 要求を管理するために必要な定型コードを抽象化します。
次の場合は、Azure REST API が推奨される方法です。
- Azure SDK を使用できないプレビューサービスを利用する。コードをプレビューと見なしてください。サービスが SDK と共に一般提供されたら、更新する必要があります。
- SDK 全体で 1 つの REST API を使用したくない、または HTTP 要求をより詳細に制御する必要があるために、REST 呼び出しを直接行う必要がある。

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

Azure SDK のリリースは、以下の形で提供されています。

管理 SDK: 管理ライブラリを使用すると、Azure Resource Manager (ARM) を使用して Azure リソースをプロビジョニングおよび管理できます。これらのライブラリは、パッケージ名の @azure/arm- により認識できます。
- ドキュメントとコードサンプル
クライアント SDK: Azure リソースが既に存在する場合は、クライアントライブラリを使用してそれを使用し、操作します。
- 各パッケージの README.md にドキュメントとサンプルが含まれています。

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

Azure SDK は NPM から自由に利用できます。必要な個々の SDK をインストールします。各 SDK には TypeScript 定義が用意されています。

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

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

各パッケージには、パッケージの使用をすぐに開始するためのドキュメントが用意されています。使用する特定の NPM パッケージを参照して、使用方法を確認してください。

認証資格情報を指定する

Azure SDK では、Azure プラットフォームに対する認証に資格情報が必要です。 @azure/identity によって提供される資格情報クラスには、いくつかの利点があります。

迅速なオンボード
最も安全な方法
認証メカニズムをコードから分離します。これにより、資格情報が異なる場合でも、ローカルと Azure プラットフォームで同じコードを使用できます。
複数のメカニズムを使用できるよう、チェーン認証を提供する

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

プログラムで資格情報を作成したら、資格情報を Azure SDK のクライアントに渡します。クライアントには、サブスクリプション ID やサービス URL などの追加情報が必要な場合があります。これらの値は、使用するリソースについて、Azure portal で入手できます。

この資格情報が読み取りアクセス権を持つサブスクリプションを一覧表示します。

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) 応答を返すことができます。この応答には、次の情報が含まれます。

要求は完了している
要求はまだ処理中である

次の 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 および TypeScript 用の Azure SDK を使用する

SDK と REST API の違い

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

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

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

認証資格情報を指定する

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

結果の非同期ページング

長時間実行される操作

非同期操作の取り消し

SDK からの詳細ログ

バンドル

次のステップ

フィードバック

フィードバック

その他のリソース

JavaScript および TypeScript 用の Azure SDK を使用する

SDK と REST API の違い

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

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

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

認証資格情報を指定する

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

結果の非同期ページング

長時間実行される操作

非同期操作の取り消し

SDK からの詳細ログ

バンドル

次のステップ

フィードバック

フィードバック

その他のリソース

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