共用方式為


適用于 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-secretsazure-identity

pip install azure-keyvault-secrets azure-identity

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

必要條件

驗證用戶端

若要與 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.aioSecretClient

重要概念

祕密

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

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

範例

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

設定祕密

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。

曝光數