JavaScript 및 TypeScript용 Azure 클라이언트 라이브러리 사용

아티클
03/09/2025

프로그래밍 방식으로 Azure 서비스에 액세스하려면 JavaScript용 Azure 클라이언트 라이브러리를 사용합니다. 일반적으로 이러한 라이브러리는 microsoft1es에서 게시한 @azure npm 패키지 범위 내에서 지정됩니다.

클라이언트 라이브러리와 REST API 간의 차이점

다음 정보를 사용하여 액세스 유형을 사용하는 시기를 이해합니다.

Azure 클라이언트 라이브러리는 Azure 서비스에 액세스하는 기본 방법입니다. 이러한 라이브러리는 인증, 재시도 및 로깅과 같은 클라우드 기반 Azure 플랫폼 REST 요청을 관리하는 데 필요한 상용구 코드를 추상화합니다.
Azure REST API는 다음의 경우 선호되는 방법입니다.
- Azure 클라이언트 라이브러리가 없는 미리 보기 서비스와 함께 작업하기 서비스를 클라이언트 라이브러리에서 일반적으로 사용할 수 있는 경우 업데이트해야 하는 코드를 미리 보기로 간주합니다.
- 전체 SDK가 단일 REST API를 사용하지 않도록 하거나 HTTP 요청을 더 자세히 제어하려고 하므로 REST 호출을 직접 만들려고 합니다.

Azure 클라이언트 및 관리 라이브러리

Azure 클라이언트 라이브러리 릴리스 다음과 같이 사용할 수 있습니다.

관리: 관리 라이브러리를 사용하면 Azure 리소스를 만들고 관리할 수 있습니다. 패키지 이름에 arm-이 포함된 이러한 라이브러리를 인식할 수 있습니다. arm 용어는 Azure Resource Manager를 나타냅니다.
- 설명서 및 코드 샘플
클라이언트: Azure 리소스가 이미 있는 경우 클라이언트 라이브러리를 사용하여 이를 활용하고 상호작용합니다.
- 각 패키지 README.md 설명서 및 샘플을 포함합니다.

Azure npm 패키지 설치

Azure 클라이언트 라이브러리는 NPM 및 Yarn자유롭게 사용할 수 있습니다. 필요에 따라 개별 SDK를 설치합니다. 각 SDK는 TypeScript 정의를 제공합니다.

클라이언트/브라우저 사용의 경우 Azure 클라이언트 라이브러리를 번들링 프로세스에 추가해야 합니다.

Azure npm 패키지 샘플 코드 사용

각 패키지에는 패키지를 빠르게 시작하기 위한 설명서가 포함되어 있습니다. 사용 방법을 알아보려면 사용하는 특정 패키지의 설명서를 참조하세요.

인증 자격 증명 제공

Azure 클라이언트 라이브러리는 Azure 플랫폼 인증하기 위해 자격 증명필요합니다. @azure/identity 에서 제공하는 자격 증명 클래스는 몇 가지 이점을 제공합니다.

빠른 온보딩
가장 안전한 방법
인증 메커니즘을 코드와 분리합니다. 이렇게 하면 자격 증명이 다른 동안 로컬 및 Azure 플랫폼에서 동일한 코드를 사용할 수 있습니다.
여러 메커니즘을 사용할 수 있도록 연결된 인증을 제공합니다.

SDK 클라이언트 및 호출 메서드 만들기

프로그래밍 방식으로 자격 증명을 만든 후에는 자격 증명을 Azure 클라이언트에 전달합니다. 클라이언트에는 구독 ID 또는 서비스 엔드포인트와 같은 추가 정보가 필요할 수 있습니다. 이러한 값은 리소스에 대해 Azure Portal에서 사용할 수 있습니다.

다음 코드 예제에서는 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의 페이징 및 반복기에 대해 자세히 알아봅니다.

JavaScript/TypeScript용 Azure SDK에서 비동기 반복기

장기 실행 작업

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 작업은 다음과 같습니다.

사용자 고유의 논리에 따라 중단됨
시간 제한에 따라 중단됨
부모 작업의 신호에 따라 취소됨
부모 작업의 신호 에 따라 중단되거나,의 시간 초과 제한으로 인해 중단되었습니다.

더 알아보세요:

JavaScript/TypeScript용 Azure SDK에서 중단 신호를 사용하여 작업을 취소하는 방법

SDK의 자세한 정보 로깅

Azure SDK를 사용하는 경우 애플리케이션을 디버그해야 하는 경우가 있을 수 있습니다.

빌드 시간로깅을 사용하도록 설정하려면 AZURE_LOG_LEVEL 환경 변수를 info설정합니다.
런타임로깅을 사용하도록 설정하려면 @azure/로거 패키지를 사용합니다.
```
import { setLogLevel } from "@azure/logger";

setLogLevel("info");
```

번들링

Azure SDK를 사용하여 번들링하는 방법에 대해 알아봅니다.

다음 단계

@azure/arm-subscriptions SDK를 사용하여 구독 목록 보기
@azure/arm-monitor SDK 사용하여 최근 리소스 작업을 나열합니다.

다음을 통해 공유