Python용 Azure Storage Blob 클라이언트 라이브러리 - 버전 12.19.0

아티클
11/07/2023

Azure Blob Storage는 클라우드를 위한 Microsoft의 개체 스토리지 솔루션입니다. Blob Storage는 텍스트 또는 이진 데이터와 같이 구조화되지 않은 대량의 데이터를 저장하는 데 최적화되어 있습니다.

Blob 스토리지가 적합한 경우는 다음과 같습니다.

브라우저에 직접 이미지 또는 문서 제공
분산 액세스용 파일 저장.
비디오 및 오디오 스트리밍.
백업 및 복원, 재해 복구, 보관을 위한 데이터 저장.
온-프레미스 또는 Azure 호스팅 서비스에서 분석하기 위한 데이터 저장.

시작

필수 구성 요소

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

패키지 설치

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

pip install azure-storage-blob

저장소 계정 만들기

새 스토리지 계정을 만들려는 경우 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 Blob 클라이언트 라이브러리를 사용하면 스토리지 계정 자체, Blob Storage 컨테이너 및 Blob의 세 가지 유형의 리소스와 상호 작용할 수 있습니다. 이러한 리소스와의 상호 작용은 클라이언트의 instance 시작합니다. 클라이언트 개체를 만들려면 스토리지 계정의 Blob 서비스 계정 URL과 스토리지 계정에 액세스할 수 있는 자격 증명이 필요합니다.

from azure.storage.blob import BlobServiceClient

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

계정 URL 조회

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

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

자격 증명 유형

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

AAD(Azure Active Directory) 토큰 자격 증명을 사용하려면 azure-identity 라이브러리에서 가져온 원하는 자격 증명 형식의 instance 제공합니다. 예를 들어 DefaultAzureCredential을 사용하여 클라이언트를 인증할 수 있습니다.

이렇게 하려면 몇 가지 초기 설정이 필요합니다.
- azure-identity 설치
- 새 AAD 애플리케이션을 등록 하고 Azure Storage에 액세스할 수 있는 권한을 부여합니다.
- Azure Portal에서 RBAC를 사용하여 Azure Blob 데이터에 대한 액세스 권한 부여
- AAD 애플리케이션의 클라이언트 ID, 테넌트 ID 및 클라이언트 암호 값을 환경 변수(AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET
반환된 토큰 자격 증명을 사용하여 클라이언트를 인증합니다.
```
    from azure.identity import DefaultAzureCredential
    from azure.storage.blob import BlobServiceClient
    token_credential = DefaultAzureCredential()

    blob_service_client = BlobServiceClient(
        account_url="https://<my_account_name>.blob.core.windows.net",
        credential=token_credential
    )
```

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

from datetime import datetime, timedelta
from azure.storage.blob import BlobServiceClient, 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)
)

blob_service_client = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential=sas_token)

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

az storage account keys list -g MyResourceGroup -n MyStorageAccount

키를 자격 증명 매개 변수로 사용하여 클라이언트를 인증합니다.
```
from azure.storage.blob import BlobServiceClient
service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential="<account_access_key>")
```
사용자 지정된 URL(URL이 이 형식<my_account_name>.blob.core.windows.net이 아님)을 사용하는 경우 아래 자격 증명을 사용하여 클라이언트를 인스턴스화하세요.
```
from azure.storage.blob import BlobServiceClient
service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", 
   credential={"account_name": "<your_account_name>", "account_key":"<account_access_key>"})
```
익명 공용 읽기 액세스를 사용하려면 자격 증명 매개 변수를 생략하기만 하면 됩니다.

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

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

from azure.storage.blob import BlobServiceClient

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

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

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

주요 개념

다음 구성 요소는 Azure Blob Service를 구성합니다.

스토리지 계정 자체
스토리지 계정 내의 컨테이너
컨테이너 내의 Blob

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

클라이언트

Blob Service의 다양한 구성 요소와 상호 작용하기 위해 네 가지 클라이언트가 제공됩니다.

