適用于 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 或更新版本才能使用此套件。 如需詳細資訊，請參閱 適用于 Python 的 Azure SDK 版本支援原則。

開始使用

安裝套件

使用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 核心檔 。

不再需要非同步用戶端和認證時，應該關閉它們。 這些物件是非同步內容管理員，並定義非同步 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 上啟用詳細的 DEBUG 層級記錄，包括要求/回應主體和未回應標頭：

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

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