JavaScript용 Azure Storage 파일 공유 클라이언트 라이브러리 - 버전 12.26.0

Azure Files는 업계 표준 SMB(서버 메시지 블록) 프로토콜을 통해 액세스할 수 있는 완전히 관리되는 파일 공유를 클라우드에서 제공합니다. Azure 파일 공유는 Windows, Linux 및 macOS의 클라우드 또는 온-프레미스 배포를 통해 동시에 탑재할 수 있습니다. 또한 Azure 파일 공유는 데이터가 사용되는 곳 근처에서 빠르게 액세스할 수 있도록 Azure 파일 동기화를 사용하여 Windows Server에 캐시할 수 있습니다.

이 프로젝트는 Microsoft Azure File Storage 서비스를 쉽게 사용할 수 있는 JavaScript의 클라이언트 라이브러리를 제공합니다.

이 패키지의 클라이언트 라이브러리를 사용하여 다음을 수행합니다.

• 파일 서비스 속성 가져오기/설정
• 파일 공유 만들기/나열/삭제
• 파일 디렉터리 만들기/나열/삭제
• 파일 만들기/읽기/나열/업데이트/삭제

참고: 이 패키지는 이전에 @azure/storage-file이름으로 게시되었습니다. Azure Storage Files DataLake에 대한 예정된 새 패키지에 더 잘 부합하고 Azure에서 파일을 사용하기 위한 일관된 API 집합을 제공하기 위해 @azure/storage-file-share 이름이 바뀌었습니다.

키 링크:

• 소스 코드
• 패키지(npm)
• API 참조 설명서
• 제품 설명서
• 샘플
• Azure Storage 파일 REST API

시작

현재 지원되는 환경

• Node.js의 LTS 버전
• Safari, Chrome, Edge 및 Firefox의 최신 버전입니다.

자세한 내용은 지원 정책 참조하세요.

필수 구성 요소

• Azure 구독
• Storage 계정

패키지 설치

JavaScript용 Azure File Storage 클라이언트 라이브러리를 설치하는 기본 방법은 npm 패키지 관리자를 사용하는 것입니다. 터미널 창에 다음을 입력합니다.

npm install @azure/storage-file-share

클라이언트 인증

Azure Storage는 인증하는 여러 가지 방법을 지원합니다. Azure Storage 파일 공유 서비스와 상호 작용하려면 스토리지 클라이언트의 인스턴스(예: ShareServiceClient, ShareClient또는 ShareDirectoryClient)를 만들어야 합니다. 인증에 대한 자세한 내용은 만들기 위한 샘플을 참조하세요.

• 공유 키
• 공유 액세스 서명

호환성

이 라이브러리는 Node.js 및 브라우저와 호환되며 LTS Node.js 버전(>=8.16.0) 및 최신 버전의 Chrome, Firefox 및 Edge에 대해 유효성을 검사합니다.

웹 작업자

이 라이브러리를 사용하려면 브라우저에서 사용할 때 특정 DOM 개체를 전역적으로 사용할 수 있어야 하며, 웹 작업자는 기본적으로 사용할 수 없습니다. 이 라이브러리가 웹 작업자에서 작동하도록 하려면 이러한 라이브러리를 폴리필해야 합니다.

자세한 내용은 Web Worker JS용 Azure SDK 사용에 대한 설명서를 참조하세요.

이 라이브러리는 웹 작업자에서 사용할 때 로드된 외부 폴리필이 필요한 다음 DOM API에 따라 달라집니다.

• document
• DOMParser
• Node
• XMLSerializer

Node.js 브라우저 간의 차이점

Node.js 브라우저 런타임 간에는 차이가 있습니다. 이 라이브러리를 시작할 때는 "NODE.JS 런타임에서만 사용 가능" 또는 "브라우저에서만 사용 가능"표시된 API 또는 클래스에 주의하세요.

• 파일이 압축된 데이터를 gzip 또는 deflate 형식으로 보유하고 콘텐츠 인코딩이 그에 따라 설정된 경우 다운로드 동작은 Node.js 브라우저 간에 다릅니다. Node.js 스토리지 클라이언트는 압축된 형식으로 파일을 다운로드하고 브라우저에서는 데이터가 압축 해제된 형식으로 다운로드됩니다.

다음 기능, 인터페이스, 클래스 또는 함수는 Node.js

• 계정 이름 및 계정 키를 기반으로 하는 공유 키 권한 부여
  • StorageSharedKeyCredential
• SAS(공유 액세스 서명) 생성
  • generateAccountSASQueryParameters()
  • generateFileSASQueryParameters()
• 병렬 업로드 및 다운로드. ShareFileClient.uploadData() Node.js 브라우저에서 모두 사용할 수 있습니다.
  • ShareFileClient.uploadFile()
  • ShareFileClient.uploadStream()
  • ShareFileClient.downloadToBuffer()
  • ShareFileClient.downloadToFile()

다음 기능, 인터페이스, 클래스 또는 함수는 브라우저에서만 사용할 수 있습니다.

해당(N/A)

JavaScript 번들

