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

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

Различия между пакетами SDK и REST API

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

• Пакеты Azure SDK являются предпочтительным способом доступа к службе Azure. Пакеты Azure SDK абстрагируют шаблонный код, требуемый для управления облачными запросами REST платформы Azure, такими как аутентификация, повторные попытки и ведение журнала.
• Интерфейсы REST API Azure — это предпочтительный метод, если вы:
  • работаете со службами в предварительной версии, которые не имеют доступа к пакетам Azure SDK; рассматриваете свой код как код в предварительной версии, который будет обновлен после общей доступности службы с наличием SDK пакетов;
  • хотите напрямую осуществлять вызовы REST, чтобы весь пакет SDK не использовал один REST API, или хотите получить больше возможностей для управления HTTP-запросами.

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

Выпуски пакетов Azure SDK доступны в следующих форматах:

• Пакеты SDK для управления: библиотеки управления позволяют вам подготавливать и администрировать ресурсы Azure через Azure Resource Manager (ARM). Их можно распознать по наличию @azure/arm- в имени пакетов.
  • Документация и примеры кода
• Клиентские пакеты SDK: если ресурс Azure уже существует, вы будете использовать клиентские библиотеки для его использования и взаимодействия с ним.
  • Файл README.md в каждом пакете включает соответствующую документацию и примеры.

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

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

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

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

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

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

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

• Быстрое подключение.
• Самый безопасный способ.
• Независимость механизма аутентификации от кода. Это позволяет использовать один и тот же код локально и на платформе 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 для 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
• Создание виртуальной машины с помощью пакета SDK для @azure/arm-вычислений