Bagikan melalui

Pustaka klien Azure IoT Models Repository untuk Python - versi 1.0.0a20220330001

  • Artikel

Pustaka Repositori Model Azure IoT untuk Python menyediakan fungsionalitas untuk bekerja dengan Repositori Model Azure IoT

Memulai

Instal paket

Instal pustaka Repositori Model Azure IoT untuk Python dengan pip:

pip install azure-iot-modelsrepository

Prasyarat

  • Repositori model mengikuti konvensi Azure IoT
    • Repositori model dapat dihosting di sistem file lokal atau dihosting di server web
    • Azure IoT menghosting Repositori Model Azure IoT global yang akan digunakan klien jika tidak ada lokasi kustom yang disediakan

Model Penerbitan

Ikuti panduan untuk menerbitkan model ke Repositori Model Azure IoT global.

Jika menggunakan repositori lokal atau jarak jauh kustom, Anda cukup menambahkan file model Anda ke struktur direktori di lokasi repositori, misalnya. dtmi/com/example/thermostat-1.json

Autentikasi

Saat ini, tidak ada mekanisme autentikasi yang didukung. Titik akhir global tidak terkait dengan langganan Azure dan tidak mendukung autentikasi. Semua model yang diterbitkan dimaksudkan untuk konsumsi publik anonim.

Konsep utama

Azure IoT Models Repository memungkinkan penyusun mengelola dan berbagi model kembar digital. Modelnya adalah dokumen JSON-LD yang ditentukan menggunakan Digital Twins Definition Language (DTDL).

Repositori mendefinisikan pola untuk menyimpan antarmuka DTDL dalam struktur direktori berdasarkan Pengidentifikasi Model Digital Twin (DTMI). Anda dapat menemukan antarmuka di repositori dengan mengonversi DTMI ke jalur relatif. Misalnya, DTMI dtmi:com:example:Thermostat;1 diterjemahkan ke /dtmi/com/example/thermostat-1.json.

Contoh

Bagian berikut ini menyediakan beberapa cuplikan yang mencakup tugas Repositori Model umum:

Menginisialisasi ModelsRepositoryClient

Lokasi Repositori

