Pustaka klien Azure Digital Twins Core untuk Python - versi 1.2.0

Artikel
04/05/2023

Paket ini berisi SDK untuk Azure Digital Twins API untuk menyediakan akses ke layanan Azure Digital Twins untuk mengelola kembar, model, hubungan, dll.

Pengelakan

Dukungan paket Azure SDK Python untuk Python 2.7 telah berakhir 01 Januari 2022. Untuk informasi lebih lanjut dan pertanyaan, silakan merujuk ke https://github.com/Azure/azure-sdk-for-python/issues/20691

Memulai

Pengantar

Azure Digital Twins adalah platform pengembang untuk solusi IoT generasi berikutnya yang memungkinkan Anda membuat, menjalankan, dan mengelola representasi digital lingkungan bisnis Anda, dengan aman dan efisien di cloud. Dengan Azure Digital Twins, membuat representasi status operasional langsung cepat dan hemat biaya, dan representasi digital tetap terkini dengan data real-time dari IoT dan sumber data lainnya. Jika Anda baru menggunakan Azure Digital Twins dan ingin mempelajari selengkapnya tentang platform ini, pastikan Anda memeriksa halaman dokumentasi resmi Azure Digital Twins.

Untuk pengenalan tentang cara memprogram terhadap layanan Azure Digital Twins, kunjungi halaman tutorial pengodean untuk panduan langkah demi langkah yang mudah. Kunjungi tutorial ini untuk mempelajari cara berinteraksi dengan instans Azure Digital Twin menggunakan aplikasi klien baris perintah. Terakhir, untuk panduan cepat tentang cara membangun solusi Azure Digital Twins end-to-end yang didorong oleh data langsung dari lingkungan Anda, pastikan Anda memeriksa panduan bermanfaat ini.

Panduan yang disebutkan di atas dapat membantu Anda memulai elemen kunci Azure Digital Twins, seperti membuat instans Azure Digital Twins, model, grafik kembar, dll. Gunakan panduan sampel ini di bawah ini untuk membiasakan diri dengan berbagai API yang membantu Anda memprogram terhadap Azure Digital Twins.

Cara memasang

Instal [azure-digitaltwins-core][pypi_package_keys] dan azure-identity dengan pip:

pip install azure-digitaltwins-core azure-identity

azure-identity digunakan untuk autentikasi Azure Active Directory seperti yang ditunjukkan di bawah ini.

Cara menggunakan

Autentikasi, izin

Untuk membuat klien digital twins baru, Anda memerlukan titik akhir ke instans dan kredensial Azure Digital Twin. Untuk sampel di bawah ini, AZURE_URLvariabel lingkungan , AZURE_TENANT_ID, AZURE_CLIENT_ID, dan AZURE_CLIENT_SECRET harus diatur. Klien memerlukan instans TokenCredential atau ServiceClientCredentials. Dalam sampel ini, kami menggambarkan cara menggunakan satu kelas turunan: DefaultAzureCredentials.

Catatan: Untuk mengakses bidang data untuk layanan Digital Twins, entitas harus diberi izin. Untuk melakukan ini, gunakan perintah Azure CLI: az dt rbac assign-role --assignee '<user-email | application-id>' --role owner -n '<your-digital-twins-instance>'

DefaultAzureCredential mendukung mekanisme autentikasi yang berbeda dan menentukan jenis kredensial yang sesuai berdasarkan lingkungan tempatnya dijalankan. Ini mencoba menggunakan beberapa jenis kredensial dalam urutan hingga menemukan kredensial yang berfungsi.

Kode sampel

# DefaultAzureCredential supports different authentication mechanisms and determines the appropriate credential type based of the environment it is executing in.
# It attempts to use multiple credential types in an order until it finds a working credential.

# - AZURE_URL: The URL to the ADT in Azure
url = os.getenv("AZURE_URL")

# DefaultAzureCredential expects the following three environment variables:
# - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
# - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
# - AZURE_CLIENT_SECRET: The client secret for the registered application
credential = DefaultAzureCredential()
service_client = DigitalTwinsClient(url, credential)

Konsep utama

Azure Digital Twins adalah layanan Azure IoT yang menciptakan model komprehensif lingkungan fisik. Ini dapat membuat grafik kecerdasan spasial untuk memodelkan hubungan dan interaksi antara orang, spasi, dan perangkat. Anda dapat mempelajari selengkapnya tentang Azure Digital Twins dengan mengunjungi Dokumentasi Azure Digital Twins.

Contoh

Anda dapat menjelajahi API digital twins (menggunakan pustaka klien) menggunakan proyek sampel.

Proyek sampel menunjukkan hal berikut:

Membuat instans klien
Membuat, mendapatkan, dan menonaktifkan model
Membuat, mengkueri, dan menghapus kembar digital
Mendapatkan dan memperbarui komponen untuk kembar digital
Membuat, mendapatkan, dan menghapus hubungan antara kembar digital
Membuat, mendapatkan, dan menghapus rute peristiwa untuk kembar digital
Menerbitkan pesan telemetri ke komponen kembar digital dan kembar digital

