你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 Python 的 Azure 密钥保管库 证书客户端库 - 版本 4.7.0

Azure Key Vault 有助于解决以下问题：

• 证书管理 (此库) - 创建、管理和部署公共和专用 SSL/TLS 证书
• 加密密钥管理 (azure-keyvault-keys) - 创建、存储和控制对用于加密数据的密钥的访问
• 机密管理 (azure-keyvault-secrets) - 安全地存储和控制对令牌、密码、证书、API 密钥和其他机密的访问
• 保管库管理 (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 或更高版本。 有关更多详细信息，请参阅 Azure SDK for Python 版本支持策略。

入门

安装包

使用 pip 安装 azure-keyvault-certificates 和 azure-identity：

pip install azure-keyvault-certificates azure-identity

azure-identity 用于 Azure Active Directory 身份验证，如下所示。

先决条件

• Azure 订阅
• Python 3.7 或更高版本
• 现有的 Azure 密钥保管库。 如果需要创建一个，可以使用 Azure CLI 执行 本文档中的步骤。

验证客户端

若要与 Azure 密钥保管库 服务交互，需要一个 CertificateClient 实例，以及一个保管库 URL 和一个凭据对象。 本文档演示如何使用适用于大多数方案（包括本地开发和生产环境）的 DefaultAzureCredential。 建议使用 托管标识 在生产环境中进行身份验证。

有关其他身份验证方法及其相应凭据类型的详细信息，请参阅 azure-identity 文档。

创建客户端

为 DefaultAzureCredential 配置环境以使用适当的身份验证方法后，可以执行以下操作来创建证书客户端 (将 的值 VAULT_URL 替换为保管库的 URL) ：

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

注意： 对于异步客户端，请改为导入 azure.keyvault.certificates.aio的 CertificateClient 。

关键概念

CertificateClient

使用 CertificateClient 可以从保管库获取证书、创建新证书和现有证书的新版本、更新证书元数据以及删除证书。 还可以管理证书颁发者、联系人和证书的管理策略。 以下示例对此进行了说明。

示例

本部分包含涵盖常见任务的代码片段：

• 创建证书
• 检索证书
• 更新现有证书的属性
• 删除证书
• 列出证书的属性
• 异步操作
• 异步创建证书
• 异步列出证书的属性

创建证书

begin_create_certificate创建要存储在 Azure 密钥保管库中的证书。 如果已存在同名证书，则会创建该证书的新版本。 在创建证书之前，可以创建证书的管理策略，或使用我们的默认策略。 此方法返回长时间运行的操作轮询器。

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient, CertificatePolicy

credential = DefaultAzureCredential()

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

create_certificate_poller = certificate_client.begin_create_certificate(
    certificate_name="cert-name", policy=CertificatePolicy.get_default()
)
print(create_certificate_poller.result())

如果要检查证书创建状态，可以在轮询器上调用 status() ，或使用证书名称get_certificate_operation。

检索证书

get_certificate检索以前存储在密钥保管库中的证书的最新版本。

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

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

certificate = certificate_client.get_certificate("cert-name")

print(certificate.name)
print(certificate.properties.version)
print(certificate.policy.issuer_name)

get_certificate_version 检索证书的特定版本。

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
certificate = certificate_client.get_certificate_version(certificate_name="cert-name", version="cert-version")

print(certificate.name)
print(certificate.properties.version)

更新现有证书的属性

update_certificate_properties更新以前存储在密钥保管库中的证书。

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

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

# we will now disable the certificate for further use
updated_certificate= certificate_client.update_certificate_properties(
    certificate_name="cert-name", enabled=False
)

print(updated_certificate.name)
print(updated_certificate.properties.enabled)

删除证书

begin_delete_certificate请求密钥保管库删除证书，并返回一个轮询程序，以便等待删除完成。 如果保管库已启用 软删除 ，并且你想要清除 (尽快永久删除证书) ，则等待会很有帮助。 禁用 软删除 时， begin_delete_certificate 其本身是永久性的。

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

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

deleted_certificate_poller = certificate_client.begin_delete_certificate("cert-name")

deleted_certificate = deleted_certificate_poller.result()
print(deleted_certificate.name)
print(deleted_certificate.deleted_on)

列出证书的属性

list_properties_of_certificates列出了指定密钥保管库中所有证书的属性。

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

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

certificates = certificate_client.list_properties_of_certificates()

for certificate in certificates:
    # this list doesn't include versions of the certificates
    print(certificate.name)

异步操作

此库包含一组完整的异步 API。 若要使用它们，必须先安装异步传输，例如 aiohttp。 有关详细信息 ，请参阅 azure-core 文档 。

当不再需要异步客户端和凭据时，应将其关闭。 这些对象是异步上下文管理器并定义异步 close 方法。 例如：

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient

credential = DefaultAzureCredential()

# call close when the client and credential are no longer needed
client = CertificateClient(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 = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
async with client:
  async with credential:
    ...

异步创建证书

create_certificate创建要存储在 Azure 密钥保管库中的证书。 如果已存在同名证书，则会创建该证书的新版本。 在创建证书之前，可以创建证书的管理策略，或使用我们的默认策略。 create_certificate如果创建成功，则等待将返回创建的证书，否则返回 CertificateOperation。

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient
from azure.keyvault.certificates import CertificatePolicy

credential = DefaultAzureCredential()

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

create_certificate_result = await certificate_client.create_certificate(
    certificate_name="cert-name", policy=CertificatePolicy.get_default()
)
print(create_certificate_result)

异步列出证书的属性

list_properties_of_certificates 列出了客户端保管库中证书的所有属性：

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient

credential = DefaultAzureCredential()

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

certificates = certificate_client.list_properties_of_certificates()
async for certificate in certificates:
    print(certificate.name)

故障排除

有关如何诊断各种故障方案的详细信息，azure-keyvault-certificates请参阅故障排除指南。

常规

密钥保管库客户端会引发 azure-core 中定义的异常。 例如，如果尝试获取保管库中不存在的密钥， CertificateClient 会引发 ResourceNotFoundError：

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient
from azure.core.exceptions import ResourceNotFoundError

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

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

日志记录

此库使用标准 日志记录 库进行日志记录。 有关 HTTP 会话 (URL、标头等的基本信息，) 在 INFO 级别记录。

可以使用 参数在客户端 logging_enable 上启用详细的调试级别日志记录，包括请求/响应正文和未处理标头：

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient
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
client = CertificateClient(
    vault_url="https://my-key-vault.vault.azure.net/",
    credential=credential,
    logging_enable=True
)

还可以为任何单个操作启用网络跟踪日志记录：

certificate = certificate_client.get_certificate(certificate_name="cert-name", logging_enable=True)

后续步骤

Azure SDK for Python GitHub 存储库中提供了多个示例。 这些示例提供了其他密钥保管库方案的示例代码： |文件 |说明 | |-------------|-------------| |hello_world.py (异步版本) |创建/获取/更新/删除证书 | |backup_restore_operations.py (异步版本) |备份和恢复证书 | |import_certificate.py (异步版本) |将 PKCS#12 (PFX) 和 PEM 格式的证书导入密钥保管库 | |list_operations.py (异步版本) |列出证书 | |recover_purge_operations.py (异步版本) |恢复和清除证书 | |issuers.py (异步版本) |管理证书颁发者 | |contacts.py (异步版本) |管理证书联系人 | |parse_certificate.py (异步版本) |提取证书的私钥 |

其他文档

有关 Azure 密钥保管库的更多文档，请参阅 API 参考文档。

贡献

本项目欢迎贡献和建议。 大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。 有关详细信息，请访问 https://cla.microsoft.com 。

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。 直接按机器人提供的说明操作。 只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答；若有其他任何问题或意见，请联系 opencode@microsoft.com。