Python용 Azure 라이브러리 사용 패턴

아티클
10/23/2023

Python용 Azure SDK는 Python SDK 패키지 인덱스로 나열되는 많은 독립 라이브러리로 구성됩니다.

모든 라이브러리는 개체 인수에 대한 인라인 JSON의 설치 및 사용과 같은 특정 일반적인 특성 및 사용 패턴을 공유합니다.

로컬 개발 환경 설정

아직 실행하지 않은 경우 이 코드를 실행할 수 있는 환경을 설정할 수 있습니다. 다음은 몇 가지 옵션입니다.

Python 가상 환경을 구성합니다. 로컬 또는 Azure Cloud Shell에서 가상 환경을 만들고 해당 환경에서 코드를 실행할 수 있습니다. 가상 환경을 활성화하여 사용을 시작해야 합니다.
conda 환경을 사용합니다.
Visual Studio Code 또는 GitHub Codespaces에서 개발 컨테이너를 사용합니다.

특정 라이브러리 패키지를 설치하려면 다음을 사용합니다 pip install.

# Install the management library for Azure Storage
pip install azure-mgmt-storage

# Install the client library for Azure Blob Storage
pip install azure-storage-blob

pip install 는 현재 Python 환경에서 최신 버전의 라이브러리를 검색합니다.

pip를 사용하여 라이브러리를 제거하고 미리 보기 버전을 비롯한 특정 버전을 설치할 수도 있습니다. 자세한 내용은 Python용 Azure 라이브러리 패키지를 설치하는 방법을 참조 하세요.

Conda 환경에 특정 라이브러리 패키지를 설치하려면 다음을 사용합니다 conda install.

# Install the Azure management library package
conda install azure-mgmt

# Install the client library for Azure Storage
conda install azure-storage

conda install 는 현재 Conda 환경에서 패키지의 최신 버전을 검색합니다.

패키지를 제거하거나 특정 버전을 설치하는 방법을 비롯한 자세한 내용은 Python용 Azure 라이브러리 패키지를 설치하는 방법을 참조하세요.

비동기 작업

비동기 라이브러리

많은 클라이언트 및 관리 라이브러리는 비동기 버전(.aio)을 제공합니다. 이 라이브러리는 asyncio Python 3.4부터 사용할 수 있으며 Python 3.5에서 비동기/대기 키워드(keyword) 도입되었습니다. 라이브러리의 비동기 버전은 Python 3.5 이상에서 사용됩니다.

비동기 버전을 사용하는 Azure Python SDK 라이브러리의 예로는 azure.storage.blob.aio, azure.servicebus.aio, azure.mgmt.keyvault.aio 및 azure.mgmt.compute.aio가 있습니다.

이러한 라이브러리는 작동하는 것과 같은 aiohttp 비동기 전송이 필요합니다. 라이브러리는 azure-core 비동기 라이브러리에서 사용하는 비동기 전송 AioHttpTransport을 제공합니다.

다음 코드는 Azure Blob Storage 라이브러리의 비동기 버전에 대한 클라이언트를 만드는 방법을 보여 줍니다.

credential = DefaultAzureCredential()

async def run():

    async with BlobClient(
        storage_url,
        container_name="blob-container-01",
        blob_name=f"sample-blob-{str(uuid.uuid4())[0:5]}.txt",
        credential=credential,
    ) as blob_client:

        # Open a local file and upload its contents to Blob Storage
        with open("./sample-source.txt", "rb") as data:
            await blob_client.upload_blob(data)
            print(f"Uploaded sample-source.txt to {blob_client.url}")

        # Close credential
        await credential.close()

asyncio.run(run())

전체 예제는 use_blob_auth_async.py GitHub에 있습니다. 이 코드의 동기 버전은 예제: Blob 업로드를 참조하세요.

장기 실행 작업

호출하는 일부 관리 작업(예: ComputeManagementClient.virtual_machines.begin_create_or_updateWebSiteManagementClient.web_apps.begin_create_or_update 장기 실행 작업에 대한 폴러 반환, LROPoller[<type>]해당 작업과 관련된 위치 <type> )

참고 항목

버전 차이로 인해 라이브러리의 메서드 이름에 차이가 있을 수 있습니다. azure.core를 기반으로 하지 않는 이전 라이브러리는 일반적으로 다음과 같은 create_or_update이름을 사용합니다. azure.core를 기반으로 하는 라이브러리는 begin_ 메서드 이름에 접두사를 추가하여 긴 폴링 작업임을 더 잘 나타냅니다. 이전 코드를 최신 azure.core 기반 라이브러리로 마이그레이션하는 것은 일반적으로 대부분의 메서드 시그니처가 동일한 기본 메서드 이름에 접두사를 추가하는 begin_ 것을 의미합니다.

