Início Rápido: Biblioteca de clientes do Razão Confidencial do Microsoft Azure para Python

  • Artigo

Introdução à biblioteca de clientes do Razão Confidencial do Microsoft Azure para Python. Neste artigo, você vai seguir as etapas para instalar o pacote e testar o código de exemplo para tarefas básicas.

O Razão Confidencial do Microsoft Azure é um serviço novo e altamente seguro para gerenciar registros de dados confidenciais. Baseado em um modelo de blockchain com permissão, o razão confidencial do Azure oferece vantagens exclusivas de integridade de dados, como imutabilidade (tornando o razão somente de acréscimo) e proteção contra adulteração (para garantir que todos os registros sejam mantidos intactos).

Caso você não tenha uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar.

Documentação de referência da API | Código-fonte da biblioteca | Biblioteca de Gerenciamento de Pacotes (Índice de Pacote Python)| Biblioteca de Clientes de Pacotes (Índice de Pacote Python)

Pré-requisitos

Configuração

Este guia de início rápido usa a biblioteca da Identidade do Azure com a CLI do Azure ou o Azure PowerShell para autenticar usuários nos serviços do Azure. Os desenvolvedores também podem usar o Visual Studio ou o Visual Studio Code para autenticar as chamadas. Para obter mais informações, confira Autenticar o cliente com a biblioteca de clientes da Identidade do Azure.

Entrar no Azure

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

az login

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

Se solicitado, entre com suas credenciais de conta no navegador.

Instalar os pacotes

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

Instale a biblioteca de clientes de identidade do Microsoft Entra:

pip install azure-identity

Instale a biblioteca de clientes do painel de controle do Razão Confidencial do Azure.

pip install azure.mgmt.confidentialledger

Instale a biblioteca de clientes do plano de dados do 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 cmdlet az group create da CLI do Azure ou o cmdlet New-AzResourceGroup do Azure PowerShell para criar um grupo de recursos chamado myResourceGroup na localização eastus.

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

Registrar o provedor de recursos microsoft.ConfidentialLedger

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

az provider register --namespace "microsoft.ConfidentialLedger"

Você pode verificar se o registro foi concluído com o comando az provider register da CLI do Azure ou com o cmdlet Get-AzResourceProvider do Azure PowerShell.

az provider show --namespace "microsoft.ConfidentialLedger"

Criar 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 no 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 clientes do plano de dados.

Importante

Cada razão precisa ter um nome globalmente exclusivo. Substitua o <nome-do razão-exclusivo> pelo nome do seu 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 clientes do painel de controle

A biblioteca de clientes do painel de controle (azure.mgmt.confidentialledger) permite operações em razões, como criação, modificação e exclusão, listando os razões associados a uma assinatura e obtendo os detalhes de um razão específico.

No código, primeiro crie um cliente de plano de controle passando à ConfidentialLedgerAPI 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 razão usando begin_create. A função begin_create exige três parâmetros: seu grupo de recursos, um nome para o razão e um objeto "properties".

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

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

ledger_properties = ConfidentialLedger(**properties)

Agora, transmita o grupo de recursos, o nome do 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 razão foi criado com êxito, veja os detalhes dele 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}")

Usar a biblioteca de clientes do plano de dados

Agora que temos um razão, interagiremos com ele usando a biblioteca de clientes do plano de dados (azure.confidentialledger).

Primeiro, geramos e salvamos um certificado do razão 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 razão e nossas credenciais, para criar um cliente do Razão Confidencial.

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

Estamos preparados para gravar dados no razão. Faremos isso usando a função create_ledger_entry.

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

A função print retornará a ID da transação da gravação para o razão, que pode ser usada para recuperar a mensagem que você gravou no 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 confirmada no razão, use 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 print retornará "Olá, Mundo!", pois essa é a mensagem no razão que corresponde à 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']}")

Instrumentos de sondagem

Se você quiser aguardar a confirmação da transação de gravação no razão, use a função begin_create_ledger_entry. Isso retornará um instrumento de sondagem para aguardar até que a entrada seja confirmada de modo durável.

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

A consulta de uma entrada mais antiga no razão requer que o razão leia a entrada do disco e valide-a. Você pode usar a função begin_get_ledger_entry para criar um instrumento de sondagem que aguardará até que a entrada consultada esteja em um estado pronto para exibição.

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

Limpar os recursos

Outros artigos do Razão Confidencial do Azure podem se basear neste guia de início rápido. Se você planeja continuar a trabalhar com os tutoriais e inícios rápidos subsequentes, deixe esses recursos onde estão.

Caso contrário, quando tiver concluído os recursos criados neste artigo, use o comando az group delete da CLI do Azure para excluir o grupo de recursos e todos os recursos que ele contém:

az group delete --resource-group myResourceGroup

Próximas etapas