Ketika tidak ada lokasi repositori yang disediakan selama instansiasi, titik akhir global Repositori Model Azure IoT (https://devicemodels.azure.com/) digunakan

client = ModelsRepositoryClient()

Atau, Anda dapat menyediakan lokasi kustom tempat repositori Anda berada melalui kata kunci opsional repository_location . Klien menerima format lokasi berikut:

  • URL Web - misalnya "https://contoso.com/models/"
  • URI Filesystem Lokal - misalnya "file:///path/to/repository/"
  • Jalur file POSIX - misalnya "/path/to/repository/"
  • Drive letter filepath - misalnya "C:/path/to/repository/"
client = ModelsRepositoryClient(repository_location="https://contoso.com/models/")

Mode Resolusi Dependensi

Klien dapat dikonfigurasi dengan mode opsional dependency_resolution saat instantiation, menggunakan salah satu nilai berikut:

  • 'disabled' - Klien tidak akan menyelesaikan dependensi model
  • 'enabled' - Klien akan menyelesaikan dependensi model apa pun
  • 'tryFromExpanded' - Klien akan mencoba menyelesaikan model menggunakan definisi model yang diperluas (mundur ke 'enabled' mode jika tidak memungkinkan)
client = ModelsRepositoryClient(dependency_resolution="enabled")

dependency_resolution Jika mode tidak ditentukan:

  • Klien yang dikonfigurasi untuk titik akhir global Repositori Model Azure IoT akan default menggunakan 'tryFromExpanded'
  • Klien yang dikonfigurasi untuk lokasi kustom (jarak jauh atau lokal) akan default menggunakan 'enabled'

Opsi Tambahan

Jika Anda perlu mengambil alih perilaku alur default dari pustaka azure-core, Anda dapat memberikan berbagai argumen kata kunci selama instantiation.

Pembersihan klien

Setelah selesai dengan klien Anda, pastikan untuk memanggil .close() untuk membebaskan sumber daya

client = ModelsRepositoryClient()
# Do things
client.close()

Untuk menghindari keharusan melakukan ini, disarankan agar Anda menggunakan klien Anda dari dalam manajer konteks jika memungkinkan, yang akan secara otomatis ditutup untuk Anda

with ModelsRepositoryClient() as client:
    # Do things

ModelsRepositoryClient - Dapatkan Model

Perhatikan bahwa Anda harus terlebih dahulu menerbitkan model ke repositori Anda sebelum Anda dapat mengambilnya. Contoh berikut mengasumsikan Anda menggunakan Repositori Model Azure IoT global.

.get_models() Panggilan akan mengambil model di DTMI yang disediakan dan berpotensi dependensinya (tergantung pada mode resolusi dependensi). Ini akan mengembalikan dict yang memetakan DTMIs ke definisi model.

dtmi = "dtmi:com:example:TemperatureController;1"
with ModelsRepositoryClient() as client:
    models = get_models(dtmi)
print("{} resolved in {} interfaces".format(dtmi, len(models)))

Jika Anda menyediakan beberapa DTMI ke metode , Anda dapat mengambil beberapa model (dan kemungkinan dependensinya) sekaligus

dtmis = ["dtmi:com:example:TemperatureController;1", "dtmi:com:example:azuresphere:sampledevice;1"]
with ModelsRepositoryClient() as client:
    models = get_models(dtmis)
print("{} resolved in {} interfaces".format(dtmi, len(models)))

Secara default klien akan menggunakan mode resolusi mana pun mode resolusi dependensi yang dikonfigurasi dengan pada instansiasi saat mengambil model. Namun, perilaku ini dapat ditimpa dengan meneruskan salah satu opsi yang valid sebagai argumen kata kunci opsional ke .get_models()

dtmi = "dtmi:com:example:TemperatureController;1"
with ModelsRepositoryClient(dependency_resolution="disabled") as client:
    models = get_models(dtmi, dependency_resolution="enabled")

Konvensi DTMI

Paket berisi modul yang disebut dtmi_conventions, yang, ketika diimpor menyediakan serangkaian operasi utilitas untuk bekerja dengan DTMIs

# Returns True - this is a valid DTMI
dtmi_conventions.is_valid_dtmi("dtmi:com:example:Thermostat;1")

# Returns False - this is NOT a valid DTMI
dtmi_conventions.is_valid_dtmi("dtmi:com:example:Thermostat")

dtmi = "dtmi:com:example:Thermostat;1"

# Local repository example
repo_uri = "file:///path/to/repository"
print(dtmi_conventions.get_model_uri(dtmi, repo_uri))
# Prints: "file:///path/to/repository/dtmi/com/example/thermostat-1.json"
print(dtmi_conventions.get_model_uri(dtmi, repo_uri, expanded=True))
# Prints: "file:///path/to/repository/dtmi/com/example/thermostat-1.expanded.json"

# Remote repository example
repo_uri = "https://contoso.com/models/"
print(dtmi_conventions.get_model_uri(dtmi, repo_uri))
# Prints: "https://contoso/com/models/dtmi/com/example/thermostat-1.json"
print(dtmi_conventions.get_model_uri(dtmi, repo_uri, expanded=True))
# Prints: "https://contoso/com/models/dtmi/com/example/thermostat-1.expanded.json"

Pemecahan Masalah

Pencatatan

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

Pengecualian

API Repositori Model dapat memunculkan pengecualian yang ditentukan dalam azure-core.

Selain itu, mereka dapat memunculkan pengecualian yang ditentukan dalam azure-iot-modelsrepository:

  • ModelError - Menunjukkan kesalahan yang terjadi saat mencoba mengurai/menyelesaikan definisi model. Ini umumnya berarti bahwa ada model cacat yang tidak mematuhi spesifikasi DTDL model

Berikan Umpan Balik

Jika Anda menemukan bug atau memiliki saran, buka masalah.

Langkah berikutnya

Sampel

Sampel tambahan tersedia di repositori sampel.

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.