Share via

التشغيل السريع - مكتبة عميل Microsoft Azure confidential ledger لـ Python

  • مقالة

ابدأ بمكتبة عميل Microsoft Azure Confidential Ledger لـ Python. اتبع الخطوات الواردة في هذه المقالة لتثبيت الحزمة وتجربة مثال التعليمات البرمجية للمهام الأساسية.

Microsoft Azure confidential ledger خدمة جديدة وآمنة للغاية لإدارة سجلات البيانات الحساسة. استنادا إلى نموذج سلسلة السجلات المعتمد، يقدم دفتر الأستاذ السري من Azure مزايا فريدة لسلامة البيانات، مثل عدم قابلية التغيير (جعل دفتر الأستاذ ملحقا فقط) والتدقيق على العبث (لضمان الحفاظ على جميع السجلات سليمة).

إذا لم يكن لديك اشتراك في Azure، فأنشئ حساب Azure مجاني قبل أن تبدأ.

وثائق مرجع API | التعليمة البرمجية المصدر للمكتبة | مكتبة إدارة (فهرس حزمة Python) الحزمة| مكتبة عميل (فهرس حزمة Python) الحزمة

المتطلبات الأساسية

الإعداد

يُستخدم هذا التشغيل السريع مكتبة Azure Identity مع Azure CLI أو Azure PowerShell، لمصادقة المستخدم إلى Azure Services. يمكن للمُطورين أيضاً استخدام Visual Studio أو Visual Studio Code لمصادقة استدعاءاتهم. لمزيد من المعلومات، راجع مصادقة العميل مع مكتبة عميل Azure Identity.

تسجيل الدخول إلى Azure

سجل الدخول إلى Azure باستخدام الأمر تسجيل الدخول إلى Azure CLI az أو Azure PowerShell Connect-AzAccount cmdlet.

az login

إذا كان CLI أو PowerShell بإمكانهما فتح المستعرض الافتراضي الخاص بك، فسيتم القيام بذلك وتحميل صفحة تسجيل الدخول إلى Azure. وإلا، افتح صفحة مستعرض في https://aka.ms/devicelogin وأدخِل رمز التفويض المعروض في الواجهة الطرفية الخاصة بك.

إذا طُلب منك ذلك، فقم بتسجيل الدخول باستخدام بيانات اعتماد حسابك في المستعرض.

قم بتثبيت الحِزَم

في terminal أو موجه الأوامر، بادر بإنشاء مجلد مشروع مناسب، ثم بادر بإنشاء بيئة 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 cmdlet لإنشاء مجموعة موارد باسم myResourceGroup في موقع الشرق .

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

تسجيل موفر مورد microsoft.ConfidentialLedger

يُعد موفر الموارد هو خدمة توفر موارد Azure. استخدم الأمر Azure CLI az provider register أو Azure PowerShell Register-AzResourceProvider cmdlet لتسجيل موفر موارد دفتر الأستاذ السري Azure، 'microsoft. ConfidentialLedger'.

az provider register --namespace "microsoft.ConfidentialLedger"

يمكنك التحقق من اكتمال التسجيل باستخدام الأمر Azure CLI az provider register أو Azure PowerShell Get-AzResourceProvider cmdlet.

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) بالعمليات على دفاتر الأستاذ، مثل الإنشاء والتعديل والحذف وإدراج دفاتر الأستاذ المقترنة باشتراك والحصول على تفاصيل دفتر الأستاذ المحدد.

في التعليمات البرمجية، قم أولا بإنشاء عميل وحدة تحكم عن طريق تمرير ConfidentialLedgerAPI متغير بيانات الاعتماد ومعرف اشتراك 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'])

الآن يمكننا استخدام شهادة الشبكة، جنبًا إلى جنب مع عنوان ويب دفتر الأستاذ وبيانات اعتمادنا، لإنشاء عميل دفتر الأستاذ السري.

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 الأخرى على هذه البداية السريعة. إذا كنت تخطط لمواصلة العمل مع الخطوات السريعة والبرامج التعليمية اللاحقة، فقد ترغب في ترك هذه الموارد في مكانها.

في حالة عدم حدوث ذلك، عندما تنتهي من الموارد التي جرى إنشاؤها في هذه المقالة، استخدم أمرحذف مجموعة az لـ Azure CLI لحذف مجموعة الموارد وجميع الموارد المضمنة بها:

az group delete --resource-group myResourceGroup

الخطوات التالية