Schnellstart: Microsoft Azure Confidential Ledger-Clientbibliothek für Python

  • Artikel

Führen Sie erste Schritte mit der Microsoft Azure Confidential Ledger-Clientbibliothek für Python aus. Führen Sie die Schritte in diesem Artikel aus, um das Pakets zu installieren und den Beispielcode für grundlegende Aufgaben zu testen.

Microsoft Azure Confidential Ledger ist ein neuer und äußerst sicherer Dienst für die Verwaltung vertraulicher Datensätze. Basierend auf einem berechtigungsbasierten Block Chain-Modell bietet Azure Confidential Ledger einzigartige Vorteile bei der Datenintegrität, z. B. Unveränderlichkeit (der Ledger unterstützt nur Anfügevorgänge) und Manipulationsschutz (um sicherzustellen, dass alle Datensätze intakt bleiben).

Wenn Sie kein Azure-Abonnement haben, erstellen Sie ein kostenloses Azure-Konto, bevor Sie beginnen.

API-Referenzdokumentation | Quellcode der Bibliothek | Paketverwaltungsbibliothek (Python-Paketindex)| Paketclientbibliothek (Python-Paketindex)

Voraussetzungen

Einrichten

In dieser Schnellstartanleitung wird die Azure Identity-Bibliothek mit der Azure CLI oder Azure PowerShell verwendet, um den Benutzer bei Azure-Diensten zu authentifizieren. Entwickler können auch Visual Studio oder Visual Studio Code verwenden, um ihre Aufrufe zu authentifizieren. Weitere Informationen finden Sie unter Authentifizieren des Clients mit der Azure Identity-Clientbibliothek.

Anmelden bei Azure

Melden Sie sich über den Azure CLI-Befehl az login oder das Azure PowerShell-Cmdlet Connect-AzAccount bei Azure an.

Die CLI oder PowerShell öffnet Ihren Standardbrowser, sofern sie oder der Dienst dazu in der Lage ist, und lädt eine Azure-Anmeldeseite. Besuchen Sie andernfalls https://aka.ms/devicelogin, und geben Sie den in Ihrem Terminal angezeigten Autorisierungscode ein.

Melden Sie sich dann im Browser mit Ihren Anmeldeinformationen an, wenn Sie dazu aufgefordert werden.

Installieren der Pakete

Erstellen Sie in einem Terminal oder an einer Eingabeaufforderung einen geeigneten Projektordner, und erstellen und aktivieren Sie dann eine virtuelle Python-Umgebung, wie unter Verwenden von virtuellen Python-Umgebungen beschrieben.

Installieren Sie die Microsoft Entra Identity-Clientbibliothek:

pip install azure-identity

Installieren Sie die Azure Confidential Ledger-Clientbibliothek für die Steuerungsebene:

pip install azure.mgmt.confidentialledger

Installieren Sie die Azure Confidential Ledger-Clientbibliothek für die Datenebene:

pip install azure.confidentialledger

Erstellen einer Ressourcengruppe

Eine Ressourcengruppe ist ein logischer Container, in dem Azure-Ressourcen bereitgestellt und verwaltet werden. Erstellen Sie mit dem Azure CLI-Befehl az group create oder mit dem Azure PowerShell-Cmdlet New-AzResourceGroup eine Ressourcengruppe mit dem Namen myResourceGroup am Standort eastus.

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

Registrieren Sie microsoft.ConfidentialLedger-Ressourcenanbieter

Ein Ressourcenanbieter ist ein Dienst, der Azure-Ressourcen bereitstellt. Verwenden Sie den Azure CLI-Befehl az provider register oder das Azure PowerShell-Cmdlet Register-AzResourceProvider, um den Azure Confidential Ledger-Ressourcenanbieter „microsoft.ConfidentialLedger“ zu registrieren.

az provider register --namespace "microsoft.ConfidentialLedger"

Mit dem Azure CLI-Befehl az provider register oder dem Azure PowerShell-Cmdlet Get-AzResourceProvider können Sie überprüfen, ob die Registrierung abgeschlossen ist.

az provider show --namespace "microsoft.ConfidentialLedger"

Erstellen Ihrer Python-App

Initialisierung

Wir können jetzt damit beginnen, unsere Python-Anwendung zu schreiben. Importieren Sie zunächst die erforderlichen Pakete.

# 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

Als Nächstes verwenden Sie die DefaultAzureCredential-Klasse, um die App zu authentifizieren.

