適用于 Python 的 Azure 金鑰保存庫秘密用戶端程式庫 - 4.7.0 版

Azure Key Vault 可協助您解決下列問題：

• 此程式庫) (秘密管理 - 安全地儲存和控制權杖、密碼、憑證、API 金鑰和其他秘密的存取權
• 密碼編譯金鑰管理 (azure-keyvault-keys) - 建立、儲存和控制用來加密資料的金鑰存取
• 憑證管理 (azure-keyvault-certificates) - 建立、管理和部署公用和私人 SSL/TLS 憑證
• 保存庫管理 (azure-keyvault-administration) - 角色型存取控制 (RBAC) ，以及保存庫層級的備份和還原選項

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

免責聲明

Python 2.7 的 Azure SDK Python 套件支援已于 2022 年 1 月 1 日結束。 如需詳細資訊和問題，請參閱 https://github.com/Azure/azure-sdk-for-python/issues/20691 。 需要 Python 3.7 或更新版本才能使用此套件。 如需詳細資訊，請參閱 適用于 Python 的 Azure SDK 版本支援原則。

開始使用

安裝套件

使用pip安裝azure-keyvault-secrets和azure-identity：

pip install azure-keyvault-secrets azure-identity

azure-identity 用於 Azure Active Directory 驗證，如下所示。

必要條件

• Azure 訂用帳戶
• Python 3.7 或更新版本
• 現有的Azure 金鑰保存庫。 如果您需要建立一個，您可以依照 本檔中的步驟，使用 Azure CLI 來執行此動作。

驗證用戶端

若要與 Azure 金鑰保存庫 服務互動，您需要SecretClient的實例，以及保存庫 URL和認證物件。 本檔示範如何使用 DefaultAzureCredential，適用于大部分案例，包括本機開發和生產環境。 建議您在生產環境中使用 受控識別 來進行驗證。

如需其他驗證方法及其對應認證類型的詳細資訊，請參閱 azure-identity 檔。

建立用戶端

將環境設定為 DefaultAzureCredential 以使用適當的驗證方法之後，您可以執行下列動作來建立秘密用戶端， (將 的值 VAULT_URL 取代為您的保存庫 URL) ：

VAULT_URL = os.environ["VAULT_URL"]
credential = DefaultAzureCredential()
client = SecretClient(vault_url=VAULT_URL, credential=credential)

注意：如果是非同步用戶端，請改為匯入 azure.keyvault.secrets.aio 。 SecretClient

重要概念

祕密

秘密是由秘密值及其相關聯的中繼資料和管理資訊所組成。 此程式庫會以字串的形式處理秘密值，但 Azure 金鑰保存庫不會儲存它們。 如需秘密及其金鑰保存庫儲存和管理方式的詳細資訊，請參閱金鑰保存庫檔。

SecretClient 可以在保存庫中設定秘密值、更新秘密中繼資料和刪除秘密，如下列 範例 所示。

範例

本節包含涵蓋一般工作的程式碼片段：

• 設定祕密
• 擷取祕密
• 更新秘密中繼資料
• 刪除秘密
• 列出祕密
• 非同步 API
• 以非同步方式建立秘密
• 以非同步方式列出秘密

設定祕密

set_secret 會建立新的秘密，並變更現有秘密的值。 如果沒有具有指定名稱的秘密存在， set_secret 請使用該名稱和指定值建立新的秘密。 如果指定的名稱正在使用中， set_secret 請使用指定的值建立該密碼的新版本。

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret = secret_client.set_secret("secret-name", "secret-value")

print(secret.name)
print(secret.value)
print(secret.properties.version)

擷取祕密

get_secret擷取先前儲存在金鑰保存庫中的秘密。

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret = secret_client.get_secret("secret-name")

print(secret.name)
print(secret.value)

更新秘密中繼資料

update_secret_properties 更新秘密的中繼資料。 它無法變更秘密的值;使用 set_secret 來設定秘密的值。

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

# Clients may specify the content type of a secret to assist in interpreting the secret data when it's retrieved
content_type = "text/plain"

# We will also disable the secret for further use

updated_secret_properties = secret_client.update_secret_properties("secret-name", content_type=content_type, enabled=False)

print(updated_secret_properties.updated_on)
print(updated_secret_properties.content_type)
print(updated_secret_properties.enabled)

刪除祕密

begin_delete_secret要求金鑰保存庫刪除秘密，並傳回輪詢器，讓您等候刪除完成。 當保存庫已啟用 虛刪除 時，等候會很有説明，而且您想要儘快清除 (永久刪除) 秘密。 停用 虛刪除 時， begin_delete_secret 本身是永久的。

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
deleted_secret = secret_client.begin_delete_secret("secret-name").result()

print(deleted_secret.name)
print(deleted_secret.deleted_date)

列出密碼

list_properties_of_secrets 列出用戶端保存庫中所有秘密的屬性。 此清單不包含秘密的值。

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret_properties = secret_client.list_properties_of_secrets()

for secret_property in secret_properties:
    # the list doesn't include values or versions of the secrets
    print(secret_property.name)

非同步 API

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

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

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

credential = DefaultAzureCredential()

# call close when the client and credential are no longer needed
client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
...
await client.close()
await credential.close()

# alternatively, use them as async context managers (contextlib.AsyncExitStack can help)
client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
async with client:
  async with credential:
    ...

以非同步方式建立秘密

set_secret會使用指定的選擇性引數，在金鑰保存庫中建立秘密。

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

secret = await secret_client.set_secret("secret-name", "secret-value")

print(secret.name)
print(secret.value)
print(secret.properties.version)

以非同步方式列出秘密

list_properties_of_secrets 列出用戶端保存庫中所有秘密的屬性。

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret_properties = secret_client.list_properties_of_secrets()

async for secret_property in secret_properties:
    # the list doesn't include values or versions of the secrets
    print(secret_property.name)

疑難排解

azure-keyvault-secrets如需如何診斷各種失敗案例的詳細資訊，請參閱疑難排解指南。

一般

金鑰保存庫用戶端會引發azure-core中定義的例外狀況。 例如，如果您嘗試取得不存在於保存庫中的金鑰， SecretClient 會引發 ResourceNotFoundError：

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
from azure.core.exceptions import ResourceNotFoundError

credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

try:
    secret_client.get_secret("which-does-not-exist")
except ResourceNotFoundError as e:
    print(e.message)

記錄

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

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

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
import sys
import logging

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

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

credential = DefaultAzureCredential()

# This client will log detailed information about its HTTP sessions, at DEBUG level
secret_client = SecretClient(
    vault_url="https://my-key-vault.vault.azure.net/",
    credential=credential,
    logging_enable=True
)

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

secret_client.get_secret("my-secret", logging_enable=True)

後續步驟

Azure SDK for Python GitHub 存放庫中提供數個範例。 這些提供其他金鑰保存庫案例的範例程式碼： |檔案 |描述 | |-------------|-------------| |hello_world.py (非同步版本) |create/get/update/delete secrets | |list_operations.py (非同步版本) |秘密的基本欄表作業 | |backup_restore_operations.py (非同步版本) |備份和還原秘密 | |recover_purge_operations.py (非同步版本) |復原和清除秘密 |

其他文件

如需 Azure 金鑰保存庫的詳細資訊檔，請參閱API 參考檔。

參與

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

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

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