使用 Python 建立和管理容器租用

• .NET
• Java
• JavaScript
• Python

本文說明如何使用適用於 Python 的 Azure 儲存體用戶端程式庫建立和管理容器租用。 您可以使用用戶端程式庫來取得、更新、釋放和中斷容器租用。

若要了解如何使用非同步 API 租用 Blob 容器，請參閱以非同步方式租用容器。

必要條件

• Azure 訂用帳戶 - 建立免費帳戶
• Azure 儲存體帳戶 - 建立儲存體帳戶
• Python 3.8+

設定您的環境

如果沒有現有的專案，本章節會說明如何設定專案以使用適用於 Python 的 Azure Blob 儲存體用戶端程式庫。 如需詳細資訊，請參閱開始使用 Azure Blob 儲存體和 Python。

若要使用本文中的程式碼範例，請遵循下列步驟來設定您的專案。

安裝套件

使用 pip install 安裝下列套件：

pip install azure-storage-blob azure-identity

新增 import 陳述式

加入下列 import 陳述式：

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, BlobLeaseClient

授權

授權機制必須具有使用容器租用所需的權限。 如需使用 Microsoft Entra ID 授權 (建議使用)，您需要 Azure RBAC 內建角色儲存體 Blob 資料參與者或更高權限。 若要深入了解，請參閱租用容器 (REST API) (部分機器翻譯) 的授權指導。

建立用戶端物件

若要將應用程式連線至 Blob 儲存體，請建立 BlobServiceClient類別的執行個體。 下列範例示範如何使用 DefaultAzureCredential 來建立用戶端物件以進行授權：

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"
credential = DefaultAzureCredential()

# Create the BlobServiceClient object
blob_service_client = BlobServiceClient(account_url, credential=credential)

您也可以直接或從 BlobServiceClient 物件建立特定容器或 Blob 的用戶端物件。 若要深入了解如何建立及管理用戶端物件，請參閱建立和管理與資料資源互動的用戶端端物件 (部分機器翻譯)。

關於容器租用

租用會在容器上建立及管理刪除作業的鎖定。 鎖定持續時間的範圍是 15 到 60 秒，也可以設為無限。 容器上的租用會提供刪除容器的專有存取權。 容器租用只會控制使用刪除容器 REST API 作業來刪除容器的功能。 若要刪除具有作用中租用的容器，用戶端必須使用刪除要求納入作用中的租用識別碼。 在未包含租用識別碼的情況下，所有其他容器作業都可以在租用的容器上成功執行。 如果您已啟用容器虛刪除，則可以還原已刪除的容器。

若要深入了解租用狀態，以及何時可以在租用上執行指定動作，請參閱租用狀態和動作。

租用作業由 BlobLeaseClient 類別所處理，提供一個包含 Blob 和容器的所有租用作業的用戶端。 若要深入了解使用用戶端程式庫的 Blob 租用，請參閱使用 Python 建立和管理 Blob 租用。

取得租用

取得容器租用時，會取得一個租用識別碼，讓您的程式碼可用來在容器上運作。 如果容器已經有作用中的租用，您只能使用作用中的租用識別碼來要求新的租用。 不過，您可以指定新的租用期間。

若要取得租用，請建立 BlobLeaseClient 類別的執行個體，然後使用下列方法：

• BlobLeaseClient.acquire

您也可以使用 ContainerClient 類別的下列方法取得租用：

• ContainerClient.acquire_lease

下列範例會取得容器的 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

更新租用

如果在要求上指定的租用識別碼符合該容器相關聯的租用識別碼，則可以更新容器租用。 租用到期之後，只要容器未曾再度租用，即使租用已到期，還是可以更新。 當您更新租用時，租用持續時間會重設。

若要更新租用，請使用下列方法：

• BlobLeaseClient.renew

下列範例會更新容器的租用：

def renew_container_lease(self, lease_client: BlobLeaseClient):
    # Renew a lease on the container
    lease_client.renew()

釋放租用

如果在要求上指定的租用識別碼符合該容器相關聯的租用識別碼，則可以發行容器租用。 釋放租用，可讓其他用戶端在釋放完成後立即取得容器的租用。

您可以使用下列方法來釋放租用：

• BlobLeaseClient.release

下列範例會釋放容器的租用：

def release_container_lease(self, lease_client: BlobLeaseClient):
    # Release a lease on the container
    lease_client.release()

中斷租用

如果容器具有作用中的租用，您可以中斷容器租用。 任何已授權的要求都可以中斷租用；此要求不需要指定相符的租用識別碼。 租用在中斷之後會無法更新，而且中斷租用之後的一段期間内將無法取得新租用，直到原始租用到期或釋放爲止。

您可以使用下列方法來中斷租用：

• BlobLeaseClient.break_lease

下列範例會中斷容器的租用：

def break_container_lease(self, lease_client: BlobLeaseClient):
    # Break a lease on the container
    lease_client.break_lease()

以非同步方式租用容器

適用於 Python 的 Azure Blob 儲存體用戶端程式庫支援以非同步方式租用容器。 若要深入了解專案設定需求，請參閱非同步程式設計。

依照下列步驟，使用非同步 API 租用容器：

1. 新增下列匯入陳述式：

   import asyncio
   
   from azure.identity.aio import DefaultAzureCredential
   from azure.storage.blob.aio import BlobServiceClient, BlobLeaseClient
   

2. 新增程式碼以使用 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())
   

3. 新增程式碼以取得容器租用。 該程式碼與同步範例相同，不同之處在於該方法是以 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 儲存體用戶端程式庫租用容器，請參閱下列資源。

程式碼範例

• 檢視本文中的同步或非同步程式碼範例 (GitHub)

REST API 操作

Azure SDK for Python 包含建置在 Azure REST API 之上的程式庫，可讓您透過熟悉的 Python 範例與 REST API 作業進行互動。 用來租用容器的用戶端程式庫方法會使用下列 REST API 作業：

• 租用容器 (REST API)

用戶端程式庫資源

• 用戶端程式庫參考文件
• 用戶端程式庫原始程式碼
• 套件 (Pypi) (英文)

另請參閱

• 管理 Blob 儲存體中的並行

相關內容

• 本文是適用於 Python 的 Blob 儲存體開發人員指南的一部分。 若要深入了解，請參閱 建置 Python 應用程式 中的開發人員指南文章完整清單。