credential = DefaultAzureCredential()

Sie schließen das Setup ab, indem Sie einige Variablen für die Verwendung in Ihrer Anwendung festlegen: die Ressourcengruppe (myResourceGroup), den Namen des Ledgers, den Sie erstellen möchten, und zwei URLs, die von der Clientbibliothek der Datenebene verwendet werden sollen.

Wichtig

Jedes Ledger muss einen weltweit eindeutigen Namen haben. Ersetzen Sie in dem folgenden Beispiel <your-unique-ledger-name> durch den Namen Ihres Ledgers.

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"

Verwenden der Steuerungsebene-Clientbibliothek

Die Steuerungsebene-Clientbibliothek der (azure.mgmt.confidentialledger) ermöglicht Vorgänge für Ledger, z. B. Erstellen, Ändern, Löschen und Auflisten der einem Abonnement zugeordneten Ledger und Abrufen der Details eines bestimmten Ledgers.

Im Code erstellen wir zunächst einen Steuerungsebenen-Client, indem wir der ConfidentialLedgerAPI die Anmeldeinformationsvariable und Ihre Azure-Abonnement-ID übergeben (die beide oben festgelegt sind).

confidential_ledger_mgmt = ConfidentialLedgerAPI(
    credential, subscription_id
)

Wir können jetzt mit begin_create einen Ledger erstellen. Die begin_create-Funktion erfordert drei Parameter: Ihre Ressourcengruppe, einen Namen für den Ledger und ein „Eigenschaften“-Objekt.

Erstellen Sie ein properties-Wörterbuch mit den folgenden Schlüsseln und Werten, und weisen Sie es einer Variablen zu.

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

ledger_properties = ConfidentialLedger(**properties)

Übergeben Sie nun die Ressourcengruppe, den Namen Ihres Ledgers und das Eigenschaftsobjekt an begin_create.

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

Um zu überprüfen, ob Ihr Ledger erfolgreich erstellt wurde, zeigen Sie seine Details mithilfe der get-Funktion an.

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

Verwenden der Datenebenen-Clientbibliothek

Nachdem wir nun über einen Ledger verfügen, interagieren Sie mit der Datenebene-Clientbibliothek (azure.confidentialledger).

Zunächst generieren und speichern wir ein Confidential Ledger-Zertifikat.

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

Jetzt können Sie das Netzwerkzertifikat zusammen mit der Ledger-URL und den Anmeldeinformationen verwenden, um einen Confidential Ledger-Client zu erstellen:

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

Wir sind bereit, in den Ledger zu schreiben. Dazu verwenden wir die create_ledger_entry-Funktion.

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

Die print-Funktion gibt die Transaktions-ID Ihres Schreibvorgangs an den Ledger zurück, der zum Abrufen der Nachricht verwendet werden kann, die Sie in den Ledger geschrieben haben.

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

Wenn Sie nur die letzte Transaktion wünschen, die im Ledger committet wurde, können Sie die Funktion get_current_ledger_entry verwenden.

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

Die print-Funktion gibt „Hello World!“ zurück, da dies die Meldung im Ledger ist, die der Transaktions-ID entspricht und die letzte Transaktion ist.

Vollständiger Beispielcode

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

Poller

Wenn Sie warten möchten, bis Ihre Schreibtransaktion in Ihrem Ledger committet wurde, können Sie die Funktion begin_create_ledger_entry verwenden. Dadurch wird ein Poller zurückgegeben, der wartet, bis der Eintrag dauerhaft committet wurde.

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

Das Abfragen eines älteren Ledgereintrags erfordert, dass der Ledger den Eintrag vom Datenträger liest und überprüft. Sie können die Funktion begin_get_ledger_entry verwenden, um einen Poller zu erstellen, der wartet, bis der abgefragte Eintrag in einem einsehbaren Zustand ist.

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

Bereinigen von Ressourcen

Weitere Artikel zu Azure Confidential Ledger können auf dieser Schnellstartanleitung aufbauen. Falls Sie mit weiteren Schnellstartanleitungen und Tutorials fortfahren möchten, sollten Sie die Ressourcen nicht bereinigen.

Andernfalls, wenn Sie mit den in diesem Artikel erstellten Ressourcen fertig sind, verwenden Sie den Azure CLI-Befehl az group delete, um die Ressourcengruppe und alle darin enthaltenen Ressourcen zu löschen:

az group delete --resource-group myResourceGroup

Nächste Schritte