다음을 통해 공유


Python용 Azure DataLake 서비스 클라이언트 라이브러리 - 버전 12.14.0

개요

Python용 이 미리 보기 패키지에는 Storage SDK에서 사용할 수 있는 ADLS Gen2 특정 API 지원이 포함되어 있습니다. 다음 내용이 포함됩니다.

  1. HNS(계층 구조 네임스페이스 사용) 스토리지 계정에 대한 새 디렉터리 수준 작업(만들기, 이름 바꾸기, 삭제)입니다. HNS 사용 계정의 경우 이름 바꾸기/이동 작업은 원자성입니다.
  2. HNS(계층 구조 네임스페이스 사용) 계정에 대한 권한 관련 작업(ACL 가져오기/설정).

소스 코드 | 패키지(PyPi) | 패키지(Conda) | API 참조 설명서 | 제품 설명서 | 샘플

시작

필수 구성 요소

패키지 설치

pip를 사용하여 Python용 Azure DataLake Storage 클라이언트 라이브러리를 설치합니다.

pip install azure-storage-file-datalake --pre

저장소 계정 만들기

새 스토리지 계정을 만들려는 경우 Azure Portal, Azure PowerShell 또는 Azure CLI를 사용할 수 있습니다.

# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Install the extension 'Storage-Preview'
az extension add --name storage-preview

# Create the storage account
az storage account create --name my-storage-account-name --resource-group my-resource-group --sku Standard_LRS --kind StorageV2 --hierarchical-namespace true

클라이언트 인증

DataLake Storage와의 상호 작용은 DataLakeServiceClient 클래스의 instance 시작합니다. 클라이언트 개체를 인스턴스화하려면 기존 스토리지 계정, 해당 URL 및 자격 증명이 필요합니다.

자격 증명 가져오기

클라이언트를 인증하려면 몇 가지 옵션이 있습니다.

  1. SAS 토큰 문자열 사용
  2. 계정 공유 액세스 키 사용
  3. azure.identity에서 토큰 자격 증명 사용

또는 메서드를 사용하여 스토리지 연결 문자열 인증할 from_connection_string 수 있습니다. 예제: 연결 문자열 사용하여 클라이언트 만들기를 참조하세요.

계정 URL에 이미 SAS 토큰이 있는 경우 자격 증명을 생략할 수 있습니다.

클라이언트 만들기

계정 URL 및 자격 증명이 준비되면 DataLakeServiceClient를 만들 수 있습니다.

from azure.storage.filedatalake import DataLakeServiceClient

service = DataLakeServiceClient(account_url="https://<my-storage-account-name>.dfs.core.windows.net/", credential=credential)

주요 개념

DataLake 스토리지는 다음 네 가지 유형의 리소스를 제공합니다.

  • 스토리지 계정
  • 스토리지 계정의 파일 시스템
  • 파일 시스템 아래의 디렉터리
  • 파일 시스템 또는 디렉터리 아래의 파일

비동기 클라이언트

이 라이브러리에는 Python 3.5 이상에서 지원되는 완전한 비동기 API가 포함되어 있습니다. 이를 사용하려면 먼저 aiohttp와 같은 비동기 전송을 설치해야 합니다. 자세한 내용은 azure-core 설명서를 참조하세요.

비동기 클라이언트 및 자격 증명은 더 이상 필요하지 않은 경우 닫아야 합니다. 이러한 개체는 비동기 컨텍스트 관리자이며 비동 close 기 메서드를 정의합니다.

클라이언트

DataLake Storage SDK는 DataLake 서비스와 상호 작용할 수 있는 네 가지 클라이언트를 제공합니다.

  1. DataLakeServiceClient - 이 클라이언트는 계정 수준에서 DataLake 서비스와 상호 작용합니다. 계정 내의 파일 시스템을 나열, 만들기 및 삭제할 뿐만 아니라 계정 속성을 검색 및 구성하는 작업을 제공합니다. 특정 파일 시스템, 디렉터리 또는 파일과 관련된 작업의 경우 , 또는 get_file_system_client 함수를 사용하여 해당 엔터티에 get_file_clientget_directory_client 대한 클라이언트를 검색할 수도 있습니다.
  2. FileSystemClient - 이 클라이언트는 해당 파일 시스템이 아직 존재하지 않더라도 특정 파일 시스템과의 상호 작용을 나타냅니다. 파일 시스템을 만들거나 삭제하거나 구성하는 작업을 제공하며 파일 시스템의 경로 나열, 파일 또는 디렉터리 업로드 및 삭제 작업을 포함합니다. 특정 파일과 관련된 작업의 경우 함수를 사용하여 get_file_client 클라이언트를 검색할 수도 있습니다. 특정 디렉터리 관련 작업의 경우 함수를 사용하여 get_directory_client 클라이언트를 검색할 수 있습니다.
  3. DataLakeDirectoryClient - 이 클라이언트는 해당 디렉터리가 아직 없더라도 특정 디렉터리와의 상호 작용을 나타냅니다. 디렉터리 작업 만들기, 삭제, 이름 바꾸기, 속성 가져오기 및 속성 설정 작업을 제공합니다.
  4. DataLakeFileClient - 이 클라이언트는 해당 파일이 아직 없더라도 특정 파일과의 상호 작용을 나타냅니다. 데이터를 추가하고, 데이터를 플러시하고, 파일을 삭제, 만들고, 읽는 파일 작업을 제공합니다.
  5. DataLakeLeaseClient - 이 클라이언트는 FileSystemClient, DataLakeDirectoryClient 또는 DataLakeFileClient와의 임대 상호 작용을 나타냅니다. 리소스에 대한 임대를 획득, 갱신, 해제, 변경 및 중단하는 작업을 제공합니다.

