Краткое руководство. Клиентская библиотека Конфиденциального реестра Microsoft Azure для Python

  • Статья

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

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

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

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

Необходимые компоненты

Настройка

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

Вход в Azure

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

az login

Если в CLI или 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-адреса, которые будут использоваться клиентской библиотекой плоскости данных.

Важно!

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

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) позволяет выполнять операции с реестрами, такими как создание, изменение, удаление, перечисление реестров, связанных с подпиской, и получение сведений о конкретном реестре.

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

confidential_ledger_mgmt = ConfidentialLedgerAPI(
    credential, subscription_id
)

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

Создайте словарь 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

Следующие шаги