Python용 Azure SDK는 Python SDK 패키지 인덱스로 나열되는 많은 독립 라이브러리로 구성됩니다.
모든 라이브러리는 개체 인수에 대한 인라인 JSON의 설치 및 사용과 같은 특정 일반적인 특성 및 사용 패턴을 공유합니다.
로컬 개발 환경 설정
아직 실행하지 않은 경우 이 코드를 실행할 수 있는 환경을 설정할 수 있습니다. 몇 가지 옵션은 다음과 같습니다.
선택한 도구를 사용하거나
venv, Python 가상 환경을 구성합니다. 가상 환경 사용을 시작하려면 가상 환경을 활성화해야 합니다. Python을 설치하려면 Python 설치를 참조하세요.#!/bin/bash # Create a virtual environment python -m venv .venv # Activate the virtual environment source .venv/Scripts/activate # only required for Windows (Git Bash)conda 환경을 사용합니다. Conda를 설치하려면 Miniconda 설치를 참조하세요.
Visual Studio Code 또는 GitHub Codespaces에서 개발 컨테이너를 사용합니다.
라이브러리 설치
Python 환경 관리 도구(pip 또는 conda)에 해당하는 설치 방법을 선택합니다.
특정 라이브러리 패키지를 설치하려면 다음을 사용합니다 pip install.
REM Install the management library for Azure Storage
pip install azure-mgmt-storage
REM Install the client library for Azure Blob Storage
pip install azure-storage-blob
REM Install the azure identity library for Azure authentication
pip install azure-identity
pip install 는 현재 Python 환경에서 최신 버전의 라이브러리를 검색합니다.
라이브러리를 제거하고 미리 보기 버전을 포함하여 특정 버전을 설치하는 데 사용할 pip 수도 있습니다. 자세한 내용은 Python용 Azure 라이브러리 패키지를 설치하는 방법을 참조하세요.
비동기 작업
비동기 라이브러리
많은 클라이언트 및 관리 라이브러리는 비동기 버전(.aio)을 제공합니다. 이 라이브러리는 asyncio Python 3.4부터 사용할 수 있으며 Python 3.5에서 비동기/대기 키워드가 도입되었습니다. 라이브러리의 비동기 버전은 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을 제공하므로 별도로 설치 aiohttp 할 필요가 없습니다.
다음 코드는 Azure Blob Storage 라이브러리의 비동기 버전에 대한 클라이언트를 만드는 방법을 보여 주는 Python 파일을 만드는 방법을 보여 줍니다.
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_update 및 WebAppsClient.web_apps.begin_create_or_update)은 장기 실행 작업에 대한 폴러를 반환합니다 LROPoller[<type>]. 여기서 <type> 는 해당 작업과 관련이 있습니다.
비고
라이브러리의 버전 및 azure.core를 기반으로 하는지 여부에 따라 라이브러리의 메서드 이름에 차이가 있을 수 있습니다. azure.core를 기반으로 하지 않는 이전 라이브러리는 일반적으로 다음과 같은 create_or_update이름을 사용합니다. azure.core를 기반으로 하는 라이브러리는 begin_ 메서드 이름에 접두사를 추가하여 긴 폴링 작업임을 더 잘 나타냅니다. 이전 코드를 최신 azure.core 기반 라이브러리로 마이그레이션하는 것은 일반적으로 대부분의 메서드 서명이 동일하게 유지되므로 메서드 이름에 접두사를 추가하는 begin_ 것을 의미합니다.
반환 형식은 LROPoller 작업이 비동기임을 의미합니다. 따라서 작업이 완료될 때까지 기다렸다가 결과를 얻기 위해 해당 폴러의 result 메서드를 호출해야 합니다.
예제에서 가져온 다음 코드 : 웹앱 만들기 및 배포는 폴러를 사용하여 결과를 기다리는 예제를 보여줍니다.
# Step 3: With the plan in place, provision the web app itself, which is the process that can host
# whatever code we want to deploy to it.
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 - 새 라이브러리에 나열된 라이브러리에 적용됩니다. 예를 들어 다음은 에 대한 키워드 인수의 하위 집합입니다 azure-core. 전체 목록은 azure-core에 대한 GitHub 추가 정보입니다.
| 이름 | 유형 | 기본값 | 설명 |
|---|---|---|---|
| 로그 활성화 | bool | 거짓 | 로깅을 사용하도록 설정합니다. 자세한 내용은 Azure 라이브러리의 로깅을 참조하세요. |
| 프록시 | 사전 | {} | 프록시 서버 URL입니다. 자세한 내용은 프록시를 구성하는 방법을 참조하세요. |
| 환경_설정_사용 | bool | 진실 | True이면 프록시에 HTTP_PROXY 대한 환경 변수 및 HTTPS_PROXY 환경 변수를 사용할 수 있습니다. False이면 환경 변수가 무시됩니다. 자세한 내용은 프록시를 구성하는 방법을 참조하세요. |
| 연결_시간_초과 | 정수 (int) | 300 | Azure REST API 엔드포인트에 연결하기 위한 시간 제한(초)입니다. |
| 읽기_시간초과 | 정수 (int) | 300 | Azure REST API 작업을 완료하기 위한 시간 제한(초)입니다(즉, 응답을 기다리는 중). |
| 재시도_전체 | 정수 (int) | 10 | REST API 호출에 대해 허용되는 재시도 횟수입니다. 재시도를 비활성화하려면 retry_total=0를 사용하세요. |
| 재시도_모드 | enum | 지수의 | 선형 또는 지수 방식으로 재시도 타이밍을 적용합니다. 'single'이면 정기적으로 재시도합니다. '지수'이면 각 재시도는 이전 재시도보다 두 배 정도 대기합니다. |
개별 라이브러리는 이러한 인수를 지원할 의무가 없으므로 정확한 세부 정보는 항상 각 라이브러리에 대한 참조 설명서를 참조하세요. 또한 각 라이브러리는 다른 인수를 지원할 수 있습니다. 예를 들어 Blob Storage 관련 키워드 인수의 경우 azure-storage-blob에 대한 GitHub README를 참조하세요.
개체 인수에 대한 인라인 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는 Sku 및 list[AccessPolicyEntry] 형식의 개체 인수를 순차적으로 포함합니다. A 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 매개변수가 인라인 개체 JSON을 기대하는 Sku 개체이기 때문에 이 오류가 발생합니다. 이 경우, {'name': 'standard'}은(는) 예상 SkuName 유형에 매핑됩니다.
다음 단계
이제 Python용 Azure 라이브러리를 사용하는 일반적인 패턴을 이해했으므로 다음 독립 실행형 예제를 참조하여 특정 관리 및 클라이언트 라이브러리 시나리오를 살펴봅니다. 순차적이거나 상호 의존적이지 않으므로 이러한 예제를 순서대로 사용해 볼 수 있습니다.