開始使用 Azure Blob 儲存體和 Python

發行項
10/03/2024

本文會說明如何使用適用於 Python 的 Azure Blob 儲存體用戶端程式庫來連線至 Azure Blob 儲存體。線上之後，請使用開發人員指南來瞭解如何在 Blob 記憶體服務的容器、Blob 和功能上運作程式碼。

如果您想要從完整的範例開始，請參閱快速入門：Azure Blob 儲存體 Python 用戶端連結庫。

API 參考 | 套件 (PyPi) | 程式庫原始程式碼 | 範例 | 提供意見反應

必要條件

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

設定您的專案

本節會引導您準備專案以搭配適用於 Python 的 Azure Blob 儲存體用戶端程式庫使用。

從您的專案目錄中，使用 pip install 命令安裝 Azure Blob 儲存體和 Azure 身分識別客戶端程式庫的套件。需要 azure 身分識別 套件才能對 Azure 服務進行無密碼連線。

pip install azure-storage-blob azure-identity

然後開啟程式碼檔案，並新增必要的匯入陳述式。在此範例中，我們會將下列內容新增至 .py 檔案:

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, BlobClient, ContainerClient

Blob 用戶端程式庫資訊:

azure.storage.blob: 包含可用來操作服務、容器和 Blob 的主要類別 (「用戶端物件」)。

非同步程式設計

適用於 Python 的 Azure Blob 儲存體用戶端程式庫支援同步及非同步 API。非同步 API 是以 Python 的 asyncio 程式庫為基礎。

請遵循下列步驟，在您的專案中使用非同步 API:

安裝非同步傳輸，例如 aiohttp。您可以使用選擇性的相依性安裝命令來安裝 aiohttp 以及 azure-storage-blob。在此範例中，我們會使用下列 pip install 命令:
```
pip install azure-storage-blob[aio]
```
開啟您的程式碼檔案，並新增必要的匯入陳述式。在此範例中，我們會將下列內容新增至 .py 檔案:
```
import asyncio

from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient, BlobClient, ContainerClient
```
只有在程式碼中使用程式庫時，才需要 import asyncio 陳述式。由於開發人員指南文章中的範例會使用 asyncio 程式庫，為了清楚起見會將其新增至這裡。
使用 async with 建立客戶端物件，以開始使用資料資源。只有最上層用戶端需要使用 async with，因為從中建立的其他用戶端會共用相同的連線集區。在此範例中，我們會使用 async with 建立 BlobServiceClient 對象，然後建立 ContainerClient 物件:
```
async with BlobServiceClient(account_url, credential=credential) as blob_service_client:
    container_client = blob_service_client.get_container_client(container="sample-container")
```
若要深入了解，請參閱授權存取權並連線到 Blob 儲存體中的非同步範例。

Blob 非同步用戶端程式庫資訊:

azure.storage.blob.aio: 包含可用來非同步操作服務、容器和 Blob 的主要類別。

授權存取權並連線到 Blob 儲存體

若要將應用程式連線至 Blob 儲存體，請建立 BlobServiceClient 類別的執行個體。此物件是您與儲存體帳戶層級的資料資源互動的起點。您可以使用它來操作儲存體帳戶及其容器。您也可以使用服務用戶端來建立容器用戶端或 Blob 用戶端，視您需要使用的資源而定。

若要深入了解如何建立和管理客戶端物件，包括最佳做法，請參閱建立和管理與資料資源互動的客戶端物件。

您可以使用 Microsoft Entra 授權權杖、帳戶存取密鑰或共用存取簽章 (SAS) 來授權 BlobServiceClient 物件。為了實現最佳安全性，Microsoft 建議使用具有受控識別的 Microsoft Entra ID 來授權針對 Blob 資料的要求。如需更多資訊，請參閱使用 Microsoft Entra ID 授與 Blob 的存取權。

若要使用 Microsoft Entra ID 進行授權，您必須使用安全性主體。需要何種安全性主體取決於應用程式的執行位置。參考下表：

應用程式的執行位置	安全性主體	指引
本機電腦 (開發和測試)	服務主體	若要了解如何註冊應用程式、設定 Microsoft Entra 群組、指派角色及設定環境變數，請參閱使用開發人員服務主體授權存取
本機電腦 (開發和測試)	使用者身分識別	若要了解如何設定 Microsoft Entra 群組、指派角色並登入 Azure，請參閱使用開發人員認證授權存取
裝載於 Azure 中	受控識別	若要了解如何啟用受控識別並指派角色，請參閱使用受控識別從 Azure 裝載的應用程式授權存取
裝載在 Azure 外部 (例如內部部署應用程式)	服務主體	若要了解如何註冊應用程式、指派角色及設定環境變數，請參閱使用應用程式服務主體從内部部署應用程式授權存取

使用 DefaultAzureCredential 授權存取

授權存取權並連線到 Blob 儲存體簡單又安全的方式，是藉由建立 DefaultAzureCredential 執行個體來取得 OAuth 權杖。然後，您可以使用該認證來建立 BlobServiceClient 物件。

