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

快速入门：适用于 Python 的 Microsoft Azure 机密账本客户端库

项目
08/08/2024

开始使用适用于 Python 的 Microsoft Azure 机密账本客户端库。按照本文的步骤安装包，并试用基本任务的示例代码。

Microsoft Azure 机密账本是高度安全的新服务，用于管理敏感数据记录。根据授权区块链模型，Azure 机密账本提供独特的数据完整性优势，例如保持不变（使账本只能追加）和防篡改（以确保所有记录保持完整）。

如果没有 Azure 订阅，请在开始之前创建一个 Azure 免费帐户。

API 参考文档 | 库源代码 | 包（Python 包索引）管理库| 包（Python 包索引）客户端库

先决条件

Azure 订阅 - 免费创建订阅。 - 订阅所有者 - 只有在 Azure 订阅上具有所有者权限的用户才能创建机密账本。在继续此快速入门之前，请先确认你具有适当的访问权限。
Azure SDK for Python 支持的 Python 版本。
Azure CLI 或 Azure PowerShell。

设置

本快速入门结合使用 Azure 标识库和 Azure CLI 或 Azure PowerShell，向 Azure 服务验证用户身份。开发人员还可以使用 Visual Studio 或 Visual Studio Code 来验证其调用。有关详细信息，请参阅使用 Azure 标识客户端库对客户端进行身份验证。

使用 Azure CLI az login 命令或 Azure PowerShell Connect-AzAccount cmdlet 登录到 Azure。

Azure CLI
Azure PowerShell

az login

Connect-AzAccount

如果 CLI 或 PowerShell 可以打开默认浏览器，它将这样做并加载 Azure 登录页。否则，请访问 https://aka.ms/devicelogin，然后输入终端中显示的授权代码。

如果出现提示，则在浏览器中使用帐户凭据登录。

安装包

在终端或命令提示符中，创建合适的项目文件夹，然后创建并激活 Python 虚拟环境，如使用 Python 虚拟环境中所述。

安装 Microsoft Entra 标识客户端库：

pip install azure-identity

安装 Azure 机密账本控制平面客户端库。

pip install azure.mgmt.confidentialledger

安装 Azure 机密账本数据平面客户端库。

pip install azure.confidentialledger

创建资源组

资源组是在其中部署和管理 Azure 资源的逻辑容器。使用 Azure CLI az group create 命令或 Azure PowerShell New-AzResourceGroup cmdlet 在 eastus 位置创建一个名为 myResourceGroup 的资源组。

Azure CLI
Azure PowerShell

az group create --name "myResourceGroup" -l "EastUS"

New-AzResourceGroup -Name myResourceGroup -Location eastus

注册 microsoft.ConfidentialLedger 资源提供程序

资源提供程序是提供 Azure 资源的服务。使用 Azure CLI az provider register 命令或 Azure PowerShell Register-AzResourceProvider cmdlet 注册 Azure 机密账本资源提供程序“microsoft.ConfidentialLedger”。

Azure CLI
Azure PowerShell

az provider register --namespace "microsoft.ConfidentialLedger"

Register-AzResourceProvider -ProviderNamespace "microsoft.ConfidentialLedger"

可以使用 Azure CLI az provider register 命令或 Azure PowerShell Get-AzResourceProvider cmdlet 验证注册是否完成。

Azure CLI
Azure PowerShell

az provider show --namespace "microsoft.ConfidentialLedger"

Get-AzResourceProvider -ProviderNamespace "microsoft.ConfidentialLedger"

创建 python 应用

初始化

现在，我们可以开始编写 Python 应用程序。首先，导入所需的包。

# Import the Azure authentication library

from azure.identity import DefaultAzureCredential

## Import the control plane sdk

from azure.mgmt.confidentialledger import ConfidentialLedger as ConfidentialLedgerAPI
from azure.mgmt.confidentialledger.models import ConfidentialLedger

# import the data plane sdk

