JavaScript용 Azure Storage File Data Lake 클라이언트 라이브러리 - 버전 12.25.0

ADLS(Azure Data Lake Storage)에는 개발자, 데이터 과학자 및 분석가가 모든 크기, 모양 및 속도의 데이터를 쉽게 저장하고 플랫폼 및 언어에서 모든 유형의 처리 및 분석을 수행할 수 있도록 하는 데 필요한 모든 기능이 포함되어 있습니다. 일괄 처리, 스트리밍 및 대화형 분석으로 더 빠르게 시작하고 실행할 수 있도록 하면서 모든 데이터를 수집하고 저장하는 복잡성을 제거합니다.

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

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

• 파일 시스템 만들기/나열/삭제
• 경로, 디렉터리 및 파일 만들기/읽기/목록/업데이트/삭제

키 링크:

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

시작

현재 지원되는 환경

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

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

필수 구성 요소

• Azure 구독
• Storage 계정

패키지 설치

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

npm install @azure/storage-file-datalake

클라이언트 인증

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

• Azure Active Directory
• 공유 키
• 공유 액세스 서명

Azure Active Directory

Azure Data Lake Storage 서비스는 Azure Active Directory를 사용하여 해당 API에 대한 요청을 인증하도록 지원합니다. @azure/identity 패키지는 애플리케이션에서 이 작업을 수행하는 데 사용할 수 있는 다양한 자격 증명 유형을 제공합니다. 시작하기 위한 자세한 내용 및 샘플은 대한 추가 정보를 참조하세요.

호환성

이 라이브러리는 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()
  • generateDataLakeSASQueryParameters()
• 병렬 업로드 및 다운로드. DataLakeFileClient.upload() Node.js 브라우저에서 모두 사용할 수 있습니다.
  • DataLakeFileClient.uploadFile()
  • DataLakeFileClient.uploadStream()
  • DataLakeFileClient.readToBuffer()
  • DataLakeFileClient.readToFile()

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

• 해당(N/A)

JavaScript 번들

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

CORS

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

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

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

참고: Data Lake는 현재 Blob 서비스에 대한 CORS 설정을 공유합니다.

주요 개념

Azure Data Lake Storage Gen2는 다음을 수행하도록 설계되었습니다.

• 수백 기가비트의 처리량을 유지하면서 여러 페타바이트 정보를 제공합니다.
• 대량의 데이터를 쉽게 관리할 수 있습니다.

DataLake Storage Gen2의 주요 기능은 다음과 같습니다.

• Hadoop 호환 액세스
• POSIX 권한의 슈퍼 집합
• 저비용 스토리지 용량 및 트랜잭션 측면에서 비용 효율적
• 빅 데이터 분석을 위한 최적화된 드라이버

Data Lake Storage Gen2의 기본 부분은 Blob Storage에 계층 구조 네임스페이스를 추가하는 것입니다. 계층 구조 네임스페이스는 효율적인 데이터 액세스를 위해 개체/파일을 디렉터리의 계층 구조로 구성합니다.

과거에는 클라우드 기반 분석이 성능, 관리 및 보안 영역에서 손상해야 했습니다. Data Lake Storage Gen2는 다음과 같은 방법으로 이러한 각 측면을 다룹니다.

• 분석을 위한 필수 구성 요소로 데이터를 복사하거나 변환할 필요가 없으므로 성능이 최적화됩니다. 계층 구조 네임스페이스는 디렉터리 관리 작업의 성능을 크게 향상시켜 전반적인 작업 성능을 향상시킵니다.
• 디렉터리 및 하위 디렉터리를 통해 파일을 구성하고 조작할 수 있으므로 관리가 더 쉽습니다.
• 디렉터리 또는 개별 파일에 대한 POSIX 권한을 정의할 수 있으므로 보안을 적용할 수 있습니다.
• Data Lake Storage Gen2는 저비용 Azure Blob Storage를 기반으로 구축되므로 비용 효율성이 가능합니다. 추가 기능은 Azure에서 빅 데이터 분석을 실행하기 위한 총 소유 비용을 더욱 낮춥니다.

Data Lake Storage는 다음 세 가지 유형의 리소스를 제공합니다.

