Python용 Azure Storage 파일 공유 클라이언트 라이브러리

아티클
11/07/2023

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

Azure 파일 공유를 사용하여 다음을 수행할 수 있습니다.

온-프레미스 파일 서버 바꾸기 또는 보완
"리프트 앤 시프트" 애플리케이션
공유 애플리케이션 설정, 진단 공유 및 개발/테스트/디버그 도구를 사용하여 클라우드 개발 간소화

시작

필수 구성 요소

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

패키지 설치

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

pip install azure-storage-file-share

저장소 계정 만들기

새 스토리지 계정을 만들려는 경우 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

# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group

클라이언트 만들기

Python용 Azure Storage 파일 공유 클라이언트 라이브러리를 사용하면 스토리지 계정 자체, 파일 공유, 디렉터리 및 파일의 네 가지 유형의 리소스와 상호 작용할 수 있습니다. 이러한 리소스와의 상호 작용은 클라이언트의 instance 시작합니다. 클라이언트 개체를 만들려면 스토리지 계정의 파일 서비스 URL과 스토리지 계정에 액세스할 수 있는 자격 증명이 필요합니다.

from azure.storage.fileshare import ShareServiceClient

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

계정 URL 조회

Azure Portal, Azure PowerShell 또는 Azure CLI를 사용하여 스토리지 계정의 파일 서비스 URL을 찾을 수 있습니다.

# Get the file service URL for the storage account
az storage account show -n my-storage-account-name -g my-resource-group --query "primaryEndpoints.file"

자격 증명 유형

매개 변수는 credential 사용하려는 권한 부여 유형에 따라 다양한 형식으로 제공될 수 있습니다.

SAS(공유 액세스 서명) 토큰을 사용하려면 토큰을 문자열로 제공합니다. 계정 URL에 SAS 토큰이 포함된 경우 자격 증명 매개 변수를 생략합니다. Azure Portal에서 "공유 액세스 서명"에서 SAS 토큰을 생성하거나 함수 중 generate_sas() 하나를 사용하여 스토리지 계정, 공유 또는 파일에 대한 sas 토큰을 만들 수 있습니다.

from datetime import datetime, timedelta
from azure.storage.fileshare import ShareServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions

sas_token = generate_account_sas(
    account_name="<storage-account-name>",
    account_key="<account-access-key>",
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

share_service_client = ShareServiceClient(account_url="https://<my_account_name>.file.core.windows.net", credential=sas_token)

스토리지 계정 공유 키 (즉, 계정 키 또는 액세스 키)를 사용하려면 키를 문자열로 제공합니다. 이는 Azure Portal의 "액세스 키" 섹션 아래 또는 다음 Azure CLI 명령을 실행하여 찾을 수 있습니다.

az storage account keys list -g MyResourceGroup -n MyStorageAccount

키를 자격 증명 매개 변수로 사용하여 클라이언트를 인증합니다.
```
from azure.storage.fileshare import ShareServiceClient
service = ShareServiceClient(account_url="https://<my_account_name>.file.core.windows.net", credential="<account_access_key>")
```

연결 문자열 클라이언트 만들기

사용 사례 및 권한 부여 방법에 따라 계정 URL과 자격 증명을 별도로 제공하는 대신 스토리지 연결 문자열 사용하여 클라이언트 instance 초기화하는 것이 좋습니다. 이렇게 하려면 스토리지 연결 문자열 클라이언트의 from_connection_string 클래스 메서드에 전달합니다.

from azure.storage.fileshare import ShareServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = ShareServiceClient.from_connection_string(conn_str=connection_string)

스토리지 계정에 대한 연결 문자열은 "액세스 키" 섹션 아래의 Azure Portal 또는 다음 CLI 명령을 실행하여 찾을 수 있습니다.

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

주요 개념

다음 구성 요소는 Azure 파일 공유 서비스를 구성합니다.

스토리지 계정 자체
스토리지 계정 내의 파일 공유
파일 공유 내 디렉터리의 선택적 계층 구조
파일 공유 내의 파일(최대 1TiB 크기일 수 있음)

Python용 Azure Storage 파일 공유 클라이언트 라이브러리를 사용하면 전용 클라이언트 개체를 사용하여 이러한 각 구성 요소와 상호 작용할 수 있습니다.

비동기 클라이언트

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

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

클라이언트

파일 공유 서비스의 다양한 구성 요소와 상호 작용하기 위해 네 가지 클라이언트가 제공됩니다.

ShareServiceClient - 이 클라이언트는 Azure Storage 계정 자체와의 상호 작용을 나타내며, 미리 구성된 클라이언트 인스턴스를 획득하여 파일 공유에 액세스할 수 있습니다. 계정 내에서 공유를 나열, 만들기 및 삭제할 뿐만 아니라 서비스 속성을 검색 및 구성하는 작업을 제공합니다. 특정 공유에 대한 작업을 수행하려면 메서드를 사용하여 클라이언트를 검색합니다 get_share_client .
ShareClient - 이 클라이언트는 특정 파일 공유와의 상호 작용을 나타내며(아직 존재하지 않음) 미리 구성된 클라이언트 인스턴스를 획득하여 내의 디렉터리 및 파일에 액세스할 수 있습니다. 공유의 스냅샷을 생성, 삭제, 구성 또는 만드는 작업을 제공하며, 그 안에 있는 디렉터리 콘텐츠를 만들고 열거하는 작업을 포함합니다. 특정 디렉터리 또는 파일에 대한 작업을 수행하려면 또는 get_file_client 메서드를 사용하여 클라이언트를 get_directory_client 검색합니다.
ShareDirectoryClient - 이 클라이언트는 특정 디렉터리(아직 존재하지 않아도 됨)와의 상호 작용을 나타냅니다. 즉시 또는 중첩된 하위 디렉터리의 내용을 만들거나 삭제하거나 열거하는 작업을 제공하며, 그 안에 파일을 만들고 삭제하는 작업이 포함됩니다. 특정 하위 디렉터리 또는 파일과 관련된 작업의 경우 및 get_file_client 함수를 사용하여 해당 엔터티에 get_subdirectory_client 대한 클라이언트를 검색할 수도 있습니다.
ShareFileClient - 이 클라이언트는 특정 파일과의 상호 작용을 나타냅니다(아직 존재하지 않아도 됨). 파일을 업로드, 다운로드, 만들기, 삭제 및 복사하는 작업을 제공합니다.

경로 명명 제한에 대한 자세한 내용은 공유, 디렉터리, 파일 및 메타데이터 명명 및 참조를 참조하세요.

예제

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

파일 공유 만들기
파일 업로드
파일 다운로드
디렉터리의 콘텐츠 나열

파일을 저장할 파일 공유 만들기

from azure.storage.fileshare import ShareClient

share = ShareClient.from_connection_string(conn_str="<connection_string>", share_name="myshare")
share.create_share()

비동기 클라이언트를 사용하여 파일 공유 만들기

from azure.storage.fileshare.aio import ShareClient

share = ShareClient.from_connection_string(conn_str="<connection_string>", share_name="myshare")
await share.create_share()

파일 업로드

공유에 파일 업로드

from azure.storage.fileshare import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("./SampleSource.txt", "rb") as source_file:
    file_client.upload_file(source_file)

파일을 비동기적으로 업로드

from azure.storage.fileshare.aio import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("./SampleSource.txt", "rb") as source_file:
    await file_client.upload_file(source_file)

파일 다운로드

공유에서 파일 다운로드

from azure.storage.fileshare import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("DEST_FILE", "wb") as file_handle:
    data = file_client.download_file()
    data.readinto(file_handle)

파일을 비동기적으로 다운로드

from azure.storage.fileshare.aio import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("DEST_FILE", "wb") as file_handle:
    data = await file_client.download_file()
    await data.readinto(file_handle)

디렉터리의 콘텐츠 나열

부모 디렉터리 아래의 모든 디렉터리 및 파일 나열

from azure.storage.fileshare import ShareDirectoryClient

parent_dir = ShareDirectoryClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", directory_path="parent_dir")

my_list = list(parent_dir.list_directories_and_files())
print(my_list)

디렉터리의 내용을 비동기적으로 나열

from azure.storage.fileshare.aio import ShareDirectoryClient

parent_dir = ShareDirectoryClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", directory_path="parent_dir")

my_files = []
async for item in parent_dir.list_directories_and_files():
    my_files.append(item)
print(my_files)

선택적 구성

선택적 키워드(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): 선택적 사용자 지정 요청 ID입니다.
user_agent (str): 요청과 함께 보낼 사용자 에이전트 헤더에 사용자 지정 값을 추가합니다.
logging_enable (bool): DEBUG 수준에서 로깅을 사용하도록 설정합니다. 기본값은 False입니다. 클라이언트 수준에서 전달하여 모든 요청에 사용할 수도 있습니다.
logging_body (bool): 요청 및 응답 본문을 로깅할 수 있습니다. 기본값은 False입니다. 클라이언트 수준에서 전달하여 모든 요청에 사용할 수도 있습니다.
헤더 (dict): 사용자 지정 헤더를 키, 값 쌍으로 전달합니다. 예: headers={'CustomValue': value}

문제 해결

일반

스토리지 파일 클라이언트는 Azure Core에 정의된 예외를 발생합니다.

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

로깅

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

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

import sys
import logging
from azure.storage.fileshare import ShareServiceClient

# Create a logger for the 'azure.storage.fileshare' SDK
logger = logging.getLogger('azure.storage.fileshare')
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 = ShareServiceClient.from_connection_string("your_connection_string", logging_enable=True)

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

service_client.get_service_properties(logging_enable=True)

다음 단계

추가 샘플 코드

파일 공유 샘플을 시작합니다.

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

file_samples_hello_world.py (비동기 버전) - 이 문서에 있는 예제:
- 클라이언트 만들기
- 파일 공유 만들기
- 파일 업로드
file_samples_authentication.py (비동기 버전) - 클라이언트를 인증하고 만드는 예제:
- 연결 문자열
- 공유 액세스 키에서
- 공유 액세스 서명 토큰에서
file_samples_service.py (비동기 버전) - 파일 서비스와 상호 작용하는 예제:
- 서비스 속성 가져오기 및 설정
- 공유 만들기, 나열 및 삭제
- 공유 클라이언트 가져오기
file_samples_share.py (비동기 버전) - 파일 공유와 상호 작용하는 예제:
- 공유 스냅샷 만들기
- 공유 할당량 및 메타데이터 설정
- 디렉터리 및 파일 나열
- 특정 엔터티와 상호 작용할 디렉터리 또는 파일 클라이언트 가져오기
file_samples_directory.py (비동기 버전) - 디렉터리 조작 예제:
- 디렉터리 만들기 및 파일 추가
- 하위 디렉터리 만들기 및 삭제
- 하위 디렉터리 클라이언트 가져오기
file_samples_client.py (비동기 버전) - 파일과 상호 작용하는 예제:
- 파일 만들기, 업로드, 다운로드 및 삭제
- URL에서 파일 복사

추가 설명서

Azure File Share 스토리지에 대한 보다 광범위한 설명서는 docs.microsoft.com Azure File Share 스토리지 설명서를 참조하세요 .

참여

이 프로젝트에 대한 기여와 제안을 환영합니다. 대부분의 경우 기여하려면 권한을 부여하며 실제로 기여를 사용할 권한을 당사에 부여한다고 선언하는 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으로 문의하세요.

시작

필수 구성 요소

패키지 설치

저장소 계정 만들기

클라이언트 만들기

계정 URL 조회

자격 증명 유형

연결 문자열 클라이언트 만들기

주요 개념

비동기 클라이언트

클라이언트

예제

파일 업로드

파일 다운로드

디렉터리의 콘텐츠 나열

선택적 구성

재시도 정책 구성

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

문제 해결

일반

로깅

다음 단계

추가 샘플 코드

추가 설명서

참여

피드백

추가 리소스

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

시작

필수 구성 요소

패키지 설치

저장소 계정 만들기

클라이언트 만들기

계정 URL 조회

자격 증명 유형

연결 문자열 클라이언트 만들기

주요 개념

비동기 클라이언트

클라이언트

예제

파일 공유 만들기

파일 업로드

파일 다운로드

디렉터리의 콘텐츠 나열

선택적 구성

재시도 정책 구성

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

문제 해결

일반

로깅

다음 단계

추가 샘플 코드

추가 설명서

참여

피드백

추가 리소스