브라우저에서 이 클라이언트 라이브러리를 사용하려면 먼저 번들러를 사용해야 합니다. 이 작업을 수행하는 방법에 대한 자세한 내용은 번들링 설명서참조하세요.

CORS

브라우저용으로 개발해야 하는 경우 스토리지 계정에 대한 CORS(원본 간 리소스 공유) 규칙을 설정해야 합니다. Azure Portal 및 Azure Storage Explorer로 이동하여 스토리지 계정을 찾고 Blob/큐/파일/테이블 서비스에 대한 새 CORS 규칙을 만듭니다.

예를 들어 디버깅을 위해 다음 CORS 설정을 만들 수 있습니다. 그러나 프로덕션 환경의 요구 사항에 따라 설정을 신중하게 사용자 지정하세요.

• 허용된 원본: *
• 허용되는 동사: DELETE, GET, HEAD,MERGE,POST,OPTIONS,PUT
• 허용되는 헤더: *
• 노출된 헤더: *
• 최대 사용 기간(초): 86400

주요 개념

다음 구성 요소와 해당 클라이언트 라이브러리는 Azure Storage 파일 공유 서비스를 구성합니다.

• 스토리지 계정은 ShareServiceClient 나타내는 자체입니다.
• 스토리지 계정 내에서 파일 공유ShareClient
• 인스턴스가 나타내는 파일 공유 내에 디렉터리의 선택적 계층 구조
• 파일 공유 내에 파일 크기는 최대 1TiB이며

예제

• 패키지 가져오기
• 공유 서비스 클라이언트 만들기
• 계정 공유 나열
• 새 공유 및 디렉터리 만들기
• Azure 파일을 만든 다음 업로드합니다.
• 디렉터리 아래의 파일 및 디렉터리 나열
• 파일을 다운로드하고 문자열(Node.js) 변환
• 파일을 다운로드하고 문자열(브라우저) 변환

패키지 가져오기

클라이언트를 사용하려면 패키지를 파일로 가져옵니다.

const AzureStorageFileShare = require("@azure/storage-file-share");

또는 필요한 형식만 선택적으로 가져옵니다.

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

공유 서비스 클라이언트 만들기

ShareServiceClient 파일 공유 서비스에 대한 URL과 액세스 자격 증명이 필요합니다. 또한 필요에 따라 options 매개 변수의 일부 설정을 허용합니다.

연결 문자열 사용

또는 전체 연결 문자열을 인수로 사용하여 ShareServiceClient 정적 메서드를 사용하여 fromConnectionString() 인스턴스화할 수 있습니다. (연결 문자열은 Azure Portal에서 가져올 수 있습니다.)

const { ShareServiceClient } = require("@azure/storage-file-share");

const connStr = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connStr);

StorageSharedKeyCredential

계정 이름 및 계정 키를 사용하여 StorageSharedKeyCredential 전달합니다. (계정 이름 및 계정 키는 Azure Portal에서 가져올 수 있습니다.)

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

// Enter your storage account name and shared key
const account = "<account>";
const accountKey = "<accountkey>";

// Use StorageSharedKeyCredential with storage account and account key
// StorageSharedKeyCredential is only available in Node.js runtime, not in browsers
const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  // When using AnonymousCredential, following url should include a valid SAS
  `https://${account}.file.core.windows.net`,
  credential
);

SAS 토큰으로

또한 SAS(공유 액세스 서명)를 사용하여 ShareServiceClient 인스턴스화할 수 있습니다. Azure Portal에서 SAS 토큰을 가져오거나 generateAccountSASQueryParameters()사용하여 SAS 토큰을 생성할 수 있습니다.

const { ShareServiceClient } = require("@azure/storage-file-share");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";

const serviceClientWithSAS = new ShareServiceClient(
  `https://${account}.file.core.windows.net${sas}`
);

계정의 공유 나열

ShareServiceClient.listShares() 사용하여 새 for-await-of 구문을 사용하여 이 계정의 공유를 반복합니다.

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

async function main() {
  const shareIter = serviceClient.listShares();
  let i = 1;
  for await (const share of shareIter) {
    console.log(`Share${i}: ${share.name}`);
    i++;
  }
}

main();

또는 for-await-of없는 경우:

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

async function main() {
  const shareIter = serviceClient.listShares();
  let i = 1;
  let shareItem = await shareIter.next();
  while (!shareItem.done) {
    console.log(`Share ${i++}: ${shareItem.value.name}`);
    shareItem = await shareIter.next();
  }
}

main();

새 공유 및 디렉터리 만들기

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

async function main() {
  const shareName = `newshare${new Date().getTime()}`;
  const shareClient = serviceClient.getShareClient(shareName);
  await shareClient.create();
  console.log(`Create share ${shareName} successfully`);

  const directoryName = `newdirectory${new Date().getTime()}`;
  const directoryClient = shareClient.getDirectoryClient(directoryName);
  await directoryClient.create();
  console.log(`Create directory ${directoryName} successfully`);
}

main();

Azure 파일을 만든 다음, 업로드합니다.

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

const shareName = "<share name>";
const directoryName = "<directory name>";