from azure.confidentialledger import ConfidentialLedgerClient
from azure.confidentialledger.certificate import ConfidentialLedgerCertificateClient

接下来，请使用 DefaultAzureCredential 类对应用进行身份验证。

credential = DefaultAzureCredential()

通过设置要在应用程序中使用的某些变量来完成设置：资源组 (myResourceGroup)、要创建的账本名称以及数据平面客户端库使用的两个 url。

重要

每个账本必须具有全局唯一名称。在以下示例中，将 <your-unique-ledger-name> 替换为账本名称。

resource_group = "<azure-resource-group>"
ledger_name = "<your-unique-ledger-name>"
subscription_id = "<azure-subscription-id>"

identity_url = "https://identity.confidential-ledger.core.azure.com"
ledger_url = "https://" + ledger_name + ".confidential-ledger.azure.com"

使用控制平面客户端库

控制平面客户端库 (azure.mgmt.confidentialledger) 允许对账本进行操作（如创建、修改、删除），列出与订阅关联的账本，并获取特定账本的详细信息。

在代码中，首先通过传递 ConfidentialLedgerAPI 凭据变量和 Azure 订阅 ID（两者均在上面设置）来创建控制平面客户端。

confidential_ledger_mgmt = ConfidentialLedgerAPI(
    credential, subscription_id
)

现在可以使用 begin_create 创建账本。 begin_create 函数需要三个参数：资源组、账本名称和“properties”对象。

创建具有以下键和值的 properties 字典，并将其分配给变量。

properties = {
    "location": "eastus",
    "tags": {},
    "properties": {
        "ledgerType": "Public",
        "aadBasedSecurityPrincipals": [],
    },
}

ledger_properties = ConfidentialLedger(**properties)

现在，将资源组、账本名称和 properties 对象传递给 begin_create。

confidential_ledger_mgmt.ledger.begin_create(resource_group, ledger_name, ledger_properties)

若要验证账本是否成功创建，请使用 get 函数查看其详细信息。

myledger = confidential_ledger_mgmt.ledger.get(resource_group, ledger_name)

print("Here are the details of your newly created ledger:")
print (f"- Name: {myledger.name}")
print (f"- Location: {myledger.location}")
print (f"- ID: {myledger.id}")

使用数据平面客户端库

有了一个账本后，就可以使用数据平面客户端库 (azure.confidentialledger) 与其进行交互了。

首先，我们生成并保存机密账本证书。

identity_client = ConfidentialLedgerCertificateClient(identity_url)
network_identity = identity_client.get_ledger_identity(
     ledger_id=ledger_name
)

ledger_tls_cert_file_name = "networkcert.pem"
with open(ledger_tls_cert_file_name, "w") as cert_file:
    cert_file.write(network_identity['ledgerTlsCertificate'])

现在，我们可以结合使用网络证书和账本 URL 以及凭据来创建机密账本客户端。

ledger_client = ConfidentialLedgerClient(
     endpoint=ledger_url, 
     credential=credential,
     ledger_certificate_path=ledger_tls_cert_file_name
)

我们已准备好写入账本。我们将使用 create_ledger_entry 函数执行此操作。

sample_entry = {"contents": "Hello world!"}
append_result = ledger_client.create_ledger_entry(entry=sample_entry)
print(append_result['transactionId'])

print 函数将返回写入账本的事务 ID，该 ID 可用于检索写入账本的消息。

entry = ledger_client.get_ledger_entry(transaction_id=append_result['transactionId'])['entry']
print(f"Entry (transaction id = {entry['transactionId']}) in collection {entry['collectionId']}: {entry['contents']}")

如果只需要提交到账本的最新事务，则可以使用 get_current_ledger_entry 函数。

latest_entry = ledger_client.get_current_ledger_entry()
print(f"Current entry (transaction id = {latest_entry['transactionId']}) in collection {latest_entry['collectionId']}: {latest_entry['contents']}")

