使用適用於 JavaScript 和 TypeScript 的 Azure SDK

若要以程式設計方式存取您的 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 時，應該更新。
  • 想要直接進行 REST 呼叫，因為您不希望整個 SDK 使用單一 REST API，或想要更深入地控制 HTTP 要求。

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/身分識別所提供的認證類別提供數個優點：

• 快速上線
• 最安全的方法
• 將驗證機制與程式代碼分開。 這可讓您在本機和 Azure 平臺上使用相同的程式代碼，而認證不同。
• 提供鏈結式驗證，讓數個機制可供使用

建立 SDK 用戶端和呼叫方法

以程式設計方式建立認證之後，請將認證傳遞至 Azure SDK 的用戶端。 用戶端可能需要其他資訊，例如訂用帳戶標識碼或服務 URL。 這些值適用於您的資源 Azure 入口網站。

列出此認證有權讀取的訂用帳戶。

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 範例 示範如何在繼續之前，先等候 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 作業可以是：

• 根據您自己的邏輯中止
• 根據逾時限制中止
• 根據父工作的訊號中止
• 根據父工作的訊號 或 逾時限制而中止

深入了解：

• 如何使用中止訊號來取消適用於 JavaScript/TypeScript 的 Azure SDK 中的作業

SDK 的詳細信息記錄

使用 Azure SDK 時，有時候您可能需要對應用程式進行偵錯。

• 若要在 建置階段啟用記錄，請將AZURE_LOG_LEVEL環境變數設定為 info。

• 若要在 執行時間啟用記錄，請使用 @azure/logger 套件：

  import { setLogLevel } from "@azure/logger";
  
  setLogLevel("info");
  

統合

瞭解搭配 Azure SDK 的結合：

• 將 Azure SDK 組合在一起
• 組合範例

下一步

• 使用 @azure/arm-subscriptions SDK 列出訂用帳戶
• 使用 @azure/arm-monitor SDK 列出最近的資源作業
• 使用 @azure/arm-compute SDK 建立虛擬機