適用于 Python 的 Azure 儲存體 Blob 用戶端程式庫 - 12.19.0 版

發行項
11/09/2023

Azure Blob 儲存體是 Microsoft 針對雲端推出的物件儲存體解決方案。 Blob 儲存體已針對儲存大量非結構化物件資料 (例如文字或二進位資料) 最佳化。

Blob 儲存體是適合用於：

直接提供映像或文件給瀏覽器
儲存檔案以供分散式存取。
串流視訊和音訊
儲存資料以供備份和還原、災害復原和封存。
儲存資料供內部部署或 Azure 裝載服務進行分析

開始使用

Prerequisites

需要 Python 3.7 或更新版本才能使用此套件。如需詳細資訊，請參閱 Azure SDK for Python 版本支援原則上的頁面。
您必須擁有 Azure 訂用帳戶和 Azure 儲存體帳戶，才能使用此套件。

安裝套件

使用 pip安裝適用于 Python 的 Azure 儲存體 Blob 用戶端程式庫：

pip install azure-storage-blob

建立儲存體帳戶

如果您想要建立新的儲存體帳戶，您可以使用Azure 入口網站、Azure PowerShell或Azure CLI：

# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group

建立用戶端

適用于 Python 的 Azure 儲存體 Blob 用戶端程式庫可讓您與三種類型的資源互動：儲存體帳戶本身、Blob 儲存體容器和 Blob。與這些資源的互動會從用戶端的實例開始。若要建立用戶端物件，您需要儲存體帳戶的 Blob 服務帳戶 URL 和可讓您存取儲存體帳戶的認證：

from azure.storage.blob import BlobServiceClient

service = BlobServiceClient(account_url="https://<my-storage-account-name>.blob.core.windows.net/", credential=credential)

查閱帳戶 URL

您可以使用Azure入口網站、Azure PowerShell或Azure CLI來尋找儲存體帳戶的 Blob 服務 URL：

# Get the blob service account url for the storage account
az storage account show -n my-storage-account-name -g my-resource-group --query "primaryEndpoints.blob"

認證類型

credential根據您想要使用的授權類型而定，參數可能會以多種不同形式提供：

若要使用 Azure Active Directory (AAD) 權杖認證，請提供從 azure 身分識別程式庫取得所需認證類型的實例。例如， DefaultAzureCredential 可用來驗證用戶端。

這需要一些初始設定：
- 安裝 azure-identity
- 註冊新的 AAD 應用程式，並授與存取 Azure 儲存體的許可權
- 在 Azure 入口網站中使用 RBAC 授與 Azure Blob 資料的存取權
- 將 AAD 應用程式的用戶端識別碼、租使用者識別碼和用戶端密碼的值設定為環境變數：AZURE_TENANT_ID、AZURE_CLIENT_ID、AZURE_CLIENT_SECRET
使用傳回的權杖認證來驗證用戶端：
```
    from azure.identity import DefaultAzureCredential
    from azure.storage.blob import BlobServiceClient
    token_credential = DefaultAzureCredential()

    blob_service_client = BlobServiceClient(
        account_url="https://<my_account_name>.blob.core.windows.net",
        credential=token_credential
    )
```

若要使用共用存取簽章 (SAS) 權杖，請提供權杖作為字串。如果您的帳戶 URL 包含 SAS 權杖，請省略認證參數。您可以從 Azure 入口網站在 [共用存取簽章] 底下產生 SAS 權杖，或使用其中一個 generate_sas() 函式來建立儲存體帳戶、容器或 Blob 的 SAS 權杖：

from datetime import datetime, timedelta
from azure.storage.blob import BlobServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions

sas_token = generate_account_sas(
    account_name="<storage-account-name>",
    account_key="<account-access-key>",
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

blob_service_client = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential=sas_token)

若要使用儲存體帳戶共用金鑰 (也稱為帳戶金鑰或存取金鑰) ，請提供金鑰作為字串。您可以在 Azure 入口網站的 [存取金鑰] 區段下，或執行下列 Azure CLI 命令來找到：

az storage account keys list -g MyResourceGroup -n MyStorageAccount

使用金鑰作為認證參數來驗證用戶端：
```
from azure.storage.blob import BlobServiceClient
service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential="<account_access_key>")
```
如果您使用 自訂 url (這表示 URL 不是) 格式 <my_account_name>.blob.core.windows.net ，請使用下列認證將用戶端具現化：
```
from azure.storage.blob import BlobServiceClient
service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", 
   credential={"account_name": "<your_account_name>", "account_key":"<account_access_key>"})
```
若要使用匿名公用讀取權限，只要省略認證參數即可。

