Поделиться через

Быстрый старт: библиотека клиента конфиденциального реестра Microsoft Azure для Python

Начало работы с клиентской библиотекой конфиденциального реестра Microsoft Azure для Python. Выполните действия, описанные в этой статье, чтобы установить пакет и попробовать пример кода для основных задач.

Конфиденциальный реестр Microsoft Azure — это новая и высокозащищенная служба для управления записями конфиденциальных данных. На основе модели блокчейна с разрешениями, конфиденциальный реестр Azure предлагает уникальные преимущества в области целостности данных, такие как неизменяемость (добавление записей без возможности удаления) и защищенность от изменений (что гарантирует сохранение всех записей без изменений).

Если у вас нет аккаунта Azure, создайте бесплатную учетную запись перед началом.

Справочная документация по API | Исходный код библиотеки | Библиотека для управления пакетами (Python Package Index)| Клиентская библиотека для пакетов (Python Package Index)

Предпосылки

Настройка

В этом быстром старте используется библиотека идентификации Azure, а также Azure CLI и Azure PowerShell для аутентификации пользователей с использованием служб Azure. Разработчики также могут использовать Visual Studio или Visual Studio Code для проверки подлинности своих вызовов. Дополнительные сведения см. в статье "Проверка подлинности клиента с помощью клиентской библиотеки удостоверений Azure".

Вход в Azure

Войдите в Azure с помощью команды azure CLI az login или командлета Azure PowerShell Connect-AzAccount .

az login

Если интерфейс командной строки или PowerShell может открыть браузер по умолчанию, он будет выполнять это и загружать страницу входа в Azure. В противном случае посетите https://aka.ms/devicelogin и введите код авторизации, отображаемый в терминале.

При появлении запроса войдите с помощью учетных данных через браузер.

Установка пакетов

В терминале или в командной строке создайте подходящую папку проекта, а затем создайте и активируйте виртуальную среду Python, как описано в разделе Использование виртуальных окружений Python.

Установите клиентную библиотеку удостоверений Microsoft Entra:

pip install azure-identity

Установите клиентную библиотеку уровня управления конфиденциальным реестром Azure.

pip install azure.mgmt.confidentialledger

Установите клиентскую библиотеку для работы с данными конфиденциального реестра Azure.

pip install azure.confidentialledger

Создайте группу ресурсов

Группа ресурсов — это логический контейнер, в котором происходит развертывание ресурсов Azure и управление ими. Используйте команду Azure CLI az group create или командлет Azure PowerShell New-AzResourceGroup, чтобы создать группу ресурсов с названием myResourceGroup в регионе eastus.

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

Зарегистрируйте поставщик ресурсов microsoft.ConfidentialLedger

Поставщик ресурсов — это служба, которая предоставляет ресурсы Azure. Используйте команду azure CLI az provider register или командлет Azure PowerShell Register-AzResourceProvider , чтобы зарегистрировать поставщика ресурсов конфиденциального реестра Azure , microsoft. ConfidentialLedger'.

az provider register --namespace "microsoft.ConfidentialLedger"

Вы можете убедиться, что регистрация завершена с помощью команды azure CLI az provider register или командлета Azure PowerShell Get-AzResourceProvider .

az provider show --namespace "microsoft.ConfidentialLedger"

Создание приложения Python

Инициализация

Теперь мы можем приступить к написанию приложения Python. Сначала импортируйте необходимые пакеты.

# 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

Затем используйте класс DefaultAzureCredential для проверки подлинности приложения.

credential = DefaultAzureCredential()

Завершите настройку, задав некоторые переменные для использования в приложении: группу ресурсов (myResourceGroup), имя реестра, которую вы хотите создать, и два URL-адреса, которые будут использоваться клиентской библиотекой плоскости данных.

Это важно

Каждый реестр должен иметь глобально уникальное имя. Замените <your-unique-ledger-name> на имя вашего реестра в следующем примере.

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"

Использование клиентской библиотеки уровня управления

Клиентская библиотека уровня управления (azure.mgmt.confidentialledger) позволяет выполнять операции с реестрами, такими как создание, изменение, удаление, перечисление реестров, связанных с подпиской, и получение сведений о конкретном реестре.

В коде сначала создайте клиент плоскости управления, передав API ConfidentialLedger переменную учетных данных и идентификатор подписки Azure (оба из которых заданы выше).

confidential_ledger_mgmt = ConfidentialLedgerAPI(
    credential, subscription_id
)

Теперь мы можем создать реестр с помощью begin_create. Для begin_create функции требуются три параметра: группа ресурсов, имя реестра и объект properties.

properties Создайте словарь со следующими ключами и значениями и назначьте его переменной.

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

ledger_properties = ConfidentialLedger(**properties)

Теперь передайте группу ресурсов, имя реестра и объект свойств к begin_create.

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

Чтобы убедиться, что реестр был успешно создан, просмотрите его сведения с помощью 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}")

Использование клиентской библиотеки канала данных

Теперь, когда у нас есть реестр, взаимодействуйте с ним с помощью клиентской библиотеки плоскости данных (azure.confidentialledger).

Во-первых, мы создадим и сохраняем конфиденциальный сертификат реестра.

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

Теперь мы можем использовать сетевой сертификат вместе с URL-адресом реестра и нашими учетными данными для создания клиента конфиденциального реестра.

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

Мы готовы внести запись в бухгалтерскую книгу. Мы сделаем это с помощью create_ledger_entry функции.

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

Функция печати вернет идентификатор транзакции вашей записи в реестр, который можно использовать для получения сообщения, которое вы записали в реестр.

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

Если требуется только последняя транзакция, зафиксированная в реестре, можно использовать функцию 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']}")

Функция печати вернет сообщение "Hello world!", так как это сообщение в реестре, соответствующее идентификатору транзакции и являющееся последней транзакцией.

Полный пример кода

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

Опросчики

Если вы хотите дождаться фиксации транзакции записи в реестр, можно использовать функцию begin_create_ledger_entry . Это вернет опрашиватель, чтобы ждать, пока запись не будет надежно зафиксирована.

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

Для запроса записи в старой главной книге требуется, чтобы главная книга прочитала запись с диска и проверила её. Функцию можно использовать begin_get_ledger_entry для создания опрашителя, который будет ожидать, пока запрашиваемая запись находится в состоянии готовности к просмотру.

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

Очистите ресурсы

Другие статьи о Конфиденциальном реестре Azure могут быть основаны на этом кратком руководстве. Если вы планируете продолжить работу с последующими быстрыми стартами и руководствами, вы можете пожелать оставить эти ресурсы на месте.

В противном случае, когда вы завершите работу с ресурсами, созданными в этой статье, используйте команду Azure CLI az group delete для удаления группы ресурсов и всех его содержащихся ресурсов:

az group delete --resource-group myResourceGroup

Дальнейшие шаги