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

아티클
11/08/2023

개요

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

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

시작

필수 구성 요소

이 패키지를 사용하려면 Python 3.7 이상이 필요합니다. 자세한 내용은 Python용 Azure SDK 버전 지원 정책 페이지를 참조하세요.
이 패키지를 사용하려면 Azure 구독 및 Azure Storage 계정이 있어야 합니다.

패키지 설치

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 및 자격 증명이 필요합니다.

자격 증명 가져오기

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

SAS 토큰 문자열 사용
계정 공유 액세스 키 사용
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 서비스와 상호 작용할 수 있는 네 가지 클라이언트를 제공합니다.

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