Szybki start: biblioteka klienta poufnego rejestru platformy Microsoft Azure dla języka Python

  • Artykuł

Rozpocznij pracę z biblioteką klienta poufnego rejestru platformy Microsoft Azure dla języka Python. Wykonaj kroki opisane w tym artykule, aby zainstalować pakiet i wypróbować przykładowy kod dla podstawowych zadań.

Poufny rejestr platformy Microsoft Azure to nowa i wysoce bezpieczna usługa do zarządzania poufnymi rekordami danych. W oparciu o model łańcucha bloków z uprawnieniami poufny rejestr platformy Azure oferuje unikatowe zalety integralności danych, takie jak niezmienność (tylko dołączanie rejestru) i sprawdzanie naruszenia (w celu zapewnienia, że wszystkie rekordy są nienaruszone).

Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto platformy Azure.

Dokumentacja interfejsu API — | biblioteka klienta pakietu źródłowego biblioteki źródłowej | biblioteki| (Python Package Index) (Python Package Index)

Wymagania wstępne

Ustawienia

W tym przewodniku Szybki start używana jest biblioteka tożsamości platformy Azure wraz z interfejsem wiersza polecenia platformy Azure lub programem Azure PowerShell do uwierzytelniania użytkownika w usługach platformy Azure. Deweloperzy mogą również używać programu Visual Studio lub Visual Studio Code do uwierzytelniania wywołań. Aby uzyskać więcej informacji, zobacz Uwierzytelnianie klienta za pomocą biblioteki klienta usługi Azure Identity.

Logowanie się do platformy Azure

Zaloguj się do platformy Azure przy użyciu polecenia az login interfejsu wiersza polecenia platformy Azure lub polecenia cmdlet azure PowerShell Połączenie-AzAccount.

Jeśli interfejs wiersza polecenia lub program PowerShell może otworzyć domyślną przeglądarkę, zrobi to i załaduje stronę logowania platformy Azure. W przeciwnym razie odwiedź https://aka.ms/devicelogin stronę i wprowadź kod autoryzacji wyświetlany w terminalu.

Jeśli zostanie wyświetlony monit, zaloguj się przy użyciu poświadczeń konta w przeglądarce.

Instalowanie pakietów

W terminalu lub wierszu polecenia utwórz odpowiedni folder projektu, a następnie utwórz i aktywuj środowisko wirtualne języka Python zgodnie z opisem w temacie Używanie środowisk wirtualnych języka Python.

Zainstaluj bibliotekę klienta tożsamości firmy Microsoft Entra:

pip install azure-identity

Zainstaluj bibliotekę klienta poufnej płaszczyzny sterowania rejestru platformy Azure.

pip install azure.mgmt.confidentialledger

Zainstaluj bibliotekę klienta poufnej płaszczyzny danych rejestru platformy Azure.

pip install azure.confidentialledger

Tworzenie grupy zasobów

Grupa zasobów to logiczny kontener przeznaczony do wdrażania zasobów platformy Azure i zarządzania nimi. Użyj polecenia az group create interfejsu wiersza polecenia platformy Azure lub polecenia cmdlet New-AzResourceGroup programu Azure PowerShell, aby utworzyć grupę zasobów o nazwie myResourceGroup w lokalizacji eastus.

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

Zarejestruj firmę Microsoft. Dostawca zasobów ConfidentialLedger

Dostawca zasobów to usługa dostarczająca zasoby platformy Azure. Użyj polecenia az provider register interfejsu wiersza polecenia platformy Azure lub polecenia cmdlet Register-AzResourceProvider programu Azure PowerShell, aby zarejestrować dostawcę zasobów rejestru poufnego platformy Azure "microsoft". PoufneLedger".

az provider register --namespace "microsoft.ConfidentialLedger"

Możesz sprawdzić, czy rejestracja została zakończona za pomocą polecenia az provider register interfejsu wiersza polecenia platformy Azure lub polecenia cmdlet Get-AzResourceProvider programu Azure PowerShell.

az provider show --namespace "microsoft.ConfidentialLedger"

Tworzenie aplikacji w języku Python

Inicjowanie

Teraz możemy rozpocząć pisanie naszej aplikacji w języku Python. Najpierw zaimportuj wymagane pakiety.

# 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

Następnie użyj klasy DefaultAzureCredential, aby uwierzytelnić aplikację.

credential = DefaultAzureCredential()

Zakończ konfigurację, ustawiając niektóre zmienne do użycia w aplikacji: grupę zasobów (myResourceGroup), nazwę rejestru, który chcesz utworzyć, oraz dwa adresy URL, które mają być używane przez bibliotekę klienta płaszczyzny danych.

Ważne

Każdy rejestr musi mieć globalnie unikatową nazwę. Zastąp <ciąg your-unique-ledger-name> nazwą rejestru w poniższym przykładzie.

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"

Korzystanie z biblioteki klienta płaszczyzny sterowania

Biblioteka klienta płaszczyzny sterowania (azure.mgmt.confidentialledger) umożliwia wykonywanie operacji w rejestrach, takich jak tworzenie, modyfikowanie, usuwanie, wyświetlanie listy rejestrów skojarzonych z subskrypcją oraz pobieranie szczegółów określonego rejestru.

W kodzie najpierw utwórz klienta płaszczyzny sterowania, przekazując poufneLedgerAPI zmienną poświadczeń i identyfikator subskrypcji platformy Azure (z których oba zostały ustawione powyżej).

confidential_ledger_mgmt = ConfidentialLedgerAPI(
    credential, subscription_id
)

Teraz możemy utworzyć rejestr przy użyciu polecenia begin_create. Funkcja begin_create wymaga trzech parametrów: grupy zasobów, nazwy rejestru i obiektu "properties".

properties Utwórz słownik z następującymi kluczami i wartościami i przypisz go do zmiennej.

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

ledger_properties = ConfidentialLedger(**properties)

Teraz przekaż grupę zasobów, nazwę rejestru i obiekt properties do begin_create.

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

Aby sprawdzić, czy rejestr został pomyślnie utworzony, wyświetl jego szczegóły przy użyciu get funkcji .

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

Korzystanie z biblioteki klienta płaszczyzny danych

Teraz, gdy mamy rejestr, należy wchodzić z nim w interakcje przy użyciu biblioteki klienta płaszczyzny danych (azure.confidentialledger).

Najpierw generujemy i zapisujemy poufny certyfikat rejestru.

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

Teraz możemy użyć certyfikatu sieciowego wraz z adresem URL rejestru i naszymi poświadczeniami, aby utworzyć poufnego klienta rejestru.

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

Jesteśmy gotowi napisać do księgi. Zrobimy to przy użyciu create_ledger_entry funkcji .

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

Funkcja print zwróci identyfikator transakcji zapisu do rejestru, który może służyć do pobrania komunikatu zapisanego w rejestrze.

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

Jeśli potrzebujesz najnowszej transakcji zatwierdzonej w rejestrze, możesz użyć get_current_ledger_entry funkcji .

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

Funkcja drukowania zwróci komunikat "Hello world!", ponieważ jest to komunikat w rejestrze, który odpowiada identyfikatorowi transakcji i jest najnowszą transakcją.

Pełny przykładowy kod

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

Ankieterzy

Jeśli chcesz poczekać, aż transakcja zapisu zostanie zatwierdzona w rejestrze, możesz użyć begin_create_ledger_entry funkcji . Spowoduje to zwrócenie poller czekać, aż wpis zostanie trwale zatwierdzony.

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

Wykonywanie zapytań względem starszej pozycji rejestru wymaga, aby rejestr odczytał wpis z dysku i zweryfikował go. Możesz użyć begin_get_ledger_entry funkcji , aby utworzyć poller, który będzie czekać, aż zapytanie wpis będzie w stanie gotowości do wyświetlenia.

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

Czyszczenie zasobów

Inne poufne artykuły rejestru platformy Azure mogą opierać się na tym przewodniku Szybki start. Jeśli planujesz korzystać z kolejnych przewodników Szybki start i samouczków, pozostaw te zasoby na swoim miejscu.

W przeciwnym razie po zakończeniu pracy z zasobami utworzonymi w tym artykule użyj polecenia az group delete interfejsu wiersza polecenia platformy Azure, aby usunąć grupę zasobów i wszystkie zawarte w niej zasoby:

az group delete --resource-group myResourceGroup

Następne kroki