Azure Blob Storage 및 Python 시작

아티클
10/03/2024

이 문서에서는 Python용 Azure Blob Storage 클라이언트 라이브러리를 사용하여 Azure Blob Storage에 연결하는 방법을 보여 줍니다. 연결되면 개발자 가이드를 사용하여 Blob Storage 서비스의 컨테이너, Blob 및 기능에서 코드가 작동하는 방법을 알아봅니다.

전체 예제로 시작하려면 빠른 시작: Python용 Azure Blob Storage 클라이언트 라이브러리를 참조하세요.

API 참조 | 패키지(PyPi) | 라이브러리 소스 코드 | 샘플 | 피드백 제공

필수 조건

Azure 구독 - 체험 구독 만들기
Azure Storage 계정 - 스토리지 계정 만들기
Python 3.8+

프로젝트 설정

이 섹션에서는 Python용 Azure Blob Storage 클라이언트 라이브러리를 사용하는 프로젝트를 준비합니다.

프로젝트 디렉터리에서 pip install 명령을 사용하여 Azure Blob Storage 및 Azure ID 클라이언트 라이브러리용 패키지를 설치합니다. Azure 서비스에 암호 없이 연결하려면 azure-identity 패키지가 필요합니다.

pip install azure-storage-blob azure-identity

그런 다음 코드 파일을 열고 필요한 가져오기 문을 추가합니다. 이 예에서는 .py 파일에 다음을 추가합니다.

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, BlobClient, ContainerClient

Blob 클라이언트 라이브러리 정보:

azure.storage.blob: 서비스, 컨테이너 및 Blob에서 작업하는 데 사용할 수 있는 기본 클래스(클라이언트 개체)가 포함되어 있습니다.

비동기 프로그래밍

Python용 Azure Blob Storage 클라이언트 라이브러리는 동기 및 비동기 API를 모두 지원합니다. 비동기 API는 Python의 asyncio 라이브러리를 기반으로 합니다.

프로젝트에서 비동기 API를 사용하려면 다음 단계를 수행합니다.

aiohttp와 같은 비동기 전송을 설치합니다. 선택적 종속성 설치 명령을 사용하여 azure-storage-blob과 함께 aiohttp를 설치할 수 있습니다. 이 예제에서는 다음 pip install 명령을 사용합니다.
```
pip install azure-storage-blob[aio]
```
코드 파일을 열고 필요한 import 문을 추가합니다. 이 예에서는 .py 파일에 다음을 추가합니다.
```
import asyncio

from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient, BlobClient, ContainerClient
```
import asyncio 문은 코드에서 라이브러리를 사용하는 경우에만 필요합니다. 개발자 가이드 문서의 예제에서는 asyncio 라이브러리를 사용하므로 명확성을 위해 여기에 추가됩니다.
async with를 사용하여 클라이언트 개체를 만들어 데이터 리소스 작업을 시작합니다. 최상위 클라이언트에서만 async with를 사용해야 합니다. 최상의 클라이언트에서 만들어진 다른 클라이언트는 동일한 연결 풀을 공유하기 때문입니다. 이 예제에서는 async with를 사용하여 BlobServiceClient 개체를 만든 다음, ContainerClient 개체를 만듭니다.
```
async with BlobServiceClient(account_url, credential=credential) as blob_service_client:
    container_client = blob_service_client.get_container_client(container="sample-container")
```
자세한 내용은 액세스 권한 부여 및 Blob Storage 연결의 비동기 예제를 참조하세요.

Blob 비동기 클라이언트 라이브러리 정보:

azure.storage.blob.aio: 서비스, 컨테이너 및 Blob에서 비동기적으로 작업하는 데 사용할 수 있는 기본 클래스가 포함되어 있습니다.

액세스 권한 부여 및 Blob Storage에 연결

앱을 Blob Storage에 연결하려면 BlobServiceClient 클래스의 인스턴스를 만듭니다. 이 개체는 스토리지 계정 수준에서 데이터 리소스와 상호 작용하기 위한 시작점입니다. 이를 사용하여 스토리지 계정 및 해당 컨테이너에서 작업할 수 있습니다. 작업해야 하는 리소스에 따라 서비스 클라이언트를 사용하여 컨테이너 클라이언트 또는 Blob 클라이언트를 만들 수도 있습니다.

모범 사례를 포함하여 클라이언트 개체 만들기 및 관리에 대한 자세한 내용은 데이터 리소스와 상호 작용하는 클라이언트 개체 만들기 및 관리를 참조하세요.

