Inicio rápido: Biblioteca cliente de Microsoft Azure Confidential Ledger para Python

  • Artículo

Comience a usar la biblioteca cliente de Microsoft Azure Confidential Ledger para Python. Siga los pasos de este artículo para instalar el paquete y probar el código de ejemplo para tareas básicas.

Microsoft Azure Confidential Ledger es un servicio nuevo y muy seguro para administrar registros de datos confidenciales. En función de un modelo de cadena de bloques con permisos, Azure confidential ledger ofrece ventajas únicas para la integridad de datos, como la inmutabilidad (que hace que el libro de contabilidad sea de solo anexión) y la protección frente a alteraciones (para garantizar que todos los registros se mantienen intactos).

Si no tiene una suscripción a Azure, cree una cuenta gratuita de Azure antes de empezar.

Documentación de referencia de API | Código fuente de biblioteca | Biblioteca de administración de paquetes (índice de paquetes de Python)| Biblioteca cliente de paquetes (índice de paquetes de Python)

Requisitos previos

Configuración

En este artículo de inicio rápido se usa la biblioteca de identidades de Azure, junto con la CLI de Azure o Azure PowerShell, para autenticar al usuario en los servicios de Azure. Los desarrolladores también pueden usar Visual Studio o Visual Studio Code para autenticar las llamadas. Para más información, consulte Autenticación del cliente con la biblioteca cliente de Azure Identity.

Inicio de sesión en Azure

Inicie sesión en Azure mediante el comando az login de la CLI de Azure o el cmdlet Connect-AzAccount de Azure PowerShell.

az login

Si la CLI o PowerShell pueden abrir el explorador predeterminado, lo harán y cargarán una página de inicio de sesión de Azure. En caso contrario, visite https://aka.ms/devicelogin y escriba el código de autorización que se muestra en el terminal.

Si se le pide, inicie sesión con las credenciales de su cuenta en el explorador.

Instalación de los paquetes

En un símbolo del sistema o en un terminal, cree una carpeta de proyecto adecuada y, después, cree y active un entorno virtual de Python, como se describe en el apartado Uso de entornos virtuales de Python.

Instale la biblioteca cliente de Microsoft Entra:

pip install azure-identity

Instale la biblioteca cliente del plano de control de Azure Confidential Ledger.

pip install azure.mgmt.confidentialledger

Instale la biblioteca cliente del plano de datos de Azure Confidential Ledger.

pip install azure.confidentialledger

Crear un grupo de recursos

Un grupo de recursos es un contenedor lógico en el que se implementan y se administran los recursos de Azure. Use el comando az group create de la CLI de Azure o el cmdlet New-AzResourceGroup de Azure PowerShell para crear un grupo de recursos denominado myResourceGroup en la ubicación eastus.

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

Registro del proveedor de recursos microsoft.ConfidentialLedger

Un proveedor de recursos es un servicio que proporciona recursos de Azure. Use el comando az provider register de la CLI de Azure o el cmdlet Register-AzResourceProvider de Azure PowerShell para registrar el proveedor de recursos de Azure confidential ledger, "microsoft.ConfidentialLedger".

az provider register --namespace "microsoft.ConfidentialLedger"

Puede comprobar que el registro se ha completado con el comando de la CLI de Azure az provider register o el cmdlet de Azure PowerShell Get-AzResourceProvider.

az provider show --namespace "microsoft.ConfidentialLedger"

Creación de la aplicación de Python

Inicialización

Ahora, podemos empezar a escribir la aplicación de Python. En primer lugar, importe los paquetes necesarios.

# 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

Luego, use la clase DefaultAzureCredential para autenticar la aplicación.

credential = DefaultAzureCredential()

Para finalizar la configuración, establezca algunas variables para usar en la aplicación: el grupo de recursos (myResourceGroup), el nombre del libro de contabilidad que quiere crear y dos direcciones URL que usará la biblioteca cliente del plano de datos.

Importante

Cada libro de contabilidad debe tener un nombre único globalmente. Reemplace <your-unique-ledger-name> por el nombre del libro de contabilidad en el ejemplo siguiente.

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"

Uso de la biblioteca cliente del plano de control

La biblioteca cliente del plano de control (azure.mgmt.confidentialledger) permite operaciones en libros de contabilidad, como la creación, modificación, eliminación, enumeración de los libros de contabilidad asociados a una suscripción y la obtención de los detalles de un libro de contabilidad específico.

En el código, primero cree un cliente del plano de control pasando la variable de credencial ConfidentialLedgerAPI y el identificador de la suscripción de Azure (ambos se establecieron anteriormente).

confidential_ledger_mgmt = ConfidentialLedgerAPI(
    credential, subscription_id
)

Ahora podemos crear un libro de contabilidad mediante begin_create. La función begin_create requiere tres parámetros: el grupo de recursos, un nombre para el libro de contabilidad y un objeto "properties".

Cree un diccionario properties con las siguientes claves y valores, y asígnelo a una variable.

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

ledger_properties = ConfidentialLedger(**properties)

Ahora pase el grupo de recursos, el nombre del libro de contabilidad y el objeto properties a begin_create.

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

Para comprobar que el libro de contabilidad se creó correctamente, vea los detalles mediante la función 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}")

Uso de la biblioteca cliente del plano de datos

Ahora que tenemos un libro de contabilidad, interactúe con él mediante la biblioteca cliente del plano de datos (azure.confidentialledger).

En primer lugar, generaremos un certificado de confidential ledger y lo guardaremos.

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

Ahora podemos usar el certificado de red, junto con la dirección URL del libro de contabilidad y nuestras credenciales, para crear un cliente de Confidential Ledger.

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

Estamos preparados para escribir en el libro de contabilidad. Lo haremos mediante la función create_ledger_entry.

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

La función print devolverá el identificador de la transacción de la escritura en el libro de contabilidad, que se puede usar para recuperar el mensaje que escribió en el libro de contabilidad.

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 solo desea la transacción más reciente confirmada en el libro de contabilidad, puede usar la get_current_ledger_entry función.

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 función print devolverá "Hello world!", ya que es el mensaje del libro de contabilidad que corresponde al identificador de la transacción y es la transacción más reciente.

Código de ejemplo completo

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

Sondeos

Si desea esperar a que la transacción de escritura se confirme en el libro de contabilidad, puede usar la begin_create_ledger_entry función. Esto devolverá un sondeo para esperar hasta que la entrada se confirme de forma duradera.

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

La consulta de una entrada de libro de contabilidad anterior requiere que el libro de contabilidad lea la entrada del disco y la valide. Puede usar la begin_get_ledger_entry función para crear un sondeo que espere hasta que la entrada consultada esté en un estado listo para ver.

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

Limpieza de recursos

Otros artículos sobre Azure Confidential Ledger se pueden basar en este inicio rápido. Si tiene pensado seguir trabajando en otras guías de inicio rápido y tutoriales, considere la posibilidad de dejar estos recursos activos.

De lo contrario, cuando haya terminado con los recursos creados en este artículo, use el comando az group delete de la CLI de Azure para eliminar el grupo de recursos y todos los recursos que contiene:

az group delete --resource-group myResourceGroup

Pasos siguientes