Membuat, mencantumkan, menonaktifkan, dan menghapus model

Membuat model

Mari kita buat model menggunakan kode di bawah ini. Anda perlu meneruskan array yang berisi daftar model.

temporary_component = {
    "@id": component_id,
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;2",
    "displayName": "Component1",
    "contents": [
    {
        "@type": "Property",
        "name": "ComponentProp1",
        "schema": "string"
    },
    {
        "@type": "Telemetry",
        "name": "ComponentTelemetry1",
        "schema": "integer"
    }
    ]
}

temporary_model = {
    "@id": model_id,
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;2",
    "displayName": "TempModel",
    "contents": [
    {
        "@type": "Property",
        "name": "Prop1",
        "schema": "string"
    },
    {
        "@type": "Component",
        "name": "Component1",
        "schema": component_id
    },
    {
        "@type": "Telemetry",
        "name": "Telemetry1",
        "schema": "integer"
    }
    ]
}

new_models = [temporary_component, temporary_model]
models = service_client.create_models(new_models)
print('Created Models:')
print(models)

Mencantumkan model

Menggunakan list_models untuk mengambil semua model yang dibuat

listed_models = service_client.list_models()
for model in listed_models:
    print(model)

Dapatkan model

Gunakan get_model dengan pengidentifikasi unik model untuk mendapatkan model tertentu.

# Get a model
get_model = service_client.get_model(model_id)
print('Get Model:')
print(get_model)

Model penonaktifan

Untuk menonaktifkan model, berikan Id model untuk model yang ingin Anda nonaktifkan.

# Decommission a model
service_client.decommission_model(model_id)

Menghapus model

Untuk menghapus model, berikan Id model untuk model yang ingin Anda hapus.

# Delete a model
service_client.delete_model(model_id)

Membuat dan menghapus kembar digital

Membuat kembar digital

Untuk Membuat Kembar, Anda harus memberikan Id digital Twin seperti my_twin dan aplikasi/json digital twin berdasarkan model yang dibuat sebelumnya. Anda dapat melihat contoh aplikasi/json di sini.

digital_twin_id = 'digitalTwin-' + str(uuid.uuid4())
temporary_twin = {
    "$metadata": {
        "$model": model_id
    },
    "$dtId": digital_twin_id,
    "Prop1": 42
}

created_twin = service_client.upsert_digital_twin(digital_twin_id, temporary_twin)
print('Created Digital Twin:')
print(created_twin)

Mendapatkan kembar digital

Mendapatkan kembar digital sangat mudah.

get_twin = service_client.get_digital_twin(digital_twin_id)
print('Get Digital Twin:')
print(get_twin)

Kueri kembar digital

Kueri instans Azure Digital Twins untuk kembar digital menggunakan lanaguage Penyimpanan Kueri Azure Digital Twins. Panggilan kueri mendukung halaman. Berikut adalah contoh cara mengkueri kembar digital dan cara melakukan iterasi atas hasilnya.