從連接字串建立用戶端

根據您的使用案例和授權方法，您可能偏好使用儲存體連接字串來初始化用戶端實例，而不是個別提供帳戶 URL 和認證。若要這樣做，請將儲存體連接字串傳遞至用戶端的 from_connection_string 類別方法：

from azure.storage.blob import BlobServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = BlobServiceClient.from_connection_string(conn_str=connection_string)

您可以在 Azure 入口網站的 [存取金鑰] 區段下，或執行下列 CLI 命令，找到儲存體帳戶的連接字串：

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

重要概念

下列元件組成 Azure Blob 服務：

儲存體帳戶本身
儲存體帳戶內的容器
容器內的 Blob

適用于 Python 的 Azure 儲存體 Blob 用戶端程式庫可讓您透過使用專用用戶端物件來與這些元件互動。

用戶端

提供四個不同的用戶端來與 Blob 服務的各種元件互動：

BlobServiceClient - 此用戶端代表與 Azure 儲存體帳戶本身的互動，並可讓您取得預先設定的用戶端實例，以存取內的容器和 Blob。它提供作業來擷取和設定帳戶屬性，以及列出、建立和刪除帳戶內的容器。若要在特定容器或 Blob 上執行作業，請使用 get_container_client 或 get_blob_client 方法來擷取用戶端。
ContainerClient - 此用戶端代表與特定容器的互動 (，這些容器尚未存在) ，並可讓您取得預先設定的用戶端實例，以存取內的 Blob。它提供建立、刪除或設定容器的作業，並包含列出、上傳和刪除其中 Blob 的作業。若要對容器內的特定 Blob 執行作業，請使用 get_blob_client 方法擷取用戶端。
BlobClient - 此用戶端代表與特定 Blob 的互動， (尚未存在) 。其提供作業來上傳、下載、刪除及建立 Blob 的快照集，以及每個 Blob 類型的特定作業。
BlobLeaseClient - 此用戶端代表與 ContainerClient 或 BlobClient 的租用互動。它會提供作業，以取得、更新、發行、變更和中斷指定資源的租用。

非同步用戶端

此程式庫包含 Python 3.5+ 上支援的完整非同步 API。若要使用它，您必須先安裝非同步傳輸，例如 aioHTTP。如需詳細資訊，請參閱 azure 核心檔。

不再需要非同步用戶端和認證時，應該關閉它們。這些物件是非同步內容管理員，並定義非同步 close 方法。

Blob 類型

初始化用戶端之後，您可以從不同類型的 Blob 中選擇：

區塊 Blob 會儲存文字和二進位資料，最多 4.75 TiB。區塊 Blob 是由可個別管理的資料區塊所組成
附加 Blob 和區塊 Blob 相似，由區塊所組成，但已針對附加作業最佳化。附加 Blob 適用于從虛擬機器記錄資料等案例
分頁 Blob 可儲存隨機存取檔案 (大小上限為 8 TiB)。分頁 Blob 會將虛擬硬碟儲存 (VHD) 檔案，並作為 Azure 虛擬機器的磁片

範例

下列各節提供數個程式碼片段，涵蓋一些最常見的儲存體 Blob 工作，包括：

建立容器
上傳 Blob
下載 Blob
列舉 Blob

請注意，必須先建立容器，才能上傳或下載 Blob。

建立容器

從中建立容器，您可以在其中上傳或下載 Blob。

from azure.storage.blob import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

container_client.create_container()

使用非同步用戶端上傳 Blob

from azure.storage.blob.aio import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

await container_client.create_container()

上傳 Blob

將 Blob 上傳至您的容器

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    blob.upload_blob(data)

使用非同步用戶端上傳 Blob

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    await blob.upload_blob(data)

下載 Blob

從容器下載 Blob

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    blob_data = blob.download_blob()
    blob_data.readinto(my_blob)

以非同步方式下載 Blob

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    stream = await blob.download_blob()
    data = await stream.readall()
    my_blob.write(data)

列舉 Blob

列出容器中的 Blob

from azure.storage.blob import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = container.list_blobs()
for blob in blob_list:
    print(blob.name + '\n')

以非同步方式列出 Blob

from azure.storage.blob.aio import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = []
async for blob in container.list_blobs():
    blob_list.append(blob)
print(blob_list)

選用組態

可在用戶端和每個作業層級傳入的選擇性關鍵字引數。

重試原則設定

具現化用戶端以設定重試原則時，請使用下列關鍵字引數：

