Compartir a través de

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

Introducción a la biblioteca cliente del libro de contabilidad confidencial de Microsoft Azure para Python. Siga los pasos de este artículo para instalar el paquete y probar 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 de integridad de datos, como la inmutabilidad (haciendo que el libro de contabilidad solo se anexe) y la corrección de alteraciones (para asegurarse de que todos los registros se mantienen intactos).

Si no tiene una cuenta de Azure, cree una cuenta gratuita antes de comenzar.

Documentación de referencia de la API | Código fuente de la biblioteca | Biblioteca de gestión de paquetes de PyPI| Biblioteca cliente de paquetes de PyPI

Prerrequisitos

Configuración

En este 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 sus llamadas. Para más información, consulte Autenticación del cliente con la biblioteca cliente de Identidad de Azure.

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á y cargará una página de inicio de sesión de Azure. De lo contrario, visite https://aka.ms/devicelogin y escriba el código de autorización que se muestra en el terminal.

Si se le solicita, inicie sesión con sus credenciales de 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 identidad de Microsoft Entra:

pip install azure-identity

Instale la biblioteca cliente del plano de control del libro de contabilidad confidencial de Azure.

pip install azure.mgmt.confidentialledger

Instale la librería cliente del plano de datos de Azure Confidential Ledger.

pip install azure.confidentialledger

Creación de 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"

Registre el proveedor de recursos de 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 está completo con el comando az provider register de la CLI de Azure o el cmdlet Get-AzResourceProvider de Azure PowerShell.

az provider show --namespace "microsoft.ConfidentialLedger"

Creación de la aplicación de Python

Inicialización

Ahora podemos empezar a escribir nuestra 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

A continuación, use la clase DefaultAzureCredential para autenticar la aplicación.

credential = DefaultAzureCredential()

Finalice la instalación estableciendo algunas variables para usarlas en la aplicación: el grupo de recursos (myResourceGroup), el nombre del libro de contabilidad que desea crear y dos direcciones URL que usará la biblioteca cliente del plano de datos.

Importante

Cada libro de contabilidad debe tener un nombre único global. 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 obtención de los detalles de un libro de contabilidad específico.

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

confidential_ledger_mgmt = ConfidentialLedgerAPI(
    credential, subscription_id
)

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

Cree un properties diccionario con las claves y los valores siguientes 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 ha creado correctamente, vea sus detalles mediante la get función .

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, generamos y guardamos un certificado de libro de contabilidad confidencial.

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 libro de contabilidad confidencial.

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 create_ledger_entry función .

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

La función de impresión devolverá el identificador de transacción de la escritura en el registro, el cual se puede usar para recuperar el mensaje que escribiste en el registro.

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 de impresión devolverá "Hello world!", ya que es el mensaje del libro de contabilidad que corresponde al identificador de 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 esperará 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 de Azure Confidential Ledger pueden basarse 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 sus recursos contenidos:

az group delete --resource-group myResourceGroup

Pasos siguientes

  • Last updated on