빠른 시작: Python용 Microsoft Azure 기밀 원장 클라이언트 라이브러리

아티클
08/10/2024

Python용 Microsoft Azure 기밀 원장 클라이언트 라이브러리를 시작합니다. 이 문서의 단계를 따라 패키지를 설치하고 기본 작업에 대한 예제 코드를 사용해 봅니다.

Microsoft Azure 기밀 원장은 중요한 데이터 레코드를 관리하는 데 사용하는 매우 안전한 새로운 서비스입니다. 권한 있는 블록체인 모델을 기반으로 하는 Azure 기밀 원장은 불변성(원장을 추가 전용으로 만듦) 및 변조 방지(모든 레코드가 그대로 유지되도록)와 같은 고유한 데이터 무결성 이점을 제공합니다.

Azure를 구독하고 있지 않다면 시작하기 전에 Azure 체험 계정을 만듭니다.

API 참조 설명서 | 라이브러리 소스 코드 | 패키지(Python 패키지 인덱스) 관리 라이브러리| 패키지(Python 패키지 인덱스) 클라이언트 라이브러리

필수 조건

Azure 구독 - 체험 구독 만들기 - 구독 소유자 - Azure 구독에 대한 소유자 권한이 있는 사용자만 Confidential Ledger를 만들 수 있습니다. 이 빠른 시작을 계속하기 전에 적절한 액세스 권한이 있는지 확인합니다.
Python용 Azure SDK에서 지원되는 Python 버전입니다.
Azure CLI 또는 Azure PowerShell.

설정

이 빠른 시작에서는 Azure CLI 또는 Azure PowerShell과 함께 Azure ID 라이브러리를 사용하여 사용자를 Azure Services에 인증합니다. 개발자는 Visual Studio 또는 Visual Studio Code를 사용하여 해당 호출을 인증할 수도 있습니다. 자세한 내용은 Azure ID 클라이언트 라이브러리를 사용하여 클라이언트 인증을 참조하세요.

Azure CLI az login 명령 또는 Azure PowerShell Connect-AzAccount cmdlet을 사용하여 Azure에 로그인합니다.

Azure CLI
Azure PowerShell

az login

Connect-AzAccount

CLI 또는 PowerShell이 기본 브라우저를 열 수 있는 경우 기본 브라우저를 열고 Azure 로그인 페이지를 로드합니다. 그렇지 않으면 https://aka.ms/devicelogin을 방문하여 터미널에 표시된 인증 코드를 입력합니다.

메시지가 표시되면 브라우저에서 계정 자격 증명으로 로그인합니다.

패키지 설치

터미널 또는 명령 프롬프트에서 적절한 프로젝트 폴더를 만든 다음, Python 가상 환경 사용에 설명된 대로 Python 가상 환경을 만들고 활성화합니다.

Microsoft Entra ID 클라이언트 라이브러리를 설치합니다.

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 cmdlet을 사용하여 eastus 위치에 myResourceGroup이라는 리소스 그룹을 만듭니다.

Azure CLI
Azure PowerShell

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

New-AzResourceGroup -Name myResourceGroup -Location eastus

microsoft.ConfidentialLedger 리소스 공급자 등록

리소스 공급자는 Azure 리소스를 제공하는 서비스입니다. Azure CLI az provider register 명령 또는 Azure PowerShell Register-AzResourceProvider cmdlet을 사용하여 Azure confidential ledger 리소스 공급자인 'microsoft.ConfidentialLedger'를 등록합니다.

Azure CLI
Azure PowerShell

az provider register --namespace "microsoft.ConfidentialLedger"

Register-AzResourceProvider -ProviderNamespace "microsoft.ConfidentialLedger"

Azure CLI az provider register 명령 또는 Azure PowerShell Get-AzResourceProvider cmdlet을 통해 등록이 완료되었는지 확인할 수 있습니다.

Azure CLI
Azure PowerShell

az provider show --namespace "microsoft.ConfidentialLedger"

Get-AzResourceProvider -ProviderNamespace "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을 설정합니다.

Important

각 원장에는 전역적으로 고유한 이름이 있어야 합니다. 다음 예제에서는 <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)를 사용하면 원장에서 생성, 수정 및 삭제와 같은 작업을 수행하고, 구독과 연결된 원장을 나열하고, 특정 원장의 세부 정보를 가져올 수 있습니다.

코드에서는 먼저 ConfidentialLedgerAPI 자격 증명 변수와 Azure 구독 ID(둘 다 위에 설정됨)를 전달하여 컨트롤 플레인 클라이언트를 만듭니다.

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)를 사용하여 원장과 상호 작용합니다.

먼저 Confidential Ledger 인증서를 생성하고 저장합니다.

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

인쇄 함수는 원장에 쓴 트랜잭션 ID를 원장에 반환합니다. 이 ID는 원장에 쓴 메시지를 검색하는 데 사용할 수 있습니다.

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

인쇄 함수는 트랜잭션 ID에 해당하고 가장 최근 트랜잭션인 원장의 메시지인 "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

다음을 통해 공유