Использование клиентских библиотек Azure для JavaScript и TypeScript

Для программного доступа к службам Azure используйте клиентские библиотеки Azure для JavaScript. Как правило, эти библиотеки принадлежат к области npm-пакета @azure, опубликованной microsoft1es.

Различия между клиентскими библиотеками и REST API

Используйте следующие сведения, чтобы понять, когда следует использовать тип доступа.

• Библиотеки клиента Azure являются предпочтительным способом для доступа к вашей службе Azure. Эти библиотеки абстрагируют стандартный код, необходимый для управления облачными запросами REST платформы Azure, такими как проверка подлинности, повторные попытки и ведение журнала.
• ИНТЕРФЕЙСы REST API Azure являются предпочтительным способом, если вы:
  • Работа с службами предварительной версии, у которых нет клиентских библиотек Azure. Рассмотрим код как предварительную версию, который следует обновить, когда служба общедоступна с клиентскими библиотеками.
  • Хотите выполнять вызовы REST напрямую, так как вы не хотите, чтобы весь пакет SDK использовал один REST API или требуется более глубокий контроль над HTTP-запросами.

Клиентские библиотеки и библиотеки управления Azure

Клиентские библиотеки Azure версии доступны в виде:

• Управление. Библиотеки управления позволяют создавать и управлять ресурсами Azure. Эти библиотеки можно распознать по метке arm- в именах пакетов. Термин arm обозначает Azure Resource Manager.
  • документация и примеры кода
• Клиент: Учитывая уже существующий ресурс Azure, используйте клиентские библиотеки для его использования и взаимодействия с ним.
  • Каждый пакет README.md включает документацию и примеры.

Установка пакетов npm Azure

Клиентские библиотеки Azure свободно доступны из NPM и Yarn. Установите отдельные пакеты SDK по мере необходимости. Каждый пакет SDK предоставляет определения TypeScript.

При использовании клиентской части/браузера клиентские библиотеки Azure необходимо добавить в процесс объединения.

Использование примера кода пакета npm Azure

Каждый пакет содержит документацию, чтобы быстро приступить к работе с пакетом. Ознакомьтесь с документацией по конкретному пакету, которую вы используете, чтобы узнать, как их использовать.

Предоставьте аутентификационные данные

Клиентские библиотеки Azure требуют учетных данных для проверки подлинности на платформе Azure. классы учетных данных, предоставляемые @azure/identity предоставляют несколько преимуществ:

• Быстрое подключение
• Наиболее безопасный метод
• Отделите механизм проверки подлинности от кода. Это позволяет использовать один и тот же код локально и на платформе Azure, пока учетные данные отличаются.
• Обеспечьте цепную аутентификацию, чтобы несколько механизмов было доступно.

Создание клиента SDK и методов вызова

После программного создания учетных данных передайте учетные данные клиенту Azure. Клиенту может потребоваться дополнительная информация, например идентификатор подписки или конечная точка службы. Эти значения доступны на портале Azure для вашего ресурса.

В следующем примере кода используется свойство 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 Azure для 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, который затем можно передать в операции SDK Azure для отмены ожидающихся задач. Операции пакета SDK Azure могут быть следующими:

• Прервано на основе собственной логики
• Прервано из-за ограничения времени ожидания
• Прервано из-за сигнала родительской задачи
• Прервано на основе сигнала родительской задачи или ограничение времени ожидания

Подробнее:

• Использование сигналов прерывания для отмены операций в пакете SDK Azure для JavaScript или TypeScript

Подробное логирование из SDK

При использовании пакета SDK Для Azure может возникнуть время, когда необходимо выполнить отладку приложения.

• Чтобы включить ведение журнала во время сборки , задайте для переменной среды AZURE_LOG_LEVEL значение info.

• Чтобы включить ведение журнала во время выполнения , используйте пакет @azure/logger:

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

Комплектация

Узнайте о объединении с Azure SDK.

• Пакет пакетов SDK Azure
• Сгруппированные примеры

Дальнейшие действия

• Перечисление подписок с использованием @azure/arm-subscriptions SDK
• Вывод списка последних операций ресурсов с @azure/arm-monitor sdk