Perhatikan bahwa mungkin ada penundaan antara sebelum perubahan dalam instans Anda tercermin dalam kueri. Untuk detail selengkapnya tentang batasan kueri, lihat (/azure/digital-twins/how-to-query-graph#query-limitations)

query_expression = 'SELECT * FROM digitaltwins'
query_result = service_client.query_twins(query_expression)
print('DigitalTwins:')
for twin in query_result:
    print(twin)

Menghapus kembar digital

Hapus kembar digital hanya dengan menyediakan Id kembar digital seperti di bawah ini.

service_client.delete_digital_twin(digital_twin_id)

Mendapatkan dan memperbarui komponen kembar digital

Memperbarui komponen kembar digital

Untuk memperbarui komponen atau dengan kata lain untuk mengganti, menghapus, dan/atau menambahkan properti komponen atau subproperti dalam Digital Twin, Anda memerlukan Id operasi kembar digital, nama komponen, dan aplikasi/json-patch+json untuk dilakukan pada komponen kembar digital yang ditentukan. Berikut adalah kode sampel tentang cara melakukannya.

component_name = "Component1"
patch = [
    {
        "op": "replace",
        "path": "/ComponentProp1",
        "value": "value2"
    }
]
service_client.update_component(digital_twin_id, component_name, patch)

Mendapatkan komponen kembar digital

Dapatkan komponen dengan memberikan nama komponen dan Id kembar digital tempat komponen tersebut berada.

get_component = service_client.get_component(digital_twin_id, component_name)
print('Get Component:')
print(get_component)

Membuat dan mencantumkan hubungan kembar digital

Membuat hubungan kembar digital

upsert_relationship menciptakan hubungan pada kembar digital yang disediakan dengan Id kembar digital, nama hubungan seperti "contains", Id hubungan seperti "FloorContainsRoom" dan hubungan aplikasi/json yang akan dibuat. Harus berisi properti dengan kunci "$targetId" untuk menentukan target hubungan. Contoh payload untuk hubungan dapat ditemukan di sini.

hospital_relationships = [
    {
        "$relationshipId": "BuildingHasFloor",
        "$sourceId": building_twin_id,
        "$relationshipName": "has",
        "$targetId": floor_twin_id,
        "isAccessRestricted": False
    },
    {
        "$relationshipId": "BuildingIsEquippedWithHVAC",
        "$sourceId": building_twin_id,
        "$relationshipName": "isEquippedWith",
        "$targetId": hvac_twin_id
    },
    {
        "$relationshipId": "HVACCoolsFloor",
        "$sourceId": hvac_twin_id,
        "$relationshipName": "controlsTemperature",
        "$targetId": floor_twin_id
    },
    {
        "$relationshipId": "FloorContainsRoom",
        "$sourceId": floor_twin_id,
        "$relationshipName": "contains",
        "$targetId": room_twin_id
    }
]

for relationship in hospital_relationships:
    service_client.upsert_relationship(
        relationship["$sourceId"],
        relationship["$relationshipId"],
        relationship
    )

Mencantumkan hubungan kembar digital

list_relationships dan list_incoming_relationships mencantumkan semua hubungan dan semua hubungan masuk masing-masing dari kembar digital.

relationships = service_client.list_relationships(digital_twint_id)
for relationship in relationships:
    print(relationship)

incoming_relationships = service_client.list_incoming_relationships(digital_twin_id)
for incoming_relationship in incoming_relationships:
    print(incoming_relationship)

Membuat, mencantumkan, dan menghapus rute peristiwa kembar digital

Membuat rute peristiwa

Untuk membuat rute peristiwa, berikan Id rute peristiwa seperti "myEventRouteId" dan data rute peristiwa yang berisi titik akhir dan filter opsional seperti contoh yang ditunjukkan di bawah ini.

event_route_id = 'eventRoute-' + str(uuid.uuid4())
event_filter = "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'"
route = DigitalTwinsEventRoute(
    endpoint_name=event_hub_endpoint_name,
    filter=event_filter
)
service_client.upsert_event_route(event_route_id, route)

Untuk informasi selengkapnya tentang bahasa filter rute peristiwa, lihat dokumentasi peristiwa filter "cara mengelola rute".

Mencantumkan rute peristiwa

Cantumkan id rute peristiwa tertentu yang diberikan id rute peristiwa atau semua opsi pengaturan rute peristiwa dengan list_event_routes.

event_routes = service_client.list_event_routes()
for event_route in event_routes:
    print(event_route)

Menghapus rute peristiwa

Menghapus id rute peristiwa yang diberikan rute peristiwa.

service_client.delete_event_route(event_route_id)

Menerbitkan pesan telemetri untuk kembar digital

Untuk menerbitkan pesan telemetri untuk kembar digital, Anda perlu memberikan Id kembar digital, bersama dengan payload tempat telemetri yang memerlukan pembaruan.

digita_twin_id = "<DIGITAL TWIN ID>"
telemetry_payload = '{"Telemetry1": 5}'
service_client.publish_telemetry(
    digita_twin_id,
    telemetry_payload
)

Anda juga dapat menerbitkan pesan telemetri untuk komponen tertentu dalam kembar digital. Selain ID dan payload kembar digital, Anda perlu menentukan Id komponen target.

digita_twin_id = "<DIGITAL TWIN ID>"
component_name = "<COMPONENT_NAME>"
telemetry_payload = '{"Telemetry1": 5}'
service_client.publish_component_telemetry(
    digita_twin_id,
    component_name,
    telemetry_payload
)

Pemecahan Masalah

Pencatatan

Pustaka ini menggunakan pustaka pengelogan standar untuk pengelogan. Informasi dasar tentang sesi HTTP (URL, header, dll.) dicatat di tingkat INFO.

Pengelogan tingkat DEBUG terperinci, termasuk isi permintaan/respons dan header yang tidak diredaksikan, dapat diaktifkan pada klien dengan argumen kata kunci logging_enable:

Pengelogan tingkat klien

import sys
import logging

# Create logger
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# Create service client and enable logging for all operations
service_client = DigitalTwinsClient(url, credential, logging_enable=True)

Pengelogan tingkat operasi

import sys
import logging

# Create logger
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# Get model with logging enabled
model = service_client.get_model(model_id, logging_enable=True)

Konfigurasi Opsional

Argumen kata kunci opsional dapat diteruskan di tingkat klien dan per operasi. Dokumentasi referensi azure-core menjelaskan konfigurasi yang tersedia untuk percobaan ulang, pengelogan, protokol transportasi, dan banyak lagi.

Langkah berikutnya

Berikan Umpan Balik

Jika Anda menemukan bug atau memiliki saran, buka masalah.

Berkontribusi

Proyek ini menyambut baik kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi https://cla.microsoft.com.

Ketika Anda mengirimkan permintaan tarik, CLA-bot akan secara otomatis menentukan apakah Anda perlu memberikan CLA dan menghias PR dengan tepat (misalnya, label, komentar). Cukup ikuti instruksi yang diberikan oleh bot. Anda hanya perlu melakukan ini sekali di semua repos menggunakan CLA kami.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat Tanya Jawab Umum Tata Tertib atau hubungi opencode@microsoft.com untuk pertanyaan atau komentar lainnya.

Bagikan melalui