예제

다음 섹션에서는 다음을 포함하여 가장 일반적인 Storage DataLake 작업 중 일부를 다루는 몇 가지 코드 조각을 제공합니다.

연결 문자열 사용하여 클라이언트 만들기

Azure Storage 계정에 대한 연결 문자열 사용하여 DataLakeServiceClient를 만듭니다.

from azure.storage.filedatalake import DataLakeServiceClient

service = DataLakeServiceClient.from_connection_string(conn_str="my_connection_string")

파일 업로드

파일 시스템에 파일을 업로드합니다.

from azure.storage.filedatalake import DataLakeFileClient

data = b"abc"
file = DataLakeFileClient.from_connection_string("my_connection_string",
                                                 file_system_name="myfilesystem", file_path="myfile")
file.create_file ()
file.append_data(data, offset=0, length=len(data))
file.flush_data(len(data))

파일 다운로드

파일 시스템에서 파일을 다운로드합니다.

from azure.storage.filedatalake import DataLakeFileClient

file = DataLakeFileClient.from_connection_string("my_connection_string",
                                                 file_system_name="myfilesystem", file_path="myfile")

with open("./BlockDestination.txt", "wb") as my_file:
    download = file.download_file()
    download.readinto(my_file)

경로 열거

파일 시스템의 경로를 나열합니다.

from azure.storage.filedatalake import FileSystemClient

file_system = FileSystemClient.from_connection_string("my_connection_string", file_system_name="myfilesystem")

paths = file_system.get_paths()
for path in paths:
    print(path.name + '\n')

선택적 구성

선택적 키워드(keyword) 클라이언트 및 작업별 수준에서 전달할 수 있는 인수입니다.

재시도 정책 구성

클라이언트를 인스턴스화하여 재시도 정책을 구성할 때 다음 키워드(keyword) 인수를 사용합니다.

  • retry_total (int): 허용할 총 재시도 횟수입니다. 다른 개수보다 우선합니다. retry_total=0 요청을 다시 시도하지 않으려면 전달합니다. 기본값은 10입니다.
  • retry_connect (int): 다시 시도할 연결 관련 오류 수입니다. 기본값은 3입니다.
  • retry_read (int): 읽기 오류를 다시 시도할 횟수입니다. 기본값은 3입니다.
  • retry_status(int): 잘못된 상태 코드에서 다시 시도할 횟수입니다. 기본값은 3입니다.
  • retry_to_secondary (bool): 가능하면 요청을 보조로 다시 시도해야 하는지 여부입니다. RA-GRS 계정만 사용하도록 설정해야 하며 잠재적으로 부실한 데이터를 처리할 수 있습니다. 기본값은 False입니다.

기타 클라이언트/작업별 구성

다른 선택적 구성 키워드(keyword) 클라이언트 또는 작업별로 지정할 수 있는 인수입니다.

클라이언트 키워드(keyword) 인수:

  • connection_timeout (int): 클라이언트가 서버에 연결하기 위해 대기하는 시간(초)입니다. 기본값은 20초입니다.
  • read_timeout (int): 클라이언트가 서버의 응답을 위해 연속 읽기 작업 사이에 대기하는 시간(초)입니다. 이는 소켓 수준 시간 제한이며 전체 데이터 크기의 영향을 받지 않습니다. 클라이언트 쪽 읽기 시간 제한은 자동으로 다시 시도됩니다. 기본값은 60초입니다.
  • transport (Any): HTTP 요청을 보내기 위해 사용자가 제공한 전송입니다.