반환 형식은 LROPoller 작업이 비동기임을 의미합니다. 따라서 해당 폴러의 result 메서드를 호출한 후, 작업이 완료되고 작업 결과를 얻게 될 때까지 기다려야 합니다.

예제에서 가져온 다음 코드: 웹앱 만들기 및 배포는 폴러를 사용하여 결과를 기다리는 예제를 보여줍니다.

poller = app_service_client.web_apps.begin_create_or_update(RESOURCE_GROUP_NAME,
    WEB_APP_NAME,
    {
        "location": LOCATION,
        "server_farm_id": plan_result.id,
        "site_config": {
            "linux_fx_version": "python|3.8"
        }
    }
)

web_app_result = poller.result()

이 경우 반환 값은 begin_create_or_update 형식 AzureOperationPoller[Site]입니다. 즉, 반환 값 poller.result() 이 Site 개체임을 의미합니다.

예외

일반적으로 Azure 라이브러리는 Azure REST API에 대한 실패한 HTTP 요청을 포함하여 작업이 의도한 대로 수행되지 않으면 예외를 발생합니다. 앱 코드의 경우 라이브러리 작업과 관련한 블록을 사용할 try...except 수 있습니다.

발생할 수 있는 예외 유형에 대한 자세한 내용은 해당 작업에 대한 설명서를 참조하세요.

로깅

최신 Azure 라이브러리는 Python 표준 logging 라이브러리를 사용하여 로그 출력을 생성합니다. 개별 라이브러리, 라이브러리 그룹 또는 모든 라이브러리에 대한 로깅 수준을 설정할 수 있습니다. 로깅 스트림 처리기를 등록한 후 특정 클라이언트 개체 또는 특정 작업에 대한 로깅을 사용하도록 설정할 수 있습니다. 자세한 내용은 Azure 라이브러리의 로깅을 참조하세요.

프록시 구성

프록시를 지정하려면 환경 변수 또는 선택적 인수를 사용할 수 있습니다. 자세한 내용은 프록시를 구성하는 방법을 참조하세요.

클라이언트 개체 및 메서드에 대한 선택적 인수

라이브러리 참조 설명서에서 **kwargs 또는 **operation_config 인수는 클라이언트 개체 생성자 또는 특정 작업 메서드의 서명에 표시되는 경우가 많습니다. 이러한 자리 표시자는 해당 개체 또는 메서드가 다른 명명된 인수를 지원할 수 있음을 나타냅니다. 일반적으로 참조 설명서는 사용할 수 있는 특정 인수를 나타냅니다. 다음 섹션에 설명된 대로 종종 지원되는 몇 가지 일반적인 인수도 있습니다.

azure.core를 기반으로 하는 라이브러리에 대한 인수

이러한 인수는 Python - 새 라이브러리에 나열된 라이브러리에 적용됩니다. 예를 들어 다음은 에 대한 키워드(keyword) 인수의 하위 집합입니다azure-core. 전체 목록은 azure-core에 대한 GitHub 추가 정보입니다.

속성	Type	기본값	설명
logging_enable	bool	False	로깅을 사용하도록 설정합니다. 자세한 내용은 Azure 라이브러리의 로깅을 참조하세요.
프록시	dict	{}	프록시 서버 URL입니다. 자세한 내용은 프록시를 구성하는 방법을 참조하세요.
use_env_settings	bool	True	True이면 프록시에 `HTTP_PROXY` 대한 환경 변수 및 `HTTPS_PROXY` 환경 변수를 사용할 수 있습니다. False이면 환경 변수가 무시됩니다. 자세한 내용은 프록시를 구성하는 방법을 참조하세요.
connection_timeout	int	300	Azure REST API 엔드포인트에 연결하는 데 적용되는 시간 제한(초)입니다.
read_timeout	int	300	Azure REST API 작업을 완료하기 위한 시간 제한(초)입니다(즉, 응답을 기다리는 중).
retry_total	int	10	REST API 호출에 대해 허용되는 재시도 횟수입니다. 재시도를 사용하지 않도록 설정하는 데 사용합니다 `retry_total=0` .
retry_mode	열거형	exponential	선형 또는 지수 방식으로 재시도 타이밍을 적용합니다. 'single'이면 정기적으로 재시도합니다. 'exponential'이면 각 재시도에서 이전 재시도보다 두 배 더 오래 기다립니다.

개별 라이브러리는 이러한 인수를 지원할 의무가 없으므로 정확한 세부 정보는 항상 각 라이브러리에 대한 참조 설명서를 참조하세요. 또한 각 라이브러리는 다른 인수를 지원할 수 있습니다. 예를 들어 Blob Storage 관련 키워드(keyword) 인수의 경우 azure-storage-blob에 대한 GitHub 추가 정보를 참조하세요.

개체 인수에 대한 인라인 JSON 패턴

