你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
适用于 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。
关键概念
Secret
机密由机密值及其关联的元数据和管理信息组成。 此库将机密值作为字符串处理，但 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-core 文档 。
不再需要异步客户端和凭据时，应将其关闭。 这些对象是异步上下文管理器并定义异步 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、标头等) 的基本信息记录在信息级别。
可以使用 参数在客户端 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 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。 直接按机器人提供的说明操作。 只需使用 CLA 对所有存储库执行一次这样的操作。
此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答；若有其他任何问题或意见，请联系 opencode@microsoft.com。