下列範例會使用 DefaultAzureCredential 來建立 BlobServiceClient 物件:

def get_blob_service_client_token_credential(self):
    # 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)

    return blob_service_client

如果您的專案使用非同步 API，請使用 async with 具現化 BlobServiceClient:

# 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:
    # Work with data resources in the storage account

若要使用共用存取簽章 (SAS) 權杖，請提供權杖作為字串，並初始化 BlobServiceClient 物件。如果您的帳戶 URL 包含 SAS 權杖，請省略認證參數。

def get_blob_service_client_sas(self, sas_token: str):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    # The SAS token string can be assigned to credential here or appended to the account URL
    credential = sas_token

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

    return blob_service_client

如果您的專案使用非同步 API，請使用 async with 具現化 BlobServiceClient:

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

# Replace <sas_token_str> with your actual SAS token
sas_token: str = "<sas_token_str>"

async with BlobServiceClient(account_url, credential=sas_token) as blob_service_client:
    # Work with data resources in the storage account

若要深入了解如何產生和管理 SAS 權杖，請參閱下列文章:

注意

針對使用共用存取簽章 (SAS) 的案例，Microsoft 建議使用使用者委派 SAS。使用者委派 SAS 會使用 Microsoft Entra 認證來保護，而不是使用帳戶金鑰。

若要使用儲存體帳戶共用密鑰，請提供金鑰做為字串，並初始化 BlobServiceClient 物件。

def get_blob_service_client_account_key(self):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    shared_access_key = os.getenv("AZURE_STORAGE_ACCESS_KEY")
    credential = shared_access_key

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

    return blob_service_client

您也可以使用連接字串來建立 BlobServiceClient 物件。

def get_blob_service_client_connection_string(self):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    connection_string = os.getenv("AZURE_STORAGE_CONNECTION_STRING")

    # Create the BlobServiceClient object
    blob_service_client = BlobServiceClient.from_connection_string(connection_string)

    return blob_service_client

如果您的專案使用非同步 API，請使用 async with 具現化 BlobServiceClient:

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

shared_access_key = os.getenv("AZURE_STORAGE_ACCESS_KEY")

async with BlobServiceClient(account_url, credential=shared_access_key) as blob_service_client:
    # Work with data resources in the storage account

關於如何取得帳戶金鑰及正確管理和保護金鑰的最佳做法指導方針，如需相關資訊，請參閱管理儲存體帳戶存取金鑰。

重要

應該謹慎使用帳戶存取金鑰。如果帳戶存取金鑰遺失或意外放在不安全的地方，您的服務可能變得易受攻擊。任何擁有存取金鑰的人都可以授權執行目標為儲存體帳戶的要求，而且可實質存取所有資料。 DefaultAzureCredential 會提供增強的安全性功能和權益，建議用來管理對 Azure 服務的授權。

建置應用程式

當您建置應用程式以在 Azure Blob 儲存體中使用資料資源時，您的程式碼主要會與三種資源類型互動：儲存體帳戶、容器和 Blob。若要深入了解這些資源類型、彼此的關係，以及應用程式如何與資源互動，請參閱了解應用程式如何與 Blob 儲存體資料資源互動。

下列指南示範如何使用適用於 Python 的 Azure 儲存體客戶端連結庫來存取數據並執行特定動作：

指南	描述
設定重試原則 (部分機器翻譯)	實作用戶端作業的重試原則。
複製 Blob	將 Blob 從一個位置複製到另一個位置。
建立容器	建立 Blob 容器
建立使用者委派 SAS	建立容器或 Blob 的使用者委派 SAS。
建立和管理 blob 租用	建立和管理 Blob 上的鎖定。
建立和管理容器租用	在容器上建立和管理鎖定。
刪除和還原 Blob	刪除 Blob 並還原虛刪除的 Blob。
刪除和還原容器	刪除容器並還原虛刪除的容器。
下載 Blob	使用字串、串流和檔案路徑來下載 Blob。
使用標籤來尋找 Blob	設定和擷取標籤，以及使用標籤來尋找 Blob。
列出 Blob	以各種方式列出 Blob。
列出容器	列出帳戶中的容器，以及可用來自訂清單的各種選項。
管理屬性和中繼資料 (Blob)	取得和設定 Blob 的屬性和中繼資料。
管理屬性和中繼資料 (容器)	取得和設定容器的屬性和中繼資料。
資料傳輸的效能微調	最佳化資料傳輸作業的效能。
設定或變更 Blob 的存取層	設定及變更區塊 Blob 的存取層。
上傳 Blob	了解如何使用字串、串流、檔案路徑和其他方法來上傳 Blob。

共用方式為

開始使用 Azure Blob 儲存體和 Python

必要條件

設定您的專案

非同步程式設計

授權存取權並連線到 Blob 儲存體

使用 DefaultAzureCredential 授權存取

建置應用程式

意見反應

其他資源