• 통해 사용되는 DataLakeServiceClient
• DataLakeFileSystemClient 통해 사용되는 스토리지 계정의 파일 시스템
• DataLakeDirectoryClient 또는 DataLakeFileClient 통해 사용되는 파일 시스템의 경로

참고: 이 클라이언트 라이브러리는 HNS(계층 구조 네임스페이스)를 사용하도록 설정된 스토리지 계정만 지원합니다.

예제

• 패키지 가져오기
• 데이터 레이크 서비스 클라이언트 만들기
• 새 파일 시스템 만들기
• 파일 시스템 나열
• 디렉터리 만들기 및 삭제
• 파일 만들기
• 파일 시스템 내의 경로 나열
• 파일을 다운로드하고 문자열(Node.js) 변환
• 파일을 다운로드하고 문자열(브라우저) 변환

패키지 가져오기

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

const AzureStorageDataLake = require("@azure/storage-file-datalake");

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

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

데이터 레이크 서비스 클라이언트 만들기

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

DefaultAzureCredential 패키지의 @azure/identity

DataLakeServiceClient 인스턴스화하는 권장 방법

통지. Azure Data Lake는 현재 AAD OAuth 인증을 수행하는 동안 "Storage Blob 데이터 소유자"와 같은 Blob 관련 역할을 다시 사용합니다.

설치 : 참조 - 클라이언트 애플리케이션에서 Azure Active Directory를 사용하여 Blob(데이터 레이크) 및 큐에 대한 액세스 권한 부여 - /azure/storage/common/storage-auth-aad-app

• 새 AAD 애플리케이션을 등록하고 로그인한 사용자를 대신하여 Azure Storage에 액세스할 수 있는 권한을 부여합니다.

  • Azure Active Directory(azure-Portal)에 새 애플리케이션 등록 - /azure/active-directory/develop/quickstart-register-app
  • API permissions 섹션에서 Add a permission 선택하고 Microsoft APIs선택합니다.
  • Azure Storage 선택하고 user_impersonation 옆에 있는 확인란을 선택한 다음 Add permissions클릭합니다. 이렇게 하면 애플리케이션이 로그인한 사용자를 대신하여 Azure Storage에 액세스할 수 있습니다.

• Azure Portal에서 RBAC를 사용하여 Azure Data Lake 데이터에 대한 액세스 권한 부여

  • Blob(데이터 레이크) 및 큐에 대한 RBAC 역할 - /azure/storage/common/storage-auth-aad-rbac-portal.
  • Azure Portal에서 스토리지 계정으로 이동하여 Storage Blob 데이터 기여자 역할을 Access control (IAM) 탭(azure-portal의 스토리지 계정 왼쪽 탐색 모음)에서 등록된 AAD 애플리케이션에 할당합니다.

• 샘플에 대한 환경 설정

  • AAD 애플리케이션의 개요 페이지에서 CLIENT ID 적어두고 TENANT ID. "인증서 & 비밀" 탭에서 비밀을 만들고 기록해 둡니다.
  • 샘플을 성공적으로 실행하기 위한 환경 변수로 AZURE_TENANT_ID, AZURE_CLIENT_ID AZURE_CLIENT_SECRET 있는지 확인합니다(process.env를 활용할 수 있습니다).

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

// Enter your storage account name
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

이 메서드를 사용하는 전체 예제는 Azure AD 인증 샘플 참조하세요.

[참고 - 위의 단계는 Node.js경우에만 해당]

연결 문자열 사용

또는 전체 연결 문자열을 인수로 사용하여 DataLakeServiceClient 정적 메서드를 사용하여 fromConnectionString() 인스턴스화할 수 있습니다. (연결 문자열은 Azure Portal에서 가져올 수 있습니다.) [NODE.JS 런타임에서만 사용 가능]

const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const connStr = "<connection string>";

const dataLakeServiceClient = DataLakeServiceClient.fromConnectionString(connStr);

StorageSharedKeyCredential

또는 계정 이름 및 계정 키를 인수로 전달하여 DataLakeServiceClient 사용하여 StorageSharedKeyCredential 인스턴스화합니다. (계정 이름 및 계정 키는 Azure Portal에서 가져올 수 있습니다.) [NODE.JS 런타임에서만 사용 가능]

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

