Azure Blob Storage 및 JavaScript 시작

  • 아티클

이 문서에서는 JavaScript용 Azure Blob Storage 클라이언트 라이브러리 v12를 사용하여 Azure Blob Storage에 연결하는 방법을 보여 줍니다. 연결되면 코드가 Blob Storage 서비스의 컨테이너, Blob 및 기능에서 작동할 수 있습니다.

샘플 코드 조각은 GitHub에서 실행 가능한 Node.js 파일로 사용할 수 있습니다.

API 참조 | 패키지(npm) | 라이브러리 소스 코드 | 샘플 | 피드백 제공

필수 조건

프로젝트 설정

  1. 명령 프롬프트를 열고 프로젝트 폴더로 변경합니다. YOUR-DIRECTORY를 폴더 이름으로 변경합니다.

    cd YOUR-DIRECTORY

  2. 디렉터리에 이미 package.json 파일이 없으면 프로젝트를 초기화하여 파일을 만듭니다.

    npm init -y

  3. JavaScript용 Azure Blob Storage 클라이언트 라이브러리를 설치합니다.

    npm install @azure/storage-blob

  4. Microsoft Entra ID를 통해 암호 없는 연결을 사용하려면 JavaScript용 Azure ID 클라이언트 라이브러리를 설치합니다.

    npm install @azure/identity

액세스 권한 부여 및 Blob Storage에 연결

Microsoft Entra ID는 연결 ID(관리 ID)를 관리하여 가장 안전한 연결을 제공합니다. 암호 없는 기능을 사용하면 코드에 저장된 비밀(키 또는 연결 문자열)이 필요하지 않은 애플리케이션을 개발할 수 있습니다.

Azure 클라우드에 대한 ID 액세스 설정

암호 없이 Azure에 연결하려면 Azure ID를 설정하거나 기존 ID를 사용해야 합니다. ID가 설정되면 ID에 적절한 역할을 할당해야 합니다.

Microsoft Entra ID로 암호 없는 액세스 권한을 부여하려면 Azure 자격 증명을 사용해야 합니다. 필요한 자격 증명 형식은 애플리케이션이 실행되는 위치에 따라 다릅니다. 이 표를 가이드로 참조하세요.

환경 메서드
개발자 환경 Visual Studio Code
개발자 환경 서비스 주체
Azure 호스팅 앱 Azure에서 호스팅되는 앱 설정
온-프레미스 온-프레미스 앱 설정

스토리지 계정 역할 설정

Storage 리소스에는 연결하려는 ID 리소스에 다음 Azure RBAC 역할 중 하나 이상이 할당되어 있어야 합니다. 이전 단계(Azure 클라우드, 로컬 개발, 온-프레미스)에서 만든 각 ID에 대한 Azure Storage 역할을 설정하세요.

설정을 완료한 후 각 ID에는 적절한 역할 중 하나 이상이 필요합니다.

  • 데이터 액세스 역할 - 예:

    • Storage Blob 데이터 읽기 권한자
    • Storage Blob 데이터 Contributor

  • 리소스 역할 - 예:

    • 판독기
    • 기여자

애플리케이션 빌드

애플리케이션을 빌드할 때 코드는 주로 세 가지 형식의 리소스와 상호 작용합니다.

  • Azure Storage 데이터에 대한 고유한 최상위 네임스페이스인 스토리지 계정.
  • 스토리지 계정의 Blob 데이터를 구성하는 컨테이너.
  • 텍스트 및 이진 데이터와 같은 비정형 데이터를 저장하는 Blob.

다음 다이어그램에서는 리소스 간의 관계를 보여줍니다.

Diagram of Blob storage architecture

각 리소스 형식은 하나 이상의 연결된 JavaScript 클라이언트로 표시됩니다.

