共用方式為


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

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

Blob 儲存體是適合用於:

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

| 原始程式碼套件 (PyPI) | 套件 (Conda) | API 參考檔 | 產品檔 | 樣品

開始使用

Prerequisites

安裝套件

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

pip install azure-storage-blob

建立儲存體帳戶

如果您想要建立新的儲存體帳戶,您可以使用Azure 入口網站Azure PowerShellAzure 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 PowerShellAzure 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根據您想要使用的授權類型而定,參數可能會以多種不同形式提供:

  1. 若要使用 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
        )
    
  2. 若要使用 共用存取簽章 (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)
    
  3. 若要使用儲存體帳戶 共用金鑰 (也稱為帳戶金鑰或存取金鑰) ,請提供金鑰作為字串。 您可以在 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>"})
    
  4. 若要使用 匿名公用讀取權限,只要省略認證參數即可。

從連接字串建立用戶端

根據您的使用案例和授權方法,您可能偏好使用儲存體連接字串來初始化用戶端實例,而不是個別提供帳戶 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 服務的各種元件互動:

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

非同步用戶端

此程式庫包含 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。

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)

下一步

更多的程式碼範例

開始使用我們的 Blob 範例

您可以在 SDK 的 GitHub 存放庫中取得數個儲存體 Blob Python SDK 範例。 這些範例提供使用儲存體 Blob 時常遇到的其他案例範例程式碼:

其他文件

如需有關 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