Compartilhar via

Guia de Início Rápido: Biblioteca Cliente do Ledger Confidencial do Microsoft Azure para Python

Introdução à biblioteca de clientes do 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. 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).

Se você ainda 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 (Índice de Pacotes do Python)| Biblioteca de clientes do pacote (Índice de Pacotes do Python)

Pré-requisitos

Configuração

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 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 seu navegador padrão, ele o fará 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 em seu 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, em seguida, 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 comando az group create da CLI do Azure ou o cmdlet PowerShell do Azure New-AzResourceGroup para criar um grupo de recursos chamado myResourceGroup na regiã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 livro-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 de registro do provedor az 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 DefaultAzureCredential Class 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 o 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 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, 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 registro foi criado com êxito, exiba 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}")

Usar a biblioteca cliente do plano de dados

Agora que temos um ledger, interaja 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
)

Temos tudo preparado para gravar dados no 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 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.

Exemplo de código 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 exige 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 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 terminar de usar 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 contidos:

az group delete --resource-group myResourceGroup

Próximas etapas

  • Last updated on