共用方式為

快速入門：適用於 Python 的 Microsoft Azure 機密總帳用戶端程式庫

  • 發行項

開始使用適用於 Python 的 Microsoft Azure 機密總帳用戶端程式庫。 請遵循步驟中的步驟來安裝套件，並試用基本工作的範例程式碼。

Microsoft Azure 機密總帳是一項高安全性的新服務，可用來管理敏感性資料記錄。 Azure 機密總帳以具有權限的區塊鏈模型為基礎，可提供獨特的資料完整性優勢，例如不變性 (讓總帳只能附加) 和防篡改 (以確保所有記錄都保持不變)。

如果您沒有 Azure 訂用帳戶，請在開始之前先建立 Azure 免費帳戶。

API 參考文件 | 程式庫原始程式碼 | 套件 (Python Package Index) 管理程式庫| 套件 (Python Package Index) 用戶端程式庫

必要條件

設定

本快速入門使用 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 訂用帳戶識別碼( 兩者皆已在上方設定)，以建立控制平面用戶端。

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'])

列印函式會傳回總帳寫入交易識別碼，其可供用來擷取寫入到總帳的訊息。

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']}")

列印函式會傳回「Hello world!」，因為這是總帳中與交易識別碼對應且為最新交易的訊息。

完整範例程式碼

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

下一步