Azure 라이브러리 내의 많은 작업을 통해 개체 인수를 불연속 개체 또는 인라인 JSON으로 표현할 수 있습니다.

예를 들어 메서드를 사용하여 ResourceManagementClient 리소스 그룹을 create_or_update 만드는 개체가 있다고 가정합니다. 이 메서드의 두 번째 인수는 형식 ResourceGroup입니다.

메서드를 create_or_update 호출하려면 필요한 인수를 사용하여 직접 개별 인스턴스 ResourceGroup 를 만들 수 있습니다(location 이 경우).

# Provision the resource group.
rg_result = resource_client.resource_groups.create_or_update(
    "PythonSDKExample-rg",
    ResourceGroup(location="centralus")
)

또는 인라인 JSON과 동일한 매개 변수를 전달할 수 있습니다.

# Provision the resource group.
rg_result = resource_client.resource_groups.create_or_update(
    "PythonAzureExample-rg", {"location": "centralus"}
)

인라인 JSON을 사용하는 경우 Azure 라이브러리는 인라인 JSON을 해당 인수에 적합한 개체 형식으로 자동으로 변환합니다.

개체에는 중첩된 개체 인수가 있을 수도 있습니다. 이 경우 중첩된 JSON을 사용할 수도 있습니다.

예를 들어 KeyVaultManagementClient 개체 인스턴스가 있고 해당 create_or_update 메서드를 호출한다고 가정하겠습니다. 이 경우 세 번째 인수는 형식 VaultCreateOrUpdateParameters이며, 그 자체에는 형식 VaultProperties의 인수가 포함됩니다. VaultProperties는 형식 및 list[AccessPolicyEntry].의 개체 인수를 Sku 차례로 포함합니다. Sku는 SkuName 개체를 포함하고 각 AccessPolicyEntry는 Permissions 개체를 포함합니다.

포함된 개체를 사용하여 호출 begin_create_or_update 하려면 다음과 같은 코드를 사용합니다(이미 정의되어 있다고 가정tenant_idobject_idLOCATION). 함수를 호출하기 전에 필요한 개체를 만들 수도 있습니다.

# Provision a Key Vault using inline parameters
poller = keyvault_client.vaults.begin_create_or_update(
    RESOURCE_GROUP_NAME,
    KEY_VAULT_NAME_A,
    VaultCreateOrUpdateParameters(
        location = LOCATION,
        properties = VaultProperties(
            tenant_id = tenant_id,
            sku = Sku(
                name="standard",
                family="A"
            ),            
            access_policies = [
                AccessPolicyEntry(
                    tenant_id = tenant_id,
                    object_id = object_id,
                    permissions = Permissions(
                        keys = ['all'],
                        secrets = ['all']
                    )
                )
            ]
        )
    )
)

key_vault1 = poller.result()

인라인 JSON을 사용하는 동일한 호출은 다음과 같이 표시됩니다.

# Provision a Key Vault using inline JSON
poller = keyvault_client.vaults.begin_create_or_update(
    RESOURCE_GROUP_NAME,
    KEY_VAULT_NAME_B,
    {
        'location': LOCATION,
        'properties': {
            'sku': {
                'name': 'standard',
                'family': 'A'
            },
            'tenant_id': tenant_id,
            'access_policies': [{
                'tenant_id': tenant_id,
                'object_id': object_id,                
                'permissions': {
                    'keys': ['all'],
                    'secrets': ['all']
                }
            }]
        }
    }
)

key_vault2 = poller.result()

두 양식이 모두 동일하기 때문에 원하는 폼을 선택하고 섞을 수도 있습니다. (이러한 예제의 전체 코드는 다음에서 찾을 수 있습니다.GitHub.)

JSON이 제대로 구성되지 않은 경우 일반적으로 "DeserializationError: 개체로 역직렬화할 수 없습니다. type, AttributeError: 'str' 개체에 특성 'get'이 없습니다."라는 오류가 발생합니다. 이 오류의 일반적인 원인은 라이브러리에 중첩된 JSON 개체가 필요할 때 속성에 단일 문자열을 제공하기 때문입니다. 예를 들어 앞의 예제에서 'sku': 'standard'를 사용하면 이러한 오류가 발생합니다. sku 매개 변수는 Sku 개체이고 이 개체에는 필요한 SkuName 형식에 매핑되는 인라인 개체 JSON(이 경우, {'name': 'standard'})이 필요하기 때문입니다.

다음 단계

이제 Python용 Azure 라이브러리 사용에 대한 일반적인 패턴을 이해했으며, 이제 다음 독립 실행형 예제를 참조하여 특정 관리 및 클라이언트 라이브러리 시나리오를 살펴보세요. 순차적이거나 상호 의존적이지 않으므로 이러한 예제를 순서대로 사용해 볼 수 있습니다.