print 函数将返回“Hello world!”，因为这是账本中对应于事务 ID 的消息，并且是最新事务。

完整示例代码

import time
from azure.identity import DefaultAzureCredential

## Import control plane sdk

from azure.mgmt.confidentialledger import ConfidentialLedger as ConfidentialLedgerAPI
from azure.mgmt.confidentialledger.models import ConfidentialLedger

# import data plane sdk

from azure.confidentialledger import ConfidentialLedgerClient
from azure.confidentialledger.certificate import ConfidentialLedgerCertificateClient

# Set variables

resource_group = "<azure-resource-group>"
ledger_name = "<your-unique-ledger-name>"
subscription_id = "<azure-subscription-id>"

identity_url = "https://identity.confidential-ledger.core.azure.com"
ledger_url = "https://" + ledger_name + ".confidential-ledger.azure.com"

# Authentication

# Need to do az login to get default credential to work

credential = DefaultAzureCredential()

# Control plane (azure.mgmt.confidentialledger)
# 
# initialize endpoint with credential and subscription

confidential_ledger_mgmt = ConfidentialLedgerAPI(
    credential, "<subscription-id>"
)

# Create properties dictionary for begin_create call 

properties = {
    "location": "eastus",
    "tags": {},
    "properties": {
        "ledgerType": "Public",
        "aadBasedSecurityPrincipals": [],
    },
}

ledger_properties = ConfidentialLedger(**properties)

# Create a ledger

confidential_ledger_mgmt.ledger.begin_create(resource_group, ledger_name, ledger_properties)

# Get the details of the ledger you just created

print(f"{resource_group} / {ledger_name}")
 
print("Here are the details of your newly created ledger:")
myledger = confidential_ledger_mgmt.ledger.get(resource_group, ledger_name)

print (f"- Name: {myledger.name}")
print (f"- Location: {myledger.location}")
print (f"- ID: {myledger.id}")

# Data plane (azure.confidentialledger)
#
# Create a CL client

identity_client = ConfidentialLedgerCertificateClient(identity_url)
network_identity = identity_client.get_ledger_identity(
     ledger_id=ledger_name
)

ledger_tls_cert_file_name = "networkcert.pem"
with open(ledger_tls_cert_file_name, "w") as cert_file:
    cert_file.write(network_identity['ledgerTlsCertificate'])


ledger_client = ConfidentialLedgerClient(
     endpoint=ledger_url, 
     credential=credential,
     ledger_certificate_path=ledger_tls_cert_file_name
)

# Write to the ledger
sample_entry = {"contents": "Hello world!"}
ledger_client.create_ledger_entry(entry=sample_entry)
  
# Read from the ledger
latest_entry = ledger_client.get_current_ledger_entry()
print(f"Current entry (transaction id = {latest_entry['transactionId']}) in collection {latest_entry['collectionId']}: {latest_entry['contents']}")

轮询器

如果要等待写入事务提交到账本，可以使用 begin_create_ledger_entry 函数。这将返回一个轮询器，以等到条目长久稳定提交。

sample_entry = {"contents": "Hello world!"}
ledger_entry_poller = ledger_client.begin_create_ledger_entry( 
    entry=sample_entry
)
ledger_entry_result = ledger_entry_poller.result()

查询较旧的账本条目需要账本从磁盘读取条目并对其进行验证。可以使用 begin_get_ledger_entry 函数创建一个轮询器，该轮询器将等到查询的条目处于可供查看的就绪状态。

get_entry_poller = ledger_client.begin_get_ledger_entry(
    transaction_id=ledger_entry_result['transactionId']
)
entry = get_entry_poller.result()

清理资源

其他 Azure 机密账本文章可以根据本快速入门编写。如果打算继续使用后续的快速入门和教程，则可能需要保留这些资源。

否则，当完成本文中创建的资源后，请使用 Azure CLI az group delete 命令删除资源组及其包含的所有资源：

az group delete --resource-group myResourceGroup

通过