範例：使用適用於 Python 的 Azure 鏈接庫存取 Azure 儲存體

發行項
10/03/2024

在本文中，您將瞭解如何使用 Python 應用程式程式代碼中的 Azure 用戶端連結庫，將檔案上傳至 Azure Blob 記憶體容器。本文假設您已建立範例：建立 Azure 儲存體中顯示的資源。

本文中的所有命令在Linux/macOS bash和 Windows 命令殼層中都相同，除非另有說明。

1.設定本機開發環境

如果您尚未設定環境，您可以在其中執行此程序代碼。以下列出一些選項：

使用 venv 或您選擇的工具設定 Python 虛擬環境。您可以在本機或 Azure Cloud Shell 中建立虛擬環境，並在該處執行程序代碼。請務必啟動虛擬環境以開始使用它。
使用 conda 環境。
在 Visual Studio Code 或 GitHub Codespaces 中使用開發容器。

2.安裝連結庫套件

在您的 requirements.txt 檔案中，新增您需要的用戶端連結庫套件行並儲存盤案。

azure-storage-blob
azure-identity

然後，在您的終端機或命令提示字元中，安裝需求。

pip install -r requirements.txt

3.建立要上傳的檔案

建立名為 sample-source.txt 的來源檔案。此檔名是程式代碼預期的內容。

Hello there, Azure Storage. I'm a friendly file ready to be stored in a blob.

4.從應用程式程式代碼使用 Blob 記憶體

本節示範兩種方式，以存取您在範例：建立 Azure 儲存體中建立的 Blob 容器中的數據。若要存取 Blob 容器中的數據，您的應用程式必須能夠向 Azure 進行驗證，並獲授權存取容器中的數據。本節提供兩種執行此作業的方式：

無密碼（建議） 方法會使用 DefaultAzureCredential來驗證應用程式。 DefaultAzureCredential 是鏈結認證，可使用不同的認證序列來驗證應用程式（或使用者），包括開發人員工具認證、應用程式服務主體和受控識別。
連接字串方法會使用連接字串直接存取記憶體帳戶。

基於下列原因和更多原因，我們建議盡可能使用無密碼方法：

連接字串會使用記憶體帳戶來驗證連線代理程式，而不是使用該帳戶內的個別資源。因此，連接字串授與比可能需要更廣泛的授權。您可以使用 DefaultAzureCredential ，將記憶體資源的許可權授與更細微、最低許可權的許可權給使用 Azure RBAC 執行的應用程式身分識別。
連接字串包含純文本的存取資訊，因此，如果未正確建構或受到保護，就會造成潛在的弱點。如果公開這類連接字串，它可以用來存取記憶體帳戶內的各種資源。
連接字串通常會儲存在環境變數中，當攻擊者取得您環境的存取權時，它很容易遭到入侵。支援 DefaultAzureCredential 的許多認證類型不需要將秘密儲存在您的環境中。

無密碼 (建議)
連接字串

DefaultAzureCredential 是預先設定的認證鏈結。其設計目的是支援多種環境，以及最常見的驗證流程和開發人員工具。的 DefaultAzureCredential 實例會根據運行時間環境、特定已知環境變數的值，以及選擇性地傳遞至其建構函式的參數，決定要嘗試取得令牌的認證類型。

在下列步驟中，您會將應用程式服務主體設定為應用程式身分識別。應用程式服務主體適用於本機開發期間和裝載於內部部署的應用程式。若要設定 DefaultAzureCredential 為使用應用程式服務主體，您可以設定下列環境變數： AZURE_CLIENT_ID、 AZURE_TENANT_ID和 AZURE_CLIENT_SECRET。

請注意，已設定客戶端密碼。這是應用程式服務主體的必要專案，但視您的案例而定，您也可以 DefaultAzureCredential 設定為使用不需要在環境變數中設定秘密或密碼的認證。

例如，在本機開發中，如果 DefaultAzureCredential 無法使用已設定的環境變數取得令牌，它會嘗試使用已登入 Azure CLI 等開發工具的使用者取得令牌;針對裝載在 Azure 中的應用程式， DefaultAzureCredential 可以設定為使用受控識別。在所有情況下，您應用程式中的程式代碼會維持不變，只有組態和/或運行時間環境會變更。

使用下列程式代碼建立名為 use_blob_auth.py 的檔案。批註會說明步驟。

import os
import uuid

from azure.identity import DefaultAzureCredential

# Import the client object from the SDK library
from azure.storage.blob import BlobClient

credential = DefaultAzureCredential()

# Retrieve the storage blob service URL, which is of the form
# https://<your-storage-account-name>.blob.core.windows.net/
storage_url = os.environ["AZURE_STORAGE_BLOB_URL"]

# Create the client object using the storage URL and the credential
blob_client = BlobClient(
    storage_url,
    container_name="blob-container-01",
    blob_name=f"sample-blob-{str(uuid.uuid4())[0:5]}.txt",
    credential=credential,
)