연산별 키워드(keyword) 인수:

  • raw_response_hook (호출 가능): 지정된 콜백은 서비스에서 반환된 응답을 사용합니다.
  • raw_request_hook (호출 가능): 지정된 콜백은 서비스로 전송되기 전에 요청을 사용합니다.
  • client_request_id (str): 선택적 사용자 지정 요청 식별입니다.
  • user_agent (str): 요청과 함께 보낼 사용자 에이전트 헤더에 사용자 지정 값을 추가합니다.
  • logging_enable (bool): DEBUG 수준에서 로깅을 사용하도록 설정합니다. 기본값은 False입니다. 클라이언트 수준에서 전달하여 모든 요청에 대해 사용하도록 설정할 수도 있습니다.
  • logging_body (bool): 요청 및 응답 본문을 로깅할 수 있습니다. 기본값은 False입니다. 클라이언트 수준에서 전달하여 모든 요청에 대해 사용하도록 설정할 수도 있습니다.
  • 헤더 (dict): 사용자 지정 헤더를 키, 값 쌍으로 전달합니다. 예: headers={'CustomValue': value}

문제 해결

일반

DataLake Storage 클라이언트는 Azure Core에 정의된 예외를 발생합니다.

이 목록은 throw된 예외를 catch하는 참조에 사용할 수 있습니다. 예외의 특정 오류 코드를 얻으려면 특성(예exception.error_code: )을 사용합니다error_code.

로깅

이 라이브러리는 로깅에 표준 로깅 라이브러리를 사용합니다. HTTP 세션(URL, 헤더 등)에 대한 기본 정보는 INFO 수준에서 기록됩니다.

요청/응답 본문 및 수정되지 않은 헤더를 포함한 자세한 DEBUG 수준 로깅은 인수를 사용하여 클라이언트 logging_enable 에서 사용하도록 설정할 수 있습니다.

import sys
import logging
from azure.storage.filedatalake import DataLakeServiceClient

# Create a logger for the 'azure.storage.filedatalake' SDK
logger = logging.getLogger('azure.storage')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = DataLakeServiceClient.from_connection_string("your_connection_string", logging_enable=True)

마찬가지로 logging_enable은 클라이언트에 대해 상세 로깅을 사용하지 않는 경우에도 한 작업에만 사용하게 설정할 수 있습니다.

service_client.list_file_systems(logging_enable=True)

다음 단계

추가 샘플 코드

Azure DataLake 샘플을 시작합니다.

SDK의 GitHub 리포지토리에서 여러 DataLake Storage Python SDK 샘플을 사용할 수 있습니다. 이러한 샘플은 DataLake Storage를 사용하는 동안 일반적으로 발생하는 추가 시나리오에 대한 예제 코드를 제공합니다.

  • datalake_samples_access_control.py - 일반적인 DataLake Storage 작업의 예:

    • 파일 시스템 설정
    • 디렉터리 만들기
    • 디렉터리에 대한 액세스 제어 설정/가져오기
    • 디렉터리 아래에 파일 만들기
    • 각 파일에 대한 액세스 제어 설정/가져오기
    • 파일 시스템 삭제
  • datalake_samples_upload_download.py - 일반적인 DataLake Storage 작업의 예:

    • 파일 시스템 설정
    • 파일 만들기
    • 파일에 데이터 추가
    • 파일에 데이터 플러시
    • 업로드된 데이터 다운로드
    • 파일 시스템 삭제

추가 설명서

ADLS Gen1에서 ADLS Gen2 API 매핑에 대한 테이블 Data Lake Storage Gen2 대한 보다 광범위한 REST 설명서는 docs.microsoft.com 대한 Data Lake Storage Gen2 설명서를 참조하세요.

참여

이 프로젝트에 대한 기여와 제안을 환영합니다. 대부분의 경우 기여하려면 권한을 부여하며 실제로 기여를 사용할 권한을 당사에 부여한다고 선언하는 CLA(기여자 라이선스 계약)에 동의해야 합니다. 자세한 내용은 https://cla.microsoft.com 을 참조하세요.

끌어오기 요청을 제출하면 CLA-bot은 CLA를 제공하고 PR을 적절하게 데코레이팅해야 하는지 여부를 자동으로 결정합니다(예: 레이블, 설명). 봇에서 제공하는 지침을 따르기만 하면 됩니다. 이 작업은 CLA를 사용하여 모든 리포지토리에서 한 번만 수행하면 됩니다.

이 프로젝트에는 Microsoft Open Source Code of Conduct(Microsoft 오픈 소스 준수 사항)가 적용됩니다. 자세한 내용은 Code of Conduct FAQ(규정 FAQ)를 참조하세요. 또는 추가 질문이나 의견은 opencode@microsoft.com으로 문의하세요.