Snabbstart: Microsoft Azure Confidential Ledger-klientbibliotek för Python

  • Artikel

Kom igång med klientbiblioteket för Microsoft Azure Confidential Ledger för Python. Följ stegen i den här artikeln för att installera paketet och prova exempelkod för grundläggande uppgifter.

Microsoft Azure Confidential Ledger är en ny och mycket säker tjänst för hantering av känsliga dataposter. Baserat på en tillståndsbaserad blockkedjemodell erbjuder Azure Confidential Ledger unika fördelar med dataintegritet, till exempel oföränderlighet (endast att lägga till transaktionsregistret) och manipuleringsbevis (för att säkerställa att alla poster hålls intakta).

Om du inte har en Azure-prenumeration skapar du ett kostnadsfritt Azure-konto innan du börjar.

API-referensdokumentation Bibliotek källkodspaket | (Python Package Index) Hanteringsbibliotekspaket| (Python Package Index) Klientbibliotek |

Förutsättningar

Konfigurera

Den här snabbstarten använder Azure Identity-biblioteket, tillsammans med Azure CLI eller Azure PowerShell, för att autentisera användaren till Azure Services. Utvecklare kan också använda Visual Studio eller Visual Studio Code för att autentisera sina anrop. Mer information finns i Autentisera klienten med Azure Identity-klientbiblioteket.

Logga in på Azure

Logga in på Azure med azure CLI az login-kommandot eller cmdleten Azure PowerShell Anslut-AzAccount.

az login

Om CLI eller PowerShell kan öppna standardwebbläsaren kommer den att göra det och läsa in en Azure-inloggningssida. Annars går du till https://aka.ms/devicelogin och anger auktoriseringskoden som visas i terminalen.

Logga in med dina kontoautentiseringsuppgifter i webbläsaren om du uppmanas att göra det.

Installera paketen

I en terminal eller kommandotolk skapar du en lämplig projektmapp och skapar och aktiverar sedan en virtuell Python-miljö enligt beskrivningen i Använda virtuella Python-miljöer.

Installera Microsoft Entra-identitetsklientbiblioteket:

pip install azure-identity

Installera klientbiblioteket för azure confidential ledger control plane.

pip install azure.mgmt.confidentialledger

Installera klientbiblioteket för Azure Confidential Ledger-dataplanet.

pip install azure.confidentialledger

Skapa en resursgrupp

En resursgrupp är en logisk container där Azure-resurser distribueras och hanteras. Använd kommandot Azure CLI az group create eller cmdleten Azure PowerShell New-AzResourceGroup för att skapa en resursgrupp med namnet myResourceGroup på platsen eastus .

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

Registrera microsoft. ConfidentialLedger-resursprovider

En resursprovider är en tjänst som tillhandahåller Azure-resurser. Använd kommandot Azure CLI az provider register eller cmdleten Azure PowerShell Register-AzResourceProvider för att registrera azure confidential ledger-resursprovidern microsoft. ConfidentialLedger'.

az provider register --namespace "microsoft.ConfidentialLedger"

Du kan kontrollera att registreringen är klar med azure CLI az provider register-kommandot eller cmdleten Azure PowerShell Get-AzResourceProvider .

az provider show --namespace "microsoft.ConfidentialLedger"

Skapa din Python-app

Initiering

Nu kan vi börja skriva vårt Python-program. Importera först de nödvändiga paketen.

# 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

Använd sedan klassen DefaultAzureCredential för att autentisera appen.

credential = DefaultAzureCredential()

Slutför installationen genom att ange några variabler som ska användas i ditt program: resursgruppen (myResourceGroup), namnet på transaktionsregistret som du vill skapa och två URL:er som ska användas av dataplanets klientbibliotek.

Viktigt!

Varje transaktionsregister måste ha ett globalt unikt namn. Ersätt <ditt unika transaktionsregisternamn> med namnet på din transaktionsregister i följande exempel.

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"

Använda kontrollplanets klientbibliotek

Klientbiblioteket för kontrollplanet (azure.mgmt.confidentialledger) tillåter åtgärder i transaktionsregister, till exempel skapande, ändring, borttagning, listande av de transaktionsregister som är associerade med en prenumeration och få information om en specifik transaktionsregister.

I koden skapar du först en kontrollplansklient genom att skicka variabeln ConfidentialLedgerAPI för autentiseringsuppgifter och ditt Azure-prenumerations-ID (som båda anges ovan).

confidential_ledger_mgmt = ConfidentialLedgerAPI(
    credential, subscription_id
)

Nu kan vi skapa en transaktionsbok med hjälp av begin_create. Funktionen begin_create kräver tre parametrar: resursgruppen, ett namn på transaktionsregistret och ett "egenskapsobjekt".

Skapa en properties ordlista med följande nycklar och värden och tilldela den till en variabel.

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

ledger_properties = ConfidentialLedger(**properties)

Skicka nu resursgruppen, namnet på din transaktionsregister och egenskapsobjektet till begin_create.

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

Om du vill kontrollera att transaktionsregistret har skapats kan du visa dess information med hjälp av get funktionen .

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

Använda dataplanets klientbibliotek

Nu när vi har ett transaktionsregister kan du interagera med det med hjälp av dataplanets klientbibliotek (azure.confidentialledger).

Först genererar och sparar vi ett konfidentiellt transaktionsregistercertifikat.

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

Nu kan vi använda nätverkscertifikatet, tillsammans med transaktionsregistrets URL och våra autentiseringsuppgifter, för att skapa en konfidentiell transaktionsregisterklient.

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

Vi är beredda att skriva till transaktionsregistret. Vi gör det med hjälp av create_ledger_entry funktionen.

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

Utskriftsfunktionen returnerar transaktions-ID:t för din skrivning till transaktionsregistret, som kan användas för att hämta meddelandet du skrev till transaktionsregistret.

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

Om du bara vill ha den senaste transaktionen som har checkats in i transaktionsregistret kan du använda get_current_ledger_entry funktionen .

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

Utskriftsfunktionen returnerar "Hello world!", eftersom det är meddelandet i transaktionsregistret som motsvarar transaktions-ID:t och är den senaste transaktionen.

Full exempelkod

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

Pollers

Om du vill vänta tills din skrivtransaktion har checkats in i din transaktionsregister kan du använda begin_create_ledger_entry funktionen. Detta returnerar en poller för att vänta tills posten är vederbörligen bekräftad.

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

När du kör frågor mot en äldre transaktionsregisterpost måste transaktionsregistret läsa posten från disken och verifiera den. Du kan använda begin_get_ledger_entry funktionen för att skapa en poller som väntar tills den efterfrågade posten är i ett redo tillstånd att visa.

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

Rensa resurser

Andra konfidentiella transaktionsregisterartiklar i Azure kan bygga vidare på den här snabbstarten. Om du planerar att fortsätta med efterföljande snabbstarter och självstudier kan du lämna kvar de här resurserna.

När du är klar med resurserna som skapats i den här artikeln använder du kommandot Azure CLI az group delete för att ta bort resursgruppen och alla dess inneslutna resurser:

az group delete --resource-group myResourceGroup

Nästa steg