# Open a local file and upload its contents to Blob Storage
with open("./sample-source.txt", "rb") as data:
    blob_client.upload_blob(data)
    print(f"Uploaded sample-source.txt to {blob_client.url}")

參考連結：

建立名為的 AZURE_STORAGE_BLOB_URL環境變數：
- cmd
- bash
```
set AZURE_STORAGE_BLOB_URL=https://pythonazurestorage12345.blob.core.windows.net
```
```
AZURE_STORAGE_BLOB_URL=https://pythonazurestorage12345.blob.core.windows.net
```
以記憶體帳戶的名稱取代「pythonazurestorage12345」。。

此 AZURE_STORAGE_BLOB_URL 範例只會使用環境變數。 Azure 連結庫不會使用它。
使用 az ad sp create-for-rbac 命令為應用程式建立新的服務主體。命令會同時為應用程式建立應用程式註冊。為服務主體指定您選擇的名稱。
```
az ad sp create-for-rbac --name <service-principal-name>
```
此命令的輸出會如下所示。請記下這些值，或讓此視窗保持開啟，因為您在下一個步驟中需要這些值，且無法再次檢視密碼（客戶端密碼）值。不過，您可以稍後新增密碼，而不需視需要使服務主體或現有密碼失效。
```
{
  "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "displayName": "<service-principal-name>",
  "password": "Aa1Bb~2Cc3.-Dd4Ee5Ff6Gg7Hh8Ii9_Jj0Kk1Ll2",
  "tenant": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
}
```
Azure CLI 命令可以在 Azure Cloud Shell 或已安裝 Azure CLI 的工作站上執行。
建立應用程式服務主體的環境變數：

使用上一個命令輸出中的值，建立下列環境變數。這些變數會告知 DefaultAzureCredential 使用應用程式服務主體。
- AZURE_CLIENT_ID → 應用程式識別碼的值。
- AZURE_TENANT_ID → 租用戶識別碼的值。
- AZURE_CLIENT_SECRET → 為應用程式產生的密碼/認證。
- cmd
- bash
```
set AZURE_CLIENT_ID=00001111-aaaa-2222-bbbb-3333cccc4444
set AZURE_TENANT_ID=aaaabbbb-0000-cccc-1111-dddd2222eeee
set AZURE_CLIENT_SECRET=Aa1Bb~2Cc3.-Dd4Ee5Ff6Gg7Hh8Ii9_Jj0Kk1Ll2
```
```
AZURE_CLIENT_ID=00001111-aaaa-2222-bbbb-3333cccc4444
AZURE_TENANT_ID=aaaabbbb-0000-cccc-1111-dddd2222eeee
AZURE_CLIENT_SECRET=Aa1Bb~2Cc3.-Dd4Ee5Ff6Gg7Hh8Ii9_Jj0Kk1Ll2
```
試著執行程式碼（故意失敗）：
```
python use_blob_auth.py
```
請注意「此要求未獲授權使用此許可權執行這項作業」錯誤。因為您所使用的本機服務主體尚未具有存取 Blob 容器的許可權，因此預期會發生此錯誤。
使用 az role assignment create Azure CLI 命令，將 Blob 容器上的記憶體 Blob 數據參與者許可權授與服務主體：
```
az role assignment create --assignee <AZURE_CLIENT_ID> \
    --role "Storage Blob Data Contributor" \
    --scope "/subscriptions/<AZURE_SUBSCRIPTION_ID>/resourceGroups/PythonAzureExample-Storage-rg/providers/Microsoft.Storage/storageAccounts/pythonazurestorage12345/blobServices/default/containers/blob-container-01"
```
自 --assignee 變數會識別服務主體。以服務主體的應用程式識別碼取代 <AZURE_CLIENT_ID> 佔位元元。

自 --scope 變數會識別套用此角色指派的位置。在此範例中，您會將「記憶體 Blob 數據參與者」角色授與名為「blob-container-01」之容器的服務主體。
- 將和 pythonazurestorage12345 取代PythonAzureExample-Storage-rg為包含記憶體帳戶的資源群組，以及記憶體帳戶的確切名稱。此外，如有必要，請調整 Blob 容器的名稱。如果您使用錯誤的名稱，您會看到錯誤：「無法在巢狀資源上執行要求的作業。找不到父資源 'pythonazurestorage12345'。」
- 以 <您的 Azure 訂用帳戶標識碼取代AZURE_SUBSCRIPTION_ID> 位持有者。（您可以執行 az account show 命令，並從輸出中的屬性取得訂用帳戶標識碼id。
提示

如果角色指派命令在使用bash殼層時傳回「找不到連線配接器」錯誤，請嘗試設定 export MSYS_NO_PATHCONV=1 以避免路徑轉譯。如需詳細資訊，請參閱此問題。
等候一兩分鐘，讓許可權傳播，然後再次執行程式代碼，確認它現在是否正常運作。如果您再次看到許可權錯誤，請稍候一點，然後再試一次程序代碼。