클래스 설명
BlobServiceClient 스토리지 계정에 대한 Blob Storage 엔드포인트를 나타냅니다.
ContainerClient 를 사용하면 Azure Storage 컨테이너와 해당 Blob을 조작할 수 있습니다.
BlobClient Azure Storage Blob을 조작할 수 있습니다.

BlobServiceClient 개체 만들기

BlobServiceClient 개체는 SDK의 최상위 개체입니다. 이 클라이언트를 사용하면 서비스, 컨테이너 및 Blob을 조작할 수 있습니다.

Azure Storage 계정 ID 역할 및 로컬 환경이 설정되면 @azure/identity 패키지를 포함하는 JavaScript 파일을 만듭니다. DefaultAzureCredential과 같은 자격 증명을 만들어 Blob Storage에 대한 암호 없는 연결을 구현합니다. 해당 자격 증명을 사용하여 BlobServiceClient 개체로 인증합니다.

// connect-with-default-azure-credential.js
const { BlobServiceClient } = require('@azure/storage-blob');
const { DefaultAzureCredential } = require('@azure/identity');
require('dotenv').config()

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error('Azure Storage accountName not found');

const blobServiceClient = new BlobServiceClient(
  `https://${accountName}.blob.core.windows.net`,
  new DefaultAzureCredential()
);

async function main(){
  
  const containerName = 'REPLACE-WITH-EXISTING-CONTAINER-NAME';
  const blobName = 'REPLACE-WITH-EXISTING-BLOB-NAME';

  const timestamp = Date.now();
  const fileName = `my-new-file-${timestamp}.txt`;

  // create container client
  const containerClient = await blobServiceClient.getContainerClient(containerName);

  // create blob client
  const blobClient = await containerClient.getBlockBlobClient(blobName);

  // download file
  await blobClient.downloadToFile(fileName);

  console.log(`${fileName} downloaded`);
  
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(`error: ${ex.message}`));

dotenv 패키지는 .env 파일에서 스토리지 계정 이름을 읽는 데 사용됩니다. 이 파일은 소스 제어에 체크 인하면 안 됩니다. 로컬 서비스 주체를 DefaultAzureCredential 설정의 일부로 사용하는 경우 해당 자격 증명에 대한 모든 보안 정보도 .env 파일로 이동합니다.

Azure 외부에서 실행되는 서버 및 클라이언트에 애플리케이션을 배포하려는 경우 요구 사항에 맞는 자격 증명 중 하나를 만듭니다.

ContainerClient 개체 만들기

BlobServiceClient에서 또는 직접 ContainerClient 개체를 만들 수 있습니다.

BlobServiceClient에서 ContainerClient 개체 만들기

BlobServiceClient에서 ContainerClient 개체를 만듭니다.

// Azure Storage dependency
const {
  StorageSharedKeyCredential,
  BlobServiceClient,
} = require("@azure/storage-blob");

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure Storage resource key
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY;
if (!accountKey) throw Error("Azure Storage accountKey not found");

// Create credential
const sharedKeyCredential = new StorageSharedKeyCredential(
  accountName,
  accountKey
);

const baseUrl = `https://${accountName}.blob.core.windows.net`;
const containerName = `my-container`;

// Create BlobServiceClient
const blobServiceClient = new BlobServiceClient(
  `${baseUrl}`,
  sharedKeyCredential
);

async function main() {
  try {
    // Create container client
    const containerClient = await blobServiceClient.getContainerClient(
      containerName
    );

    // do something with containerClient...
    let i = 1;

    // List blobs in container
    for await (const blob of containerClient.listBlobsFlat()) {
      console.log(`Blob ${i++}: ${blob.name}`);
    }
  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

ContainerClient 직접 만들기

// Azure Storage dependency
const {
  ContainerClient
} = require("@azure/storage-blob");

// Azure authentication for credential dependency
const { DefaultAzureCredential } = require('@azure/identity');

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure SDK needs base URL
const baseUrl = `https://${accountName}.blob.core.windows.net`;

// Unique container name
const timeStamp = Date.now();
const containerName = `test`;

async function main() {
  try {
    
    // create container client from DefaultAzureCredential
    const containerClient = new ContainerClient(
      `${baseUrl}/${containerName}`,
      new DefaultAzureCredential()
    );    

    // do something with containerClient...
    let i = 1;

    // List blobs in container
    for await (const blob of containerClient.listBlobsFlat()) {
        console.log(`Blob ${i++}: ${blob.name}`);
    }


  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

dotenv 패키지는 .env 파일에서 스토리지 계정 이름을 읽는 데 사용됩니다. 이 파일은 소스 제어에 체크 인하면 안 됩니다.

BlobClient 개체 만들기

ContainerClient에서 또는 직접 아래에 나열된 BlobClient 개체를 만들 수 있습니다.

Blob 클라이언트 목록:

ContainerClient에서 BlobClient 개체 만들기

// Azure Storage dependency
const {
  StorageSharedKeyCredential,
  ContainerClient
} = require("@azure/storage-blob");

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure Storage resource key
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY;
if (!accountKey) throw Error("Azure Storage accountKey not found");

// Create credential
const sharedKeyCredential = new StorageSharedKeyCredential(
  accountName,
  accountKey
);

const baseUrl = `https://${accountName}.blob.core.windows.net`;
const containerName = `my-container`;
const blobName = `my-blob`;

// Create ContainerClient
const containerClient = new ContainerClient(
  `${baseUrl}/${containerName}`,
  sharedKeyCredential
);  

async function main() {
  try {
  
    // Create BlobClient object
    const blobClient = containerClient.getBlobClient(blobName);

    // do something with blobClient...
    const properties = await blobClient.getProperties();
    console.log(`Blob ${blobName} properties:`);

    // get BlockBlobClient from blobClient
    const blockBlobClient = blobClient.getBlockBlobClient();

    // do something with blockBlobClient...
    const downloadResponse = await blockBlobClient.download(0);

  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

BlobClient 직접 만들기

// Azure Storage dependency
const { BlockBlobClient } = require("@azure/storage-blob");

// Azure authentication for credential dependency
const { DefaultAzureCredential } = require('@azure/identity');

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure SDK needs base URL
const baseUrl = `https://${accountName}.blob.core.windows.net`;

// Container must exist prior to running this script
const containerName = `test`;

// Random blob name and contents
const timeStamp = Date.now();
const blobName = `${timeStamp}-my-blob.txt`;
const fileContentsAsString = "Hello there.";

async function main(){

  // Create a client that can authenticate with Azure Active Directory
  const client = new BlockBlobClient(
    `${baseUrl}/${containerName}/${blobName}`,
    new DefaultAzureCredential()
  );

  // Get file url - available before contents are uploaded
  console.log(`blob.url: ${client.url}`);

  // Upload file contents
  const result = await client.upload(fileContentsAsString, fileContentsAsString.length);

  // Get results
  return result;
}

main().then((result) => console.log(result)).catch((ex) => console.log(ex.message));

/*

Response looks like this:

{
  etag: '"0x8DAD247F1F4896E"',
  lastModified: 2022-11-29T20:26:07.000Z,
  contentMD5: <Buffer 9d 6a 29 63 87 20 77 db 67 4a 27 a3 9c 49 2e 61>,
  clientRequestId: 'a07fdd1f-5937-44c7-984f-0699a48a05c0',
  requestId: '3580e726-201e-0045-1a30-0474f6000000',
  version: '2021-04-10',
  date: 2022-11-29T20:26:06.000Z,
  isServerEncrypted: true,
  'content-length': '0',
  server: 'Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0',
  'x-ms-content-crc64': 'BLv7vb1ONT8=',
  body: undefined
}
*/

dotenv 패키지는 .env 파일에서 스토리지 계정 이름을 읽는 데 사용됩니다. 이 파일은 소스 제어에 체크 인하면 안 됩니다.

참고 항목