使用 Python 建立和管理容器租用
本文說明如何使用適用於 Python 的 Azure 儲存體用戶端程式庫建立和管理容器租用。 您可以使用用戶端程式庫來取得、更新、釋放和中斷容器租用。
若要了解如何使用非同步 API 租用 Blob 容器,請參閱以非同步方式租用容器。
必要條件
- 本文假設您已有專案設定好要使用適用於 Python 的 Azure Blob 儲存體用戶端程式庫。 若要了解如何設定您的專案,包括安裝套件、新增
import
陳述式,以及建立授權的用戶端物件,請參閱開始使用 Azure Blob 儲存體和 Python。 - 授權機制必須具有使用容器租用的權限。 若要深入了解,請參閱下列 REST API 作業的授權指引:
關於容器租用
租用會對容器建立及管理用於刪除作業的鎖定。 鎖定持續時間的範圍是 15 到 60 秒,也可以設為無限。 容器的租用會提供對容器的獨佔刪除存取權。 容器租用只會控制使用刪除容器 REST API 作業來刪除容器的能力。 若要刪除具有作用中租用的容器,用戶端必須使用刪除要求納入作用中的租用識別碼。 在未包含租用識別碼的情況下,所有其他容器作業都可以在租用的容器上成功執行。 如果您已啟用容器虛刪除,則可以還原已刪除的容器。
若要深入了解租用狀態,以及何時可以對租用執行指定動作,請參閱租用狀態和動作。
租用作業由 BlobLeaseClient 類別所處理,提供一個包含 Blob 和容器的所有租用作業的用戶端。 若要深入了解使用用戶端程式庫的 Blob 租用,請參閱使用 Python 建立和管理 Blob 租用。
取得租用
取得容器租用時,您會取得一個租用識別碼,讓您的程式碼可用來在容器上運作。 如果容器已有作用中的租用,您只能使用作用中的租用識別碼來要求新的租用。 不過,您可以指定新的租用期間。
若要取得租用,請建立 BlobLeaseClient 類別的執行個體,然後使用下列方法:
您也可以使用 ContainerClient 類別的下列方法取得租用:
下列範例會取得容器的 30 秒租用:
def acquire_container_lease(self, blob_service_client: BlobServiceClient, container_name):
# Instantiate a ContainerClient
container_client = blob_service_client.get_container_client(container=container_name)
# Acquire a 30-second lease on the container
lease_client = container_client.acquire_lease(30)
return lease_client
更新租用
如果在要求上指定的租用識別碼符合與容器相關聯的租用識別碼,則可以更新容器租用。 租用即使已到期仍可更新,只要容器在租用到期後未再次租用即可。 當您更新租用時,租用持續時間會重設。
若要更新租用,請使用下列方法:
下列範例會更新容器的租用:
def renew_container_lease(self, lease_client: BlobLeaseClient):
# Renew a lease on the container
lease_client.renew()
釋放租用
如果在要求上指定的租用識別碼符合與容器相關聯的租用識別碼,則可以釋放容器租用。 釋放租用,可讓其他用戶端在釋放完成後立即取得容器的租用。
您可以使用下列方法來釋放租用:
下列範例會釋放容器的租用:
def release_container_lease(self, lease_client: BlobLeaseClient):
# Release a lease on the container
lease_client.release()
中斷租用
如果容器有作用中的租用,您可以中斷容器租用。 任何已授權的要求都可以中斷租用;此要求不需要指定相符的租用識別碼。 租用在中斷之後會無法更新,而且中斷租用之後的一段期間内將無法取得新租用,直到原始租用到期或釋放爲止。
您可以使用下列方法來中斷租用:
下列範例會中斷容器的租用:
def break_container_lease(self, lease_client: BlobLeaseClient):
# Break a lease on the container
lease_client.break_lease()
以非同步方式租用容器
適用於 Python 的 Azure Blob 儲存體用戶端程式庫支援以非同步方式租用容器。 若要深入了解專案設定需求,請參閱非同步程式設計。
依照下列步驟,使用非同步 API 租用容器:
新增下列匯入陳述式:
import asyncio from azure.identity.aio import DefaultAzureCredential from azure.storage.blob.aio import BlobServiceClient, BlobLeaseClient
新增程式碼以使用
asyncio.run
執行程式。 此函式會執行傳遞的協同程式 (在我們的範例中為main()
),並管理asyncio
事件重複。 協同程式會以 async/await 語法宣告。 在此範例中,main()
協同程式會先使用async with
建立最上層BlobServiceClient
,然後呼叫取得容器租用的方法。 請注意,只有最上層用戶端需要使用async with
,因為從中建立的其他用戶端會共用相同的連線集區。async def main(): sample = ContainerSamples() # 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: lease_client = await sample.acquire_container_lease(blob_service_client, "sample-container") if __name__ == '__main__': asyncio.run(main())
新增程式碼以取得容器租用。 該程式碼與同步範例相同,不同之處在於該方法是以
async
關鍵字宣告的,而await
關鍵字是在呼叫acquire
方法時使用的。async def acquire_container_lease(self, blob_service_client: BlobServiceClient, container_name): # Instantiate a ContainerClient container_client = blob_service_client.get_container_client(container=container_name) # Acquire a 30-second lease on the container lease_client = BlobLeaseClient(container_client) await lease_client.acquire(lease_duration=30) return lease_client
完成這個基本設定後,您可以使用 async/await 語法將本文中的其他範例實作為協同程式。
租用狀態和動作
下圖顯示租用的五個狀態,以及會導致租用狀態變更的命令或事件。
下表列出五個租用狀態、提供每個租用狀態的簡短描述,並列出指定狀態中允許的租用動作。 這些租用動作會導致狀態轉換,如下圖所示。
租用狀態 | 描述 | 允許的租用動作 |
---|---|---|
可用的 | 租用已解除鎖定,可以取得。 | acquire |
已租用 | 租用已鎖定。 | acquire (僅限相同的租用識別碼)、renew 、change 、release 和 break |
已到期 | 租用持續時間到期。 | acquire 、renew 、release 和 break |
中斷 | 租用已中斷,但是租用將繼續鎖定,直到中斷期到期為止。 | release 和 break |
中斷 | 租用已中斷,且中斷期已到期。 | acquire 、release 和 break |
租用到期後,租用識別碼會由 Blob 服務維護,直到容器修改或再次租用。 用戶端可能會嘗試使用過期的租用識別碼來更新或釋放租用。 如果要求失敗,用戶端會得知容器已再次租用,或容器自上次有效租用後已遭刪除。
如果租用到期,而不是明確地釋放,用戶端可能需要等候一分鐘,才能取得容器的新租用。 不過,用戶端可立即以到期的租用識別碼更新租用。
資源
若要深入了解如何使用適用於 Python 的 Azure Blob 儲存體用戶端程式庫租用容器,請參閱下列資源。
REST API 操作
Azure SDK for Python 包含建置在 Azure REST API 之上的程式庫,可讓您透過熟悉的 Python 範例與 REST API 作業進行互動。 用來租用容器的用戶端程式庫方法會使用下列 REST API 作業:
- 租用容器 (REST API)
程式碼範例
用戶端程式庫資源
另請參閱
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應