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

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

Различия между клиентскими библиотеками и 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. Установите отдельные пакеты SDK по мере необходимости. Каждый пакет SDK предоставляет определения TypeScript.

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

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

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

Предоставление учетных данных для аутентификации

Клиентские библиотеки 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:

• Асинхронные итераторы в пакете Azure SDK для 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 можно:

• прервать на основе вашей логики;
• прервать на основе ограничения по времени выполнения;
• прервать на основе сигнала родительской задачи;
• прервать на основе сигнала родительской задачи или ограничения по времени выполнения.

Подробнее:

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

Подробное ведение журнала из пакета SDK

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

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

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

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

Объединение

Дополнительные сведения об объединении с помощью пакета Azure SDK:

• Выполнение объединения пакетов Azure SDK
• Примеры объединения

Следующие шаги

• Вывод списка подписок с помощью пакета SDK @azure/arm-subscriptions
• Вывод списка последних операций ресурсов с помощью пакета SDK для @azure/arm-monitor