async function main() {
  const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

  const content = "Hello World!";
  const fileName = "newfile" + new Date().getTime();
  const fileClient = directoryClient.getFileClient(fileName);
  await fileClient.create(content.length);
  console.log(`Create file ${fileName} successfully`);

  // Upload file range
  await fileClient.uploadRange(content, 0, content.length);
  console.log(`Upload file range "${content}" to ${fileName} successfully`);
}

main();

디렉터리 아래에 파일 및 디렉터리 나열

DirectoryClient.listFilesAndDirectories() 사용하여 새 for-await-of 구문을 사용하여 파일 및 디렉터리를 반복합니다. kind 속성을 사용하여 반복이 디렉터리인지 파일인지 여부를 식별할 수 있습니다.

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

const shareName = "<share name>";
const directoryName = "<directory name>";

async function main() {
  const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

  const dirIter = directoryClient.listFilesAndDirectories();
  let i = 1;
  for await (const item of dirIter) {
    if (item.kind === "directory") {
      console.log(`${i} - directory\t: ${item.name}`);
    } else {
      console.log(`${i} - file\t: ${item.name}`);
    }
    i++;
  }
}

main();

또는 for-await-of사용하지 않고 다음을 수행합니다.

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

const shareName = "<share name>";
const directoryName = "<directory name>";

async function main() {
  const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

  const dirIter = directoryClient.listFilesAndDirectories();
  let i = 1;
  let item = await dirIter.next();
  while (!item.done) {
    if (item.value.kind === "directory") {
      console.log(`${i} - directory\t: ${item.value.name}`);
    } else {
      console.log(`${i} - file\t: ${item.value.name}`);
    }
    i++;
    item = await dirIter.next();
  }
}

main();

반복에 대한 전체 샘플은 samples/v12/typescript/src/listFilesAndDirectories.ts참조하세요.

파일을 다운로드하고 문자열로 변환(Node.js)

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

const shareName = "<share name>";
const fileName = "<file name>";

// [Node.js only] A helper method used to read a Node.js readable stream into a Buffer
async function streamToBuffer(readableStream) {
  return new Promise((resolve, reject) => {
    const chunks = [];
    readableStream.on("data", (data) => {
      chunks.push(data instanceof Buffer ? data : Buffer.from(data));
    });
    readableStream.on("end", () => {
      resolve(Buffer.concat(chunks));
    });
    readableStream.on("error", reject);
  });
}

async function main() {
  const fileClient = serviceClient
    .getShareClient(shareName)
    .rootDirectoryClient.getFileClient(fileName);

  // Get file content from position 0 to the end
  // In Node.js, get downloaded data by accessing downloadFileResponse.readableStreamBody
  const downloadFileResponse = await fileClient.download();
  console.log(
    `Downloaded file content: ${(
      await streamToBuffer(downloadFileResponse.readableStreamBody)
    ).toString()}`
  );
}

main();

파일을 다운로드하고 문자열로 변환(브라우저)

브라우저에서 이 라이브러리를 사용하는 방법에 대한 자세한 내용은 JavaScript 번들 섹션을 참조하세요.

const { ShareServiceClient } = require("@azure/storage-file-share");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const shareName = "<share name>";
const fileName = "<file name>";

const serviceClient = new ShareServiceClient(`https://${account}.file.core.windows.net${sas}`);

async function main() {
  const fileClient = serviceClient
    .getShareClient(shareName)
    .rootDirectoryClient.getFileClient(fileName);

  // Get file content from position 0 to the end
  // In browsers, get downloaded data by accessing downloadFileResponse.blobBody
  const downloadFileResponse = await fileClient.download(0);
  console.log(
    `Downloaded file content: ${await blobToString(await downloadFileResponse.blobBody)}`
  );
}

// [Browser only] A helper method used to convert a browser Blob into string.
async function blobToString(blob) {
  const fileReader = new FileReader();
  return new Promise((resolve, reject) => {
    fileReader.onloadend = (ev) => {
      resolve(ev.target.result);
    };
    fileReader.onerror = reject;
    fileReader.readAsText(blob);
  });
}

main();

간단한 ShareServiceClient 시나리오의 전체 예는 samples/v12/typescript/src/shareSerivceClient.ts.

문제 해결

로깅을 사용하도록 설정하면 오류에 대한 유용한 정보를 파악하는 데 도움이 될 수 있습니다. HTTP 요청 및 응답 로그를 보려면 AZURE_LOG_LEVEL 환경 변수를 info설정합니다. 또는 setLogLevel@azure/logger 호출하여 런타임에 로깅을 사용하도록 설정할 수 있습니다.

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

다음 단계

추가 코드 샘플

• 파일 공유 스토리지 샘플(JavaScript)
• 파일 공유 스토리지 샘플 (TypeScript)
• 파일 공유 스토리지 테스트 사례

기여

이 라이브러리에 기여하려면 기여 가이드 읽어 코드를 빌드하고 테스트하는 방법에 대해 자세히 알아보세요.

또한 스토리지 라이브러리에 대한 테스트 환경 설정에 대한 자세한 내용은 Storage 관련 가이드 참조하세요.