retry_total (int) ：允許的重試總數。優先于其他計數。如果您不想在要求上重試，請傳入 retry_total=0 。預設值為 10。
retry_connect (int) ：要重試的連線相關錯誤數目。預設值為 3。
retry_read (int) ：重試讀取錯誤的次數。預設值為 3。
retry_status (int) ：重試錯誤狀態碼的次數。預設值為 3。
retry_to_secondary (bool) ：如果能夠，是否應該重試要求給次要。這應該只能啟用 RA-GRS 帳戶，而且可能過時的資料可以處理。預設值為 False。

加密設定

具現化用戶端以設定加密時，請使用下列關鍵字引數：

require_encryption (bool) ：如果設定為 True，則會強制加密並解密這些物件。
encryption_version (str) ：指定要使用的加密版本。目前的選項為 '2.0' 或 '1.0' ，而預設值為 '1.0' 。 1.0 版已被取代， 強烈建議 使用 2.0 版。
key_encryption_key (物件) ：使用者提供的 key-encryption-key。實例必須實作下列方法：
- wrap_key(key)--使用使用者選擇的演算法包裝指定的索引鍵。
- get_key_wrap_algorithm()--傳回用來包裝指定對稱金鑰的演算法。
- get_kid()--傳回此 key-encryption-key 的字串金鑰識別碼。
key_resolver_function (可呼叫) ：使用者提供的金鑰解析程式。使用兒童字串傳回實作上述介面的金鑰加密金鑰。

其他用戶端/每個作業組態

可在用戶端或個別作業上指定的其他選擇性組態關鍵字引數。

用戶端關鍵字引數：

connection_timeout (int) ：用戶端將等候建立與伺服器的連線的秒數。預設值為 20 秒。
read_timeout (int) ：用戶端在連續讀取作業之間等候的秒數，以取得來自伺服器的回應。這是通訊端層級逾時，而且不會受到整體資料大小的影響。用戶端讀取逾時會自動重試。預設值是 60 秒。
傳輸 (任何) ：使用者提供的傳輸以傳送 HTTP 要求。

每個作業關鍵字引數：

raw_response_hook (可呼叫) ：指定的回呼會使用從服務傳回的回應。
raw_request_hook (可呼叫) ：指定的回呼會在傳送至服務之前使用要求。
client_request_id (str) ：選擇性使用者指定的要求識別。
user_agent (str) ：將自訂值附加至要與要求一起傳送的使用者代理程式標頭。
logging_enable (bool) ：啟用偵錯層級的記錄。預設為 False。也可以傳入用戶端層級，以針對所有要求啟用它。
logging_body (bool) ：啟用記錄要求和回應本文。預設為 False。也可以傳入用戶端層級，以針對所有要求啟用它。
標頭 (聽寫) ：傳入自訂標頭作為索引鍵、值組。例如 headers={'CustomValue': value}

疑難排解

一般

儲存體 Blob 用戶端會引發 Azure Core中定義的例外狀況。

此清單可用於參考以攔截擲回的例外狀況。若要取得例外狀況的特定錯誤碼，請使用 error_code 屬性，也就是 exception.error_code 。

記錄

此程式庫會使用標準記錄程式庫進行記錄。 HTTP 會話的基本資訊 (URL、標頭等 ) 會記錄在 INFO 層級。

您可以在具有引數的用戶端 logging_enable 上啟用詳細的 DEBUG 層級記錄，包括要求/回應主體和未處理的標頭：

import sys
import logging
from azure.storage.blob import BlobServiceClient

# Create a logger for the 'azure.storage.blob' SDK
logger = logging.getLogger('azure.storage.blob')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = BlobServiceClient.from_connection_string("your_connection_string", logging_enable=True)

同樣地，logging_enable 可對單一作業啟用詳細記錄，即使未對用戶端啟用也可行：

service_client.get_service_stats(logging_enable=True)

下一步

其他文件

如需有關 Azure Blob 儲存體的詳細資訊檔，請參閱 azure Blob 儲存體檔 docs.microsoft.com。

參與

此專案歡迎參與和提供建議。大部分的參與都要求您同意「參與者授權合約 (CLA)」，宣告您有權且確實授與我們使用投稿的權利。如需詳細資料，請前往 https://cla.microsoft.com 。

當您提交提取要求時，CLA Bot 會自動判斷您是否需要提供 CLA，並適當地裝飾 PR (例如標籤、註解)。請遵循 bot 提供的指示。您只需要使用我們的 CLA 在所有存放庫上執行此動作一次。

此專案採用 Microsoft Open Source Code of Conduct (Microsoft 開放原始碼管理辦法)。如需詳細資訊，請參閱管理辦法常見問題集，如有任何其他問題或意見請連絡 opencode@microsoft.com。