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

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

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

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

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

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

先决条件

设置

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

登录到 Azure

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

az login

如果 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 的资源组 。

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

注册 microsoft.ConfidentialLedger 资源提供程序

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

az provider register --namespace "microsoft.ConfidentialLedger"

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

az provider show --namespace "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

后续步骤