適用於 Python 使用模式的 Azure 連結庫

適用於 Python 的 Azure SDK 是由許多獨立連結庫所組成，這些連結庫列在 Python SDK 套件索引上。

所有程式庫都共用某些通用特性和使用模式，例如安裝和對物件參數使用內嵌 JSON。

設定本機開發環境

如果您尚未這麼做，您可以設定可以執行此程式碼的環境。 以下是一些選項：

• 使用 venv 或您選擇的工具設定 Python 虛擬環境。 若要開始使用虛擬環境，請務必加以啟用。 若要安裝 Python，請參閱 安裝 Python。

  Bash

  #!/bin/bash
  # Create a virtual environment
  python -m venv .venv
  # Activate the virtual environment
  source .venv/Scripts/activate # only required for Windows (Git Bash)
  

  PowerShell

  # PowerShell syntax
  # Create a virtual environment
  python -m venv venv
  # Activate the virtual environment
  . .\venv\Scripts\Activate.ps1
  

• 使用 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 連結庫套件。

conda

若要在 Conda 環境中安裝特定連結庫套件，請使用 conda install：

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

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

REM Install the azure identity library for Azure authentication
pip install azure-identity

conda install 會取得您目前 Conda 環境中的套件的最新版本。

如需詳細資訊，包括如何移除套件或安裝特定版本，請參閱 如何安裝適用於 Python 的 Azure 連結庫套件。

非同步作業

異步函式庫

許多用戶端和管理連結庫都提供異步版本 （.aio）。 asyncio 庫自 Python 3.4 起已提供，而 async/await 關鍵詞是在 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。

下列程式代碼示範如何建立 Python 檔案，示範如何為 Azure Blob 記憶體連結庫的異步版本建立用戶端：

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())

完整範例位於 gitHub 上 ，位於 use_blob_auth_async.py。 如需此程式代碼的同步版本，請參閱 範例：上傳 Blob。

長時間執行的作業

您叫用的某些管理作業（例如 ComputeManagementClient.virtual_machines.begin_create_or_update 和 WebAppsClient.web_apps.begin_create_or_update）會傳回針對長時間執行之作業的輪詢器，其中 LROPoller[<type>] 是特定於相關作業的。

備註

您可能會注意到程式庫中的方法名稱差異，這取決於其版本以及是否基於 azure.core。 不是以 azure.core 為基礎的舊版連結庫通常會使用類似 create_or_update的名稱。 以 azure.core 為基礎的程式庫會將 begin_ 前綴新增至方法名稱，以更清楚地表示它們是長時間輪詢的操作。 將舊程式代碼移轉至較新的 azure.core 連結庫通常表示將 begin_ 前置詞新增至方法名稱，因為大部分的方法簽章都保持不變。

傳回類型 LROPoller 表示作業是非同步的。 因此，您必須呼叫該輪詢器的方法 result 來等候作業完成並取得其結果。

下列程式代碼取自 範例：建立及部署 Web 應用程式，顯示使用輪詢器等候結果的範例：

# 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 程式庫中記錄功能。

Proxy 設定

若要指定 Proxy，您可以使用環境變數或選擇性自變數。 如需詳細資訊，請參閱 如何設定 Proxy。

客戶端物件和方法的選擇性自變數

在連結庫參考檔中，您通常會在用戶端物件建構函式或特定作業方法的簽章中看到 **kwargs 或 **operation_config 自變數。 這些佔位元表示相關的物件或方法可能支援其他具名參數。 一般而言，參考檔會指出您可以使用的特定自變數。 也有一些普遍的論點通常會被支持，如下所述。

基於 azure.core 的函式庫參數

這些自變數適用於 Python - 新連結庫上所列的連結庫。 例如，以下是 的 azure-core關鍵詞自變量子集。 如需完整清單，請參閱 適用於 azure 核心的 GitHub 自述檔。

名稱	類型	預設	說明
啟用日誌記錄	布爾 (bool)	否	啟用記錄。 如需詳細資訊，請參閱 在 Azure 程式庫中記錄功能。
代理	dict	{}	Proxy 伺服器 URL。 如需詳細資訊，請參閱 如何設定 Proxy。
使用環境設定	布爾 (bool)	對	如果為 True，則允許對 HTTP_PROXY Proxy 使用 和 HTTPS_PROXY 環境變數。 如果為 False，則會忽略環境變數。 如需詳細資訊，請參閱 如何設定 Proxy。
連線逾時	整數 (int)	300	對 Azure REST API 端點進行連線的逾時，以秒為單位。
讀取超時 (read_timeout)	整數 (int)	300	完成 Azure REST API 作業的逾時以秒為單位（也就是等候回應）。
重試總數	整數 (int)	10	REST API 呼叫允許重試次數。 使用 retry_total=0 來停用重試。
重試模式	列舉	指數	以線性或指數方式套用重試計時。 如果為 'single'，則會定期重試。 如果為「指數」，每次重試的等待時間是前一次重試的兩倍。

各個程式庫無需支援這些論點，因此請務必查閱每個程式庫的參考文件，以獲取精確的細節信息。 此外，每個連結庫可能支援其他自變數。 例如，如需 Blob 記憶體特定的關鍵詞自變數，請參閱 適用於 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包含類型為Sku和list[AccessPolicyEntry]的物件參數。 Sku包含 SkuName 物件，而且每個AccessPolicyEntry物件都包含 Permissions 物件。

若要使用內嵌物件呼叫 begin_create_or_update ，您可以使用如下的程式代碼（假設 tenant_id已定義、 object_id和 LOCATION ）。 您也可以在函數調用之前建立必要的物件。

# 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 格式不正確，您通常會收到錯誤「解序列化錯誤：無法將字串解序列化為物件：type，屬性錯誤： 'str' 物件沒有屬性 'get'」。 此錯誤的常見原因是當連結庫預期有巢狀 JSON 物件時，您會為屬性提供單一字串。 例如在上一個範例中使用'sku': 'standard'會產生此錯誤，因為sku參數是期待內嵌物件 JSON 的Sku物件，在這個情況下，{'name': 'standard'}會映射到預期的SkuName類型。

後續步驟

既然您已瞭解使用適用於 Python 的 Azure 連結庫的常見模式，請參閱下列獨立範例來探索特定管理和客戶端連結庫案例。 您可以依任何順序嘗試這些範例，因為它們不是循序或相互依存的。

• 範例：建立資源群組

• 範例：使用 Azure 儲存體

• 範例：建立 Web 應用程式並部署程式代碼

• 範例：建立和查詢資料庫

• 範例：建立虛擬機

• 搭配虛擬機器使用 Azure 受控磁碟

• 完成 Azure SDK for Python 的簡短問卷