如需角色指派的詳細資訊，請參閱如何使用 Azure CLI 指派角色許可權。

重要

在上述步驟中，您的應用程式是在應用程式服務主體下執行。應用程式服務主體在其組態中需要客戶端密碼。不過，您可以使用相同的程式代碼，在不需要您在環境中明確設定密碼或密碼的不同認證類型下執行應用程式。例如，在開發期間，可以使用開發人員工具認證， DefaultAzureCredential 例如您用來透過 Azure CLI 登入的認證;或者，對於裝載在 Azure 中的應用程式，可以使用受控識別。若要深入瞭解，請參閱使用適用於 Python 的 Azure SDK 向 Azure 服務驗證 Python 應用程式。

連接字串包含儲存體帳戶存取金鑰，可用來授權要求。請務必小心，絕不要在不安全的地方公開金鑰。

使用下列程式代碼建立名為 use_blob_conn_string.py 的 Python 檔案。批註會說明步驟。

import os
import uuid

# Import the client object from the SDK library
from azure.storage.blob import BlobClient

# Retrieve the connection string from an environment variable. Note that a
# connection string grants all permissions to the caller, making it less
# secure than obtaining a BlobClient object using credentials.
conn_string = os.environ["AZURE_STORAGE_CONNECTION_STRING"]

# Create the client object for the resource identified by the connection
# string, indicating also the blob container and the name of the specific
# blob we want.
blob_client = BlobClient.from_connection_string(
    conn_string,
    container_name="blob-container-01",
    blob_name=f"sample-blob-{str(uuid.uuid4())[0:5]}.txt",
)

# Open a local file and upload its contents to Blob Storage
with open("./sample-source.txt", "rb") as data:
    blob_client.upload_blob(data)
    print(f"Uploaded sample-source.txt to {blob_client.url}")

建立名為AZURE_STORAGE_CONNECTION_STRING的環境變數，其值為記憶體帳戶的完整連接字串。（各種 Azure CLI 批注也會使用此環境變數。您可以執行 az storage account show-connection-string 命令，以取得記憶體帳戶的連接字串。
```
az storage account show-connection-string --resource-group PythonAzureExample-Storage-rg --name pythonazurestorage12345
```
將和 pythonazurestorage12345 取代PythonAzureExample-Storage-rg為包含記憶體帳戶的資源群組，以及記憶體帳戶的確切名稱。

當您設定環境變數時，請在輸出中使用屬性的 connectionString 整個值，包括引號。
執行程式代碼：
```
python use_blob_conn_string.py
```

同樣地，雖然這個方法很簡單，但連接字串會授權記憶體帳戶中的所有作業。使用生產程序代碼時，最好使用上一節中所述的特定許可權。

重要

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

5.確認 Blob 建立

執行任一方法的程式代碼之後，請移至 Azure 入口網站，流覽至 Blob 容器，確認名為 sample-blob-{random}的新 Blob 存在，.txt與sample-source.txt檔案相同的內容：

blob 容器 Azure 入口網站頁面，其中顯示上傳的檔案

如果您已建立名為 AZURE_STORAGE_CONNECTION_STRING的環境變數，您也可以使用 Azure CLI，使用 az storage blob list 命令來確認 Blob 是否存在：

az storage blob list --container-name blob-container-01

如果您依照指示使用無密碼驗證，您可以使用記憶體帳戶的連接字串，將參數新增--connection-string至上述命令。若要取得連接字串，請使用 az storage account show-connection-string 命令。

az storage account show-connection-string --resource-group PythonAzureExample-Storage-rg --name pythonazurestorage12345 --output tsv

使用整個連接字串做為參數的值--connection-string。

注意

如果您的 Azure 使用者帳戶在容器上具有「記憶體 Blob 數據參與者」角色，您可以使用下列命令來列出容器中的 Blob：

az storage blob list --container-name blob-container-01 --account-name pythonazurestorage12345 --auth-mode login

6.清除資源

如果您不需要保留此範例中使用的資源群組和記憶體資源，請執行 az group delete 命令。資源群組不會在您的訂用帳戶中產生任何持續費用，但資源群組中的資源，例如記憶體帳戶，可能會繼續產生費用。最好清除您未主動使用的任何群組。自 --no-wait 變數可讓命令立即傳回，而不是等待作業完成。

az group delete -n PythonAzureExample-Storage-rg  --no-wait

您也可以使用 ResourceManagementClient.resource_groups.begin_delete 方法，從程式代碼中刪除資源群組。範例：建立資源群組中的程式代碼會示範使用方式。

如果您依照指示使用無密碼驗證，最好刪除您所建立的應用程式服務主體。您可以使用 az ad app delete 命令。以 <服務主體的應用程式識別碼取代AZURE_CLIENT_ID> 佔位元元。

az ad app delete --id <AZURE_CLIENT_ID>

共用方式為