Partilhar via

Introdução rápida: biblioteca de cliente de diário confidencial do Microsoft Azure para Python

Comece a utilizar a biblioteca de cliente de registro 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 ledger confidencial do Microsoft Azure é um serviço novo e altamente seguro para gerir registos 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 conta do Azure, crie uma conta gratuita antes de começar.

Documentação de referência da API | Código fonte da biblioteca | Biblioteca de Gerenciamento de Pacotes (Python Package Index)| Biblioteca de cliente de pacotes (Python Package Index)

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 Azure Identity.

Iniciar sessão no Azure

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

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 contêiner lógico no qual os recursos do Azure são implantados e gerenciados. Use o comando az group create da Azure CLI ou o cmdlet New-AzResourceGroup do Azure PowerShell para criar um grupo de recursos chamado myResourceGroup na região eastus.

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

Registe o fornecedor de recursos microsoft.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 <o-nome-exclusivo-do-seu-livro-razão> 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_create. A função begin_create requer três parâmetros: o 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-geral 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 os seus detalhes usando a função 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}")

Utilizar a biblioteca de clientes do plano de dados

Uma vez que temos um livro-razão, interaja com ele usando a biblioteca 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 de contabilidade. 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 'print' retornará o ID da transação da sua gravação no ledger, que pode ser usado para recuperar a mensagem que escreveu no ledger.

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 quiseres apenas a transacção mais recente que foi confirmada no livro-razão, podes usar a função 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']}")

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 última transação.

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 pretender esperar que a sua transação de escrita seja confirmada no seu livro de registos, pode usar a função begin_create_ledger_entry. 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 no livro-razão mais antiga requer que o livro-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()

Limpeza de recursos

Outros artigos do livro-razão confidencial do Azure podem se basear neste início rápido. Se pretende continuar a trabalhar com os quickstarts e tutoriais subsequentes, poderá querer deixar estes recursos no lugar.

Depois, quando terminar de utilizar os recursos criados neste artigo, use o comando Azure CLI az group delete para eliminar o grupo de recursos e todos os recursos incluídos:

az group delete --resource-group myResourceGroup

Próximos passos