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

發行項
12/14/2023

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

所有連結庫都會共用特定通用特性和使用模式，例如安裝和針對物件自變數使用內嵌 JSON。

設定本機開發環境

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

使用 venv 或您選擇的工具設定 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 起已提供，而異步/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由異步連結庫使用。

下列程式代碼示範如何為 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 ，並 WebSiteManagementClient.web_apps.begin_create_or_update 針對長時間執行的作業傳迴輪詢器， LROPoller[<type>]其中 <type> 是有問題的作業專屬的。

注意

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

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

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

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 自述檔。

名稱	類型	預設	描述
logging_enable	bool	False	啟用記錄。如需詳細資訊，請參閱在 Azure 連結庫中記錄。
Proxy	dict	{}	Proxy 伺服器 URL。如需詳細資訊，請參閱如何設定 Proxy。
use_env_settings	bool	True	如果為 True，則允許對 `HTTP_PROXY` Proxy 使用和 `HTTPS_PROXY` 環境變數。如果為 False，則會忽略環境變數。如需詳細資訊，請參閱如何設定 Proxy。
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	enum	指數	以線性或指數方式套用重試計時。如果為 '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 格式不正確，您通常會收到錯誤「還原串行化Error：無法還原串行化為物件：type，AttributeError： 'str' 對象沒有屬性 'get'」。此錯誤的常見原因是當連結庫預期有巢狀 JSON 物件時，您會為屬性提供單一字串。例如，'sku': 'standard'在上一個Sku範例中使用會產生此錯誤，因為 sku 參數是預期內嵌物件 JSON 的物件，在此情況下{'name': 'standard'}，它會對應至預期的SkuName類型。

下一步

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

共用方式為