// 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 sharedKeyCredential = new StorageSharedKeyCredential(account, accountKey);
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  sharedKeyCredential
);

SAS 토큰으로

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

const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const serviceClientWithSAS = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net${sas}`
);

새 파일 시스템 만들기

DataLakeServiceClient.getFileSystemClient() 사용하여 파일 시스템 클라이언트 인스턴스를 가져와서 새 파일 시스템 리소스를 만듭니다.

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  // Create a file system
  const fileSystemName = `newfilesystem${new Date().getTime()}`;
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
  const createResponse = await fileSystemClient.create();
  console.log(`Create file system ${fileSystemName} successfully`, createResponse.requestId);
}

main();

파일 시스템 나열

DataLakeServiceClient.listFileSystems() 함수를 사용하여 새 for-await-of 구문을 사용하여 파일 시스템을 반복합니다.

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  let i = 1;
  const fileSystems = datalakeServiceClient.listFileSystems();
  for await (const fileSystem of fileSystems) {
    console.log(`File system ${i++}: ${fileSystem.name}`);
  }
}

main();

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

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  let i = 1;
  const iter = datalakeServiceClient.listFileSystems();
  let fileSystemItem = await iter.next();
  while (!fileSystemItem.done) {
    console.log(`File System ${i++}: ${fileSystemItem.value.name}`);
    fileSystemItem = await iter.next();
  }
}

main();

또한 페이지 매김은 byPage()통해 목록에도 지원됩니다.

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  let i = 1;
  for await (const response of datalakeServiceClient
    .listFileSystems()
    .byPage({ maxPageSize: 20 })) {
    if (response.fileSystemItems) {
      for (const fileSystem of response.fileSystemItems) {
        console.log(`File System ${i++}: ${fileSystem.name}`);
      }
    }
  }
}

main();

디렉터리 만들기 및 삭제

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

const fileSystemName = "<file system name>";

async function main() {
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
  const directoryClient = fileSystemClient.getDirectoryClient("directory");
  await directoryClient.create();
  await directoryClient.delete();
}

main();

파일 만들기

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

const fileSystemName = "<file system name>";

async function main() {
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);

  const content = "Hello world!";
  const fileName = "newfile" + new Date().getTime();
  const fileClient = fileSystemClient.getFileClient(fileName);
  await fileClient.create();
  await fileClient.append(content, 0, content.length);
  await fileClient.flush(content.length);
  console.log(`Create and upload file ${fileName} successfully`);
}

main();

파일 시스템 내의 경로 나열

파일 시스템을 나열하는 것과 유사합니다.

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

const fileSystemName = "<file system name>";

async function main() {
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);

  let i = 1;
  const paths = fileSystemClient.listPaths();
  for await (const path of paths) {
    console.log(`Path ${i++}: ${path.name}, is directory: ${path.isDirectory}`);
  }
}

main();

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

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

const fileSystemName = "<file system name>";
const fileName = "<file name>";

async function main() {
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
  const fileClient = fileSystemClient.getFileClient(fileName);

  // Get file content from position 0 to the end
  // In Node.js, get downloaded data by accessing downloadResponse.readableStreamBody
  const downloadResponse = await fileClient.read();
  const downloaded = await streamToBuffer(downloadResponse.readableStreamBody);
  console.log("Downloaded file content:", downloaded.toString());

  // [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);
    });
  }
}

main();

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

const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const sas = "<sas token>";

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net${sas}`
);

const fileSystemName = "<file system name>";
const fileName = "<file name>"

async function main() {
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
  const fileClient = fileSystemClient.getFileClient(fileName);

  // Get file content from position 0 to the end
  // In browsers, get downloaded data by accessing downloadResponse.contentAsBlob
  const downloadResponse = await fileClient.read();
  const downloaded = await blobToString(await downloadResponse.contentAsBlob);
  console.log(
    "Downloaded file content",
    downloaded
  );

  // [Browsers 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();

문제 해결

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

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

setLogLevel("info");

다음 단계

추가 코드 샘플:

• DataLake Storage 샘플(JavaScript)
• DataLake Storage 샘플 (TypeScript)
• DataLake Storage 테스트 사례

기여

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