BlobServiceClient - 이 클라이언트는 Azure Storage 계정 자체와의 상호 작용을 나타내며, 미리 구성된 클라이언트 인스턴스를 획득하여 내 컨테이너 및 Blob에 액세스할 수 있습니다. 계정 속성을 검색 및 구성하고 계정 내에서 컨테이너를 나열, 만들기 및 삭제하는 작업을 제공합니다. 특정 컨테이너 또는 Blob에서 작업을 수행하려면 또는 get_blob_client 메서드를 사용하여 클라이언트를 get_container_client 검색합니다.
ContainerClient - 이 클라이언트는 특정 컨테이너와의 상호 작용을 나타내며(아직 존재하지 않음) 미리 구성된 클라이언트 인스턴스를 획득하여 내 Blob에 액세스할 수 있습니다. 컨테이너를 만들거나 삭제하거나 구성하는 작업을 제공하며 컨테이너 내에서 Blob을 나열, 업로드 및 삭제하는 작업을 포함합니다. 컨테이너 내의 특정 Blob에서 작업을 수행하려면 메서드를 사용하여 클라이언트를 검색합니다 get_blob_client .
BlobClient - 이 클라이언트는 특정 Blob과의 상호 작용을 나타냅니다(아직 존재하지 않아도 됨). Blob 유형별 특정 작업뿐만 아니라 Blob의 스냅샷을 업로드, 다운로드, 삭제 및 만드는 작업을 제공합니다.
BlobLeaseClient - 이 클라이언트는 또는 BlobClient과의 임대 상호 작용을 ContainerClient 나타냅니다. 지정된 리소스에서 임대를 획득, 갱신, 해제, 변경 및 중단하는 작업을 제공합니다.

비동기 클라이언트

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

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

Blob 형식

클라이언트를 초기화한 후에는 다양한 유형의 Blob 중에서 선택할 수 있습니다.

블록 Blob은 텍스트 및 이진 데이터를 약 4.75TiB까지 저장합니다. 블록 Blob은 개별적으로 관리할 수 있는 데이터 블록으로 구성됩니다.
추가 Blob은 블록 Blob과 같이 블록으로 구성되지만 추가 작업에 최적화되어 있습니다. 추가 Blob은 가상 머신에서 데이터 로깅과 같은 시나리오에 적합합니다.
페이지 Blob은 최대 8TiB 크기의 임의 액세스 파일을 저장합니다. 페이지 Blob은 VHD(가상 하드 드라이브) 파일을 저장하고 Azure 가상 머신의 디스크로 사용됩니다.

예제

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

컨테이너 만들기
Blob 업로드
Blob 다운로드
Blob 열거

Blob을 업로드하거나 다운로드하려면 먼저 컨테이너를 만들어야 합니다.

컨테이너 만들기

Blob을 업로드하거나 다운로드할 수 있는 컨테이너를 만듭니다.

from azure.storage.blob import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

container_client.create_container()

비동기 클라이언트를 사용하여 Blob 업로드

from azure.storage.blob.aio import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

await container_client.create_container()

Blob 업로드

컨테이너에 Blob 업로드

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    blob.upload_blob(data)

비동기 클라이언트를 사용하여 Blob 업로드

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    await blob.upload_blob(data)

Blob 다운로드

컨테이너에서 Blob 다운로드

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    blob_data = blob.download_blob()
    blob_data.readinto(my_blob)

비동기적으로 Blob 다운로드

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    stream = await blob.download_blob()
    data = await stream.readall()
    my_blob.write(data)

Blob 열거

컨테이너의 Blob 나열

from azure.storage.blob import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = container.list_blobs()
for blob in blob_list:
    print(blob.name + '\n')

비동기적으로 Blob 나열

from azure.storage.blob.aio import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = []
async for blob in container.list_blobs():
    blob_list.append(blob)
print(blob_list)

선택적 구성

클라이언트 및 작업별 수준에서 전달할 수 있는 선택적 키워드(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) 인수를 사용합니다.

require_encryption (부울): True로 설정하면 개체가 암호화되고 암호가 해독됩니다.
encryption_version (str): 사용할 암호화 버전을 지정합니다. 현재 옵션은 '2.0' 또는 '1.0' 이며 기본값은 입니다 '1.0'. 버전 1.0은 더 이상 사용되지 않으며 버전 2.0을 사용하는 것이 좋습니다 .
key_encryption_key (개체): 사용자가 제공한 키-암호화 키입니다. instance 다음 메서드를 구현해야 합니다.
- wrap_key(key)--는 사용자가 선택한 알고리즘을 사용하여 지정된 키를 래핑합니다.
- get_key_wrap_algorithm()--은 지정된 대칭 키를 래핑하는 데 사용되는 알고리즘을 반환합니다.
- get_kid()--이 key-encryption-key에 대한 문자열 키 ID를 반환합니다.
key_resolver_function (호출 가능): 사용자가 제공한 키 확인자입니다. kid 문자열을 사용하여 위에 정의된 인터페이스를 구현하는 키 암호화 키를 반환합니다.

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

클라이언트 또는 작업별로 지정할 수 있는 다른 선택적 구성 키워드(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}

문제 해결

일반

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

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

로깅

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

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

import sys
import logging
from azure.storage.blob import BlobServiceClient

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

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

service_client.get_service_stats(logging_enable=True)

다음 단계

추가 샘플 코드

Blob 샘플을 시작합니다.

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

blob_samples_container_access_policy.py (비동기 버전) - 액세스 정책을 설정하는 예제:
- 컨테이너에 대한 액세스 정책 설정
blob_samples_hello_world.py (비동기 버전) - 일반적인 Storage Blob 작업의 예:
- 컨테이너 설정
- 블록, 페이지 또는 추가 Blob 만들기
- Blob 업로드
- Blob 다운로드
- Blob 삭제
blob_samples_authentication.py (비동기 버전) - 클라이언트를 인증하고 만드는 예제:
- 연결 문자열
- 공유 액세스 키에서
- 공유 액세스 서명 토큰에서
- Active Directory에서
blob_samples_service.py (비동기 버전) - Blob 서비스와 상호 작용하는 예제:
- 계정 정보 가져오기
- 서비스 속성 가져오기 및 설정
- 서비스 통계 가져오기
- 컨테이너 만들기, 나열 및 삭제
- Blob 또는 컨테이너 클라이언트 가져오기
blob_samples_containers.py (비동기 버전) - 컨테이너와 상호 작용하는 예제:
- 컨테이너 만들기 및 컨테이너 삭제
- 컨테이너에서 메타데이터 설정
- 컨테이너 속성 가져오기
- 컨테이너에서 임대 취득
- 컨테이너에서 액세스 정책 설정
- 컨테이너에서 Blob 업로드, 나열, 삭제
- 특정 Blob과 상호 작용할 Blob 클라이언트 가져오기
blob_samples_common.py (비동기 버전) - 모든 유형의 Blob에 공통적인 예:
- 스냅샷 만들기
- Blob 스냅샷 삭제
- Blob 일시 삭제
- Blob 삭제 취소
- Blob에서 임대 획득
- URL에서 Blob 복사
blob_samples_directory_interface.py - 파일 시스템의 디렉터리인 것처럼 Blob Storage와 상호 작용하는 예제:
- 단일 파일 또는 디렉터리 복사(업로드 또는 다운로드)
- 단일 수준에서 또는 재귀적으로 파일 또는 디렉터리 나열
- 단일 파일을 삭제하거나 디렉터리를 재귀적으로 삭제합니다.

추가 설명서

Azure Blob Storage에 대한 보다 광범위한 설명서는 docs.microsoft.com Azure Blob Storage 설명서를 참조하세요 .

참여

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

다음을 통해 공유