Microsoft Entra 권한 부여 토큰, 계정 액세스 키 또는 SAS(공유 액세스 서명)를 사용하여 BlobServiceClient 개체에 권한을 부여할 수 있습니다. 최적의 보안을 위해 Microsoft는 관리 ID와 함께 Microsoft Entra ID를 사용하여 Blob 데이터에 대한 요청을 권한 부여하는 것이 좋습니다. 자세한 내용은 Azure Active Directory를 사용하여 Blob에 대한 액세스 권한 부여를 참조하세요.

Microsoft Entra ID로 권한을 부여하려면 보안 주체를 사용해야 합니다. 어떤 형식의 보안 주체가 필요한지는 앱이 실행되는 위치에 따라 달라집니다. 다음 표를 가이드로 따르세요.

앱이 실행되는 곳	할당할 수 있습니다.	지침
로컬 컴퓨터(개발 및 테스트)	서비스 사용자	앱 등록, Microsoft Entra 그룹 설정, 역할 할당, 환경 변수 구성 방법을 알아보려면 개발자 서비스 주체를 사용하여 액세스 권한 부여를 참조하세요.
로컬 컴퓨터(개발 및 테스트)	사용자 ID	Microsoft Entra 그룹을 설정하고, 역할을 할당하고, Azure에 로그인하는 방법을 알아보려면 개발자 자격 증명을 사용하여 액세스 권한 부여를 참조하세요.
Azure에서 호스트	관리 ID	관리 ID를 사용 설정하고 역할을 할당하는 방법을 알아보려면 관리 ID를 사용하여 Azure 호스트된 앱에서 액세스 권한 부여를 참조하세요.
Azure 외부에서 호스트됨(예: 온-프레미스 앱)	서비스 사용자	앱을 등록하고, 역할을 할당하고, 환경 변수를 구성하는 방법을 알아보려면 애플리케이션 서비스 주체를 사용하여 온-프레미스 앱에서 액세스 권한 부여를 참조하세요.

DefaultAzureCredential을 사용하여 액세스 권한 부여

액세스 권한을 부여하고 Blob Storage에 연결하는 쉽고 안전한 방법은 DefaultAzureCredential 인스턴스를 만들어 OAuth 토큰을 가져오는 것입니다. 그런 다음 해당 자격 증명을 사용하여 BlobServiceClient 개체를 만들 수 있습니다.

다음 예에서는 DefaultAzureCredential을 사용하여 BlobServiceClient 개체를 만듭니다.

def get_blob_service_client_token_credential(self):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    credential = DefaultAzureCredential()

    # Create the BlobServiceClient object
    blob_service_client = BlobServiceClient(account_url, credential=credential)

    return blob_service_client

프로젝트에서 비동기 API를 사용하는 경우 async with를 사용하여 BlobServiceClient를 인스턴스화합니다.

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"
credential = DefaultAzureCredential()

async with BlobServiceClient(account_url, credential=credential) as blob_service_client:
    # Work with data resources in the storage account

SAS(공유 액세스 서명) 토큰을 사용하려면 토큰을 문자열로 제공하고 BlobServiceClient 개체를 초기화합니다. 계정 URL에 SAS 토큰이 포함된 경우 자격 증명 매개 변수를 생략합니다.

def get_blob_service_client_sas(self, sas_token: str):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    # The SAS token string can be assigned to credential here or appended to the account URL
    credential = sas_token

    # Create the BlobServiceClient object
    blob_service_client = BlobServiceClient(account_url, credential=credential)

    return blob_service_client

프로젝트에서 비동기 API를 사용하는 경우 async with를 사용하여 BlobServiceClient를 인스턴스화합니다.

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"

# Replace <sas_token_str> with your actual SAS token
sas_token: str = "<sas_token_str>"

async with BlobServiceClient(account_url, credential=sas_token) as blob_service_client:
    # Work with data resources in the storage account

SAS 토큰 생성 및 관리에 대한 자세한 내용은 다음 문서를 참조하세요.

참고 항목

SAS(공유 액세스 서명)가 사용되는 시나리오의 경우 사용자 위임 SAS를 사용하는 것이 좋습니다. 사용자 위임 SAS는 계정 키 대신 Microsoft Entra 자격 증명으로 보호됩니다.

스토리지 계정 공유 키를 사용하려면 키를 문자열로 제공하고 BlobServiceClient 개체를 초기화합니다.

def get_blob_service_client_account_key(self):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    shared_access_key = os.getenv("AZURE_STORAGE_ACCESS_KEY")
    credential = shared_access_key

    # Create the BlobServiceClient object
    blob_service_client = BlobServiceClient(account_url, credential=credential)

    return blob_service_client

연결 문자열을 사용하여 BlobServiceClient 개체를 만들 수도 있습니다.

def get_blob_service_client_connection_string(self):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    connection_string = os.getenv("AZURE_STORAGE_CONNECTION_STRING")

    # Create the BlobServiceClient object
    blob_service_client = BlobServiceClient.from_connection_string(connection_string)

    return blob_service_client

프로젝트에서 비동기 API를 사용하는 경우 async with를 사용하여 BlobServiceClient를 인스턴스화합니다.

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"

shared_access_key = os.getenv("AZURE_STORAGE_ACCESS_KEY")

async with BlobServiceClient(account_url, credential=shared_access_key) as blob_service_client:
    # Work with data resources in the storage account

계정 키를 얻는 방법과 키를 적절하게 관리하고 보호하기 위한 모범 사례 가이드라인에 대한 자세한 내용은 스토리지 계정 액세스 키 관리를 참조하세요.

Important

계정 액세스 키는 신중하게 사용해야 합니다. 계정 액세스 키가 손실하거나 실수로 안전하지 않은 위치에 배치되는 경우 서비스가 취약해질 수 있습니다. 액세스 키가 있는 사람은 누구나 스토리지 계정에 대한 요청에 권한을 부여할 수 있으며 모든 데이터에 효과적으로 액세스할 수 있습니다. DefaultAzureCredential은 향상된 보안 기능과 이점을 제공하며 Azure 서비스에 대한 권한 부여를 관리하는 데 권장되는 방법입니다.

앱 빌드

Azure Blob Storage 데이터 리소스를 사용하는 앱을 빌드할 때 코드는 주로 스토리지 계정, 컨테이너 및 Blob의 세 가지 리소스 종류와 상호 작용합니다. 이러한 리소스 종류, 서로 상호 작용하는 방법 및 앱이 리소스와 상호 작용하는 방법에 대한 자세한 내용은 앱이 Blob Storage 데이터 리소스와 상호 작용하는 방법 이해를 참조하세요.

다음 가이드에서는 Python용 Azure Storage 클라이언트 라이브러리를 사용하여 데이터에 액세스하고 특정 작업을 수행하는 방법을 보여 줍니다.

가이드	설명
재시도 정책 구성	클라이언트 작업에 대한 다시 시도 정책을 구현합니다.
Blob 복사	한 위치에서 다른 위치로 Blob을 복사합니다.
컨테이너 만들기	Blob 컨테이너를 만듭니다.
사용자 위임 SAS 만들기:	컨테이너 또는 Blob에 대한 사용자 위임 SAS를 만듭니다.
Blob 임대 만들기 및 관리	Blob에 대한 잠금을 설정하고 관리합니다.
컨테이너 임대 만들기 및 관리	컨테이너에 대한 잠금을 설정하고 관리합니다.
Blob 삭제 및 복원	Blob을 삭제하고 일시 삭제된 Blob을 복원합니다.
컨테이너 삭제 및 복원	컨테이너를 삭제하고 일시 삭제된 컨테이너를 복원합니다.
Blob 다운로드	문자열, 스트림 및 파일 경로를 사용하여 Blob을 다운로드합니다.
태그를 사용하여 Blob 찾기	태그를 설정 및 검색하고 태그를 사용하여 Blob을 찾습니다.
Blob 나열	다양한 방법으로 Blob을 나열합니다.
컨테이너 나열	계정의 컨테이너와 목록을 사용자 지정하는 데 사용할 수 있는 다양한 옵션을 나열합니다.
속성 및 메타데이터(blob) 관리	Blob에 대한 속성 및 메타데이터를 가져오고 설정합니다.
속성 및 메타데이터(컨테이너) 관리	컨테이너의 속성과 메타데이터를 가져오고 설정합니다.
데이터 전송 성능 튜닝	데이터 전송 작업의 성능을 최적화합니다.
Blob의 액세스 계층 설정 또는 변경	블록 Blob에 대한 액세스 계층을 설정하거나 변경합니다.
Blob 업로드	문자열, 스트림, 파일 경로 및 기타 방법을 사용하여 Blob을 업로드하는 방법을 알아봅니다.

다음을 통해 공유

Azure Blob Storage 및 Python 시작

필수 조건

프로젝트 설정

비동기 프로그래밍

액세스 권한 부여 및 Blob Storage에 연결

DefaultAzureCredential을 사용하여 액세스 권한 부여

앱 빌드

피드백

추가 리소스