Démarrage rapide : Bibliothèque de client de Registre confidentiel Microsoft Azure pour Python

  • Article

Prenez en main la bibliothèque de client de Registre confidentiel Microsoft Azure pour Python. Suivez les étapes décrites dans cet article pour installer le package et essayer l’exemple de code pour les tâches de base.

Registre confidentiel Microsoft Azure est un nouveau service, hautement sécurisé, pour la gestion des enregistrements de données sensibles. Sur la base d’un modèle de blockchain avec autorisations, le registre confidentiel Azure offre des avantages uniques en termes d’intégrité des données, tels que l’immuabilité (en permettant uniquement l’ajout au registre) et l’inviolabilité (pour garantir que tous les enregistrements sont conservés intacts).

Si vous n’avez pas d’abonnement Azure, créez un compte gratuit Azure avant de commencer.

Documentation de référence sur les API | Code source de la bibliothèque | Bibliothèque de gestion des packages (index de packages Python)| Bibliothèque cliente de packages (index de packages Python)

Prérequis

Configuration

Ce guide de démarrage rapide utilise la bibliothèque Azure Identity ainsi qu’Azure CLI ou PowerShell pour authentifier l’utilisateur auprès des services Azure. Les développeurs peuvent également utiliser Visual Studio ou Visual Studio Code pour authentifier leurs appels. Pour plus d’informations, consultez Authentifier le client avec la bibliothèque cliente Azure Identity.

Connexion à Azure

Connectez-vous à Azure à l’aide de la commande Azure CLI az login ou de la cmdlet Azure PowerShell Connect-AzAccount.

az login

Si Azure CLI ou PowerShell peut ouvrir votre navigateur par défaut, il le fait et charge une page de connexion Azure. Sinon, visitez https://aka.ms/devicelogin et entrez le code d’autorisation affiché dans votre terminal.

Si on vous le demande, connectez-vous ensuite avec les informations d’identification de votre compte dans le navigateur.

Installer les packages

Dans un terminal ou une invite de commandes, créez un dossier de projet approprié, puis créez et activez un environnement virtuel Python comme décrit dans Utiliser des environnements virtuels Python.

Installez la bibliothèque de client d’identité Microsoft Entra :

pip install azure-identity

Installez la bibliothèque de client du plan de contrôle de Registre confidentiel.

pip install azure.mgmt.confidentialledger

Installez la bibliothèque de client du plan de données de Registre confidentiel.

pip install azure.confidentialledger

Créer un groupe de ressources

Un groupe de ressources est un conteneur logique dans lequel les ressources Azure sont déployées et gérées. Utilisez la commande Azure CLI az group create ou l’applet de commande Azure PowerShell New-AzResourceGroup pour créer un groupe de ressources nommé myResourceGroup à l’emplacement eastus.

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

Inscrivez le fournisseur de ressources microsoft.ConfidentialLedger

Un fournisseur de ressources est un service qui fournit des ressources Azure. Utilisez la commande Azure CLI az provider register ou l’applet de commande Azure PowerShell Register-AzResourceProvider pour inscrire le fournisseur de ressources du registre confidentiel Azure, « microsoft.ConfidentialLedger ».

az provider register --namespace "microsoft.ConfidentialLedger"

Vous pouvez vérifier que l’inscription est terminée avec la commande Azure CLI az provider register ou l’applet de commande Azure PowerShell Get-AzResourceProvider.

az provider show --namespace "microsoft.ConfidentialLedger"

Créer votre application Python

Initialisation

Nous pouvons maintenant commencer à écrire notre application Python. Commencez par importer les packages requis.

# 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

Ensuite, utilisez la classe DefaultAzureCredential pour authentifier l’application.

credential = DefaultAzureCredential()

Terminez l’installation en définissant certaines variables à utiliser dans votre application : le groupe de ressources (myResourceGroup), le nom du registre que vous souhaitez créer et deux URL à utiliser par la bibliothèque cliente du plan de données.

Important

Chaque registre doit avoir un nom globalement unique. Remplacez <your-unique-ledger-name> par le nom de votre registre dans l’exemple suivant.

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"

Utiliser la bibliothèque cliente du plan de contrôle

La bibliothèque cliente du plan de contrôle (azure.mgmt.confidentialledger) autorise des opérations sur les registres, comme la création, la modification, la suppression, l’énumération des registres associés à un abonnement et l’obtention des détails d’un registre spécifique.

Dans le code, commencez par créer un client de plan de contrôle en transmettant à ConfidentialLedgerAPI la variable d’identification et votre ID d’abonnement Azure (les deux étant définis ci-dessus).

confidential_ledger_mgmt = ConfidentialLedgerAPI(
    credential, subscription_id
)

Nous pouvons maintenant créer un registre à l’aide de begin_create. La fonction begin_create requiert trois paramètres : votre groupe de ressources, un nom pour le registre et un objet « properties ».

Créez un dictionnaire properties avec les clés et les valeurs suivantes et affectez-le à une variable.

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

ledger_properties = ConfidentialLedger(**properties)

À présent, transmettez le groupe de ressources, le nom de votre registre et l’objet properties à begin_create.

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

Pour vérifier que votre compte a été créé avec succès, affichez ses détails à l’aide de la fonction 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}")

Utiliser la bibliothèque cliente du plan de données

Maintenant que vous disposez d’un registre, interagissez avec lui à l’aide de la bibliothèque cliente du plan de données (azure.confidentialledger).

Tout d’abord, nous générons et enregistrons un certificat de registre confidentiel.

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

Nous pouvons maintenant utiliser le certificat réseau, ainsi que l’URL du registre et nos informations d’identification, pour créer un client de registre confidentiel.

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

Nous sommes prêts à écrire dans le registre. Nous allons le faire à l’aide de la fonction create_ledger_entry.

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

La fonction print renvoie l’ID de transaction de votre écriture dans le registre, qui peut être utilisé pour récupérer le message que vous avez écrit dans le registre.

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

Si vous souhaitez simplement la dernière transaction qui a été validée dans le registre, vous pouvez utiliser la fonction 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']}")

La fonction d’impression retourne « Hello world! », car c’est le message figurant dans le registre qui correspond à l’ID de transaction et c’est la dernière transaction.

Exemple de code complet

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

Observateurs

Si vous souhaitez attendre que votre transaction d’écriture soit validée dans votre registre, vous pouvez utiliser la fonction begin_create_ledger_entry. Cela retourne un observateur pour attendre que l’entrée soit validée durablement.

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

L’interrogation d’une entrée de registre plus ancienne nécessite que le registre lise l’entrée à partir du disque et la valide. Vous pouvez utiliser la fonction begin_get_ledger_entry afin de créer un observateur qui attend que l’entrée interrogée soit dans l’état Prêt pour être consultée.

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

Nettoyer les ressources

D’autres articles relatifs à Registre confidentiel Azure peuvent se baser sur ce démarrage rapide. Si vous prévoyez d’utiliser d’autres démarrages rapides et didacticiels, il peut être utile de conserver ces ressources.

Sinon, quand vous en avez terminé avec les ressources créées dans cet article, utilisez la commande Azure CLI az group delete pour supprimer le groupe de ressources et toutes les ressources qu’il contient :

az group delete --resource-group myResourceGroup

Étapes suivantes