Azure Blob Storage 및 JavaScript 시작
이 문서에서는 JavaScript용 Azure Blob Storage 클라이언트 라이브러리 v12를 사용하여 Azure Blob Storage에 연결하는 방법을 보여 줍니다. 연결되면 코드가 Blob Storage 서비스의 컨테이너, Blob 및 기능에서 작동할 수 있습니다.
샘플 코드 조각은 GitHub에서 실행 가능한 Node.js 파일로 사용할 수 있습니다.
API 참조 | 패키지(npm) | 라이브러리 소스 코드 | 샘플 | 피드백 제공
필수 조건
- Azure 구독 - 체험 구독 만들기
- Azure Storage 계정 - 스토리지 계정 만들기
- Node.js LTS
- 클라이언트(브라우저) 애플리케이션의 경우 번들링 도구가 필요합니다.
프로젝트 설정
명령 프롬프트를 열고 프로젝트 폴더로 변경합니다.
YOUR-DIRECTORY
를 폴더 이름으로 변경합니다.cd YOUR-DIRECTORY
디렉터리에 이미
package.json
파일이 없으면 프로젝트를 초기화하여 파일을 만듭니다.npm init -y
JavaScript용 Azure Blob Storage 클라이언트 라이브러리를 설치합니다.
npm install @azure/storage-blob
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에는 적절한 역할 중 하나 이상이 필요합니다.
애플리케이션 빌드
애플리케이션을 빌드할 때 코드는 주로 세 가지 형식의 리소스와 상호 작용합니다.
- Azure Storage 데이터에 대한 고유한 최상위 네임스페이스인 스토리지 계정.
- 스토리지 계정의 Blob 데이터를 구성하는 컨테이너.
- 텍스트 및 이진 데이터와 같은 비정형 데이터를 저장하는 Blob.
다음 다이어그램에서는 리소스 간의 관계를 보여줍니다.
각 리소스 형식은 하나 이상의 연결된 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
파일에서 스토리지 계정 이름을 읽는 데 사용됩니다. 이 파일은 소스 제어에 체크 인하면 안 됩니다.