Guia de início rápido: biblioteca de cliente de livro-razão confidencial do Microsoft Azure para Python

  • Artigo

Introdução à biblioteca de cliente de livro-razão confidencial do Microsoft Azure para Python. Siga as etapas neste artigo para instalar o pacote e experimentar o código de exemplo para tarefas básicas.

O livro razão confidencial do Microsoft Azure é um serviço novo e altamente seguro para gerenciar registros de dados confidenciais. Com base em um modelo de blockchain com permissão, o livro-razão confidencial do Azure oferece vantagens exclusivas de integridade de dados, como imutabilidade (tornando o livro-razão somente anexo) e inviolabilidade (para garantir que todos os registros sejam mantidos intactos).

Se não tiver uma subscrição do Azure, crie uma conta gratuita do Azure antes de começar.

Documentação | de referência da API Pacote de código-fonte | da biblioteca (Python Package Index) Pacote de biblioteca| de gerenciamento (Python Package Index) Biblioteca de cliente

Pré-requisitos

Configurar

Este início rápido usa a biblioteca de Identidade do Azure, juntamente com a CLI do Azure ou o Azure PowerShell, para autenticar o usuário nos Serviços do Azure. Os desenvolvedores também podem usar o Visual Studio ou o Visual Studio Code para autenticar suas chamadas. Para obter mais informações, consulte Autenticar o cliente com a biblioteca de cliente do Azure Identity.

Iniciar sessão no Azure

Entre no Azure usando o comando azur CLI az login do Azure ou o cmdlet Azure PowerShell Connect-AzAccount .

az login

Se a CLI ou o PowerShell puder abrir seu navegador padrão, ele fará isso e carregará uma página de entrada do Azure. Caso contrário, visite https://aka.ms/devicelogin e insira o código de autorização exibido no seu terminal.

Se solicitado, inicie sessão com as credenciais da sua conta no browser.

Instalar os pacotes

Em um terminal ou prompt de comando, crie uma pasta de projeto adequada e, em seguida, crie e ative um ambiente virtual Python conforme descrito em Usar ambientes virtuais Python.

Instale a biblioteca de cliente de identidade do Microsoft Entra:

pip install azure-identity

Instale a biblioteca de cliente do plano de controle de razão confidencial do Azure.

pip install azure.mgmt.confidentialledger

Instale a biblioteca de cliente do plano de dados do livro-razão confidencial do Azure.

pip install azure.confidentialledger

Criar um grupo de recursos

Um grupo de recursos é um contentor lógico no qual os recursos do Azure são implementados e geridos. Use o comando azur group create da CLI do Azure ou o cmdlet New-AzResourceGroup do Azure PowerShell para criar um grupo de recursos chamado myResourceGroup no local eastus.

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

Registre o microsoft. Provedor de recursos ConfidentialLedger

Um provedor de recursos é um serviço que fornece recursos do Azure. Use o comando Azure CLI az provider register ou o cmdlet Azure PowerShell Register-AzResourceProvider para registrar o provedor de recursos de contabilidade confidencial do Azure, 'microsoft. ConfidentialLedger».

az provider register --namespace "microsoft.ConfidentialLedger"

Você pode verificar se o registro está completo com o comando Azure CLI az provider register ou o cmdlet Get-AzResourceProvider do Azure PowerShell.

az provider show --namespace "microsoft.ConfidentialLedger"

Crie seu aplicativo Python

Inicialização

Agora podemos começar a escrever nosso aplicativo Python. Primeiro, importe os pacotes necessários.

# 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

Em seguida, use a classe DefaultAzureCredential para autenticar o aplicativo.

credential = DefaultAzureCredential()

Conclua a configuração definindo algumas variáveis para uso em seu aplicativo: o grupo de recursos (myResourceGroup), o nome do razão que você deseja criar e duas urls a serem usadas pela biblioteca de cliente do plano de dados.

Importante

Cada livro razão deve ter um nome globalmente exclusivo. Substitua <seu-nome-livro-razão exclusivo pelo nome do seu livro-razão> no exemplo a seguir.

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"

Usar a biblioteca de cliente do plano de controle

A biblioteca de cliente do plano de controle (azure.mgmt.confidentialledger) permite operações em livros-razão, como criação, modificação, exclusão, listagem dos livros associados a uma assinatura e obtenção dos detalhes de um livro-razão específico.

No código, primeiro crie um cliente de plano de controle passando a API ConfidentialLedger, a variável de credencial e sua ID de assinatura do Azure (ambas definidas acima).

confidential_ledger_mgmt = ConfidentialLedgerAPI(
    credential, subscription_id
)

Agora podemos criar um livro-razão usando begin_createo . A begin_create função requer três parâmetros: seu grupo de recursos, um nome para o livro-razão e um objeto "propriedades".

Crie um properties dicionário com as seguintes chaves e valores e atribua-o a uma variável.

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

ledger_properties = ConfidentialLedger(**properties)

Agora passe o grupo de recursos, o nome do seu livro razão e o objeto de propriedades para begin_create.

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

Para verificar se o livro razão foi criado com êxito, visualize seus detalhes usando a get função.

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

Usar a biblioteca de cliente do plano de dados

Agora que temos um livro-razão, interaja com ele usando a biblioteca de cliente do plano de dados (azure.confidentialledger).

Primeiro, geramos e salvamos um certificado de contabilidade 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'])

Agora podemos usar o certificado de rede, juntamente com a URL do livro-razão e nossas credenciais, para criar um cliente de contabilidade confidencial.

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

Estamos preparados para escrever no livro-razão. Faremos isso usando a create_ledger_entry função.

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

A função de impressão retornará o ID da transação de sua gravação para o livro-razão, que pode ser usado para recuperar a mensagem que você escreveu no livro-razão.

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

Se você quiser apenas a transação mais recente que foi confirmada no livro-razão, você pode usar a get_current_ledger_entry função.

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

A função de impressão retornará "Olá mundo!", pois essa é a mensagem no livro razão que corresponde ao ID da transação e é a transação mais recente.

Código de exemplo 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']}")

Sondagens

Se você quiser esperar que sua transação de gravação seja confirmada em seu livro-razão, você pode usar a begin_create_ledger_entry função. Isso retornará um poller para esperar até que a entrada seja comprometida de forma duradoura.

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

Consultar uma entrada de razão mais antiga requer que o razão leia a entrada do disco e a valide. Você pode usar a begin_get_ledger_entry função para criar um poller que aguardará até que a entrada consultada esteja em um estado pronto para visualização.

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

Clean up resources (Limpar recursos)

Outros artigos do livro-razão confidencial do Azure podem se basear neste início rápido. Se quiser continuar a trabalhar com os inícios rápidos e tutoriais subsequentes, pode manter estes recursos.

Caso contrário, quando terminar os recursos criados neste artigo, use o comando azur CLI az group delete para excluir o grupo de recursos e todos os recursos contidos:

az group delete --resource-group myResourceGroup

Próximos passos