API dan SDK Azure Digital Twins

Artikel
11/20/2023

Artikel ini memberikan gambaran umum tentang API Azure Digital Twins yang tersedia, dan metode untuk berinteraksi dengannya. Anda dapat menggunakan REST API secara langsung dengan Swaggers terkait (melalui alat seperti Postman), atau melalui SDK.

Azure Digital Twins dilengkapi dengan API sarana kontrol, API sarana data, dan SDK untuk mengelola instans Anda dan elemennya.

API sarana kontrol adalah API Azure Resource Manager (ARM), dan operasi manajemen sumber daya sampul seperti membuat dan menghapus instans Anda.
API pesawat data adalah API Azure Digital Twins yang digunakan untuk operasi manajemen data seperti mengelola model, kembar, dan grafik.
SDK memanfaatkan API yang ada untuk memungkinkan kemudahan pengembangan aplikasi khusus yang memanfaatkan Azure Digital Twins.

API sarana kontrol

API saran kontrol adalah API ARM yang digunakan untuk mengelola instans Azure Digital Twins Anda secara keseluruhan, sehingga mereka mencakup operasi seperti membuat atau menghapus seluruh instans Anda. Anda juga akan menggunakan API ini untuk membuat dan menghapus titik akhir.

Untuk memanggil API secara langsung, referensikan folder Swagger terbaru di repositori Swagger sarana kontrol. Folder ini juga menyertakan folder contoh yang menampilkan penggunaan.

Berikut adalah SDK yang saat ini tersedia untuk API sarana kontrol Azure Digital Twins.

Bahasa SDK	Tautan paket	Dokumentasi rujukan	Kode sumber
.NET (C#)	Azure.ResourceManager.DigitalTwins di NuGet	Referensi untuk Azure DigitalTwins SDK untuk .NET	Pustaka klien manajemen Microsoft Azure Digital Twins untuk .NET di GitHub
Java	azure-resourcemanager-digitaltwins di Maven	Referensi untuk Manajemen Sumber Daya - Digital Twins	Pustaka klien Azure Resource Manager AzureDigitalTwins untuk Java di GitHub
JavaScript	Pustaka klien AzureDigitalTwinsManagement untuk JavaScript di npm		Pustaka klien AzureDigitalTwinsManagement untuk JavaScript di GitHub
Python	azure-mgmt-digitaltwins di PyPI		Microsoft Azure SDK untuk Python di GitHub
Go	azure-sdk-for-go/services/digitaltwins/mgmt		Azure SDK untuk Go di GitHub

Anda juga dapat menjalankan API sarana kontrol dengan berinteraksi dengan Azure Digital Twins melalui portal Azure dan CLI.

API data plane

API sarana data adalah API Azure Digital Twins yang digunakan untuk mengelola elemen dalam instans Azure Digital Twins Anda. API ini meliputi operasi seperti membuat rute, mengunggah model, menciptakan hubungan, dan mengelola kembaran, dan dapat dibagi secara luas menjadi kategori berikut:

DigitalTwinModels - Kategori DigitalTwinModels berisi API untuk mengelola model dalam instans Azure Digital Twins. Kegiatan pengelolaan meliputi pengunggahan, validasi, pengambilan, dan penghapusan model yang ditulis dalam DTDL.
DigitalTwins - Kategori DigitalTwins berisi API yang memungkinkan pengembang membuat, memodifikasi, dan menghapus kembar digital dan hubungannya dalam instans Azure Digital Twins.
Query - Kategori Kueri memungkinkan pengembang menemukan set kembar digital dalam grafik kembar di seluruh hubungan.
Event Routes - Kategori Rute Peristiwa berisi API untuk merutekan data, melalui sistem dan ke layanan hilir.
Import Jobs - API Impor Pekerjaan memungkinkan Anda mengelola tindakan asinkron yang berjalan lama untuk mengimpor model, kembar , dan hubungan secara massal.
Delete Jobs - Delete Jobs API memungkinkan Anda mengelola tindakan asinkron yang berjalan lama untuk menghapus semua model, kembar , dan hubungan dalam instans.

Untuk memanggil API secara langsung, referensikan folder Swagger terbaru di repositori Swagger bidang data. Folder ini juga menyertakan folder contoh yang menampilkan penggunaan. Anda juga dapat melihat dokumentasi referensi API sarana data.

Berikut adalah SDK yang saat ini tersedia untuk API sarana data Azure Digital Twins.

Bahasa SDK	Tautan paket	Dokumentasi rujukan	Kode sumber
.NET (C#)	Azure.DigitalTwins.Core di NuGet	Referensi untuk pustaka klien Azure IoT Digital Twins untuk .NET	Pustaka klien Azure IoT Digital Twins untuk .NET di GitHub
Java	com.azure:azure-digitaltwins-core di Maven	Referensi untuk Azure Digital Twins SDK untuk Java	Pustaka klien Azure IoT Digital Twins untuk Java di GitHub
JavaScript	Pustaka klien Azure Digital Twins Core untuk JavaScript di npm	Reference for @azure/digital-twins-core	Pustaka klien Azure Digital Twins Core untuk JavaScript di GitHub
Python	Pustaka klien Azure Digital Twins Core untuk Python di PyPI	Referensi untuk azure-digitaltwins-core	Pustaka klien Azure Digital Twins Core untuk Python di GitHub

Anda juga dapat menjalankan API sarana data dengan berinteraksi dengan Azure Digital Twins melalui CLI.

Catatan penggunaan dan autentikasi

Bagian ini berisi informasi lebih rinci tentang menggunakan API dan SDK.

Catatan API

Berikut adalah beberapa informasi umum untuk memanggil API Azure Digital Twins secara langsung.

Anda dapat menggunakan alat pengujian HTTP REST seperti Postman untuk melakukan panggilan langsung ke API Azure Digital Twins. Untuk informasi selengkapnya tentang proses ini, lihat Memanggil API Azure Digital Twins dengan Postman.
Azure Digital Twins saat ini tidak mendukung Berbagi Sumber Daya Lintas Asal (CORS). Untuk informasi selengkapnya tentang strategi dampak dan resolusi, lihat Berbagi Sumber Daya Lintas Asal (CORS) untuk Azure Digital Twins.

Berikut adalah beberapa informasi selengkapnya tentang autentikasi untuk permintaan API.

Salah satu cara untuk menghasilkan token pembawa untuk permintaan AZURE Digital Twins API adalah dengan perintah AZ account get-access-token CLI. Untuk petunjuk terperinci, lihat Mendapatkan token pembawa.
Permintaan ke API Azure Digital Twins memerlukan pengguna atau perwakilan layanan yang merupakan bagian dari penyewa MICROSOFT Entra ID yang sama tempat instans Azure Digital Twins berada. Untuk mencegah pemindaian titik akhir Azure Digital Twins yang berbahaya, permintaan dengan token akses dari luar penyewa asal akan menampilkan pesan kesalahan "404 Sub-Domain tidak ditemukan". Kesalahan ini akan dikembalikan meskipun pengguna atau perwakilan layanan diberikan peran Pemilik Data Azure Digital Twins atau Pembaca Data Azure Digital Twins melalui kolaborasi Microsoft Entra B2B . Untuk informasi tentang cara mencapai akses di beberapa penyewa, lihat Menulis kode autentikasi aplikasi.

Catatan SDK

SDK yang mendasar untuk Azure Digital Twins adalah Azure.Core. Lihat dokumentasi namespace layanan Azure untuk referensi tentang infrastruktur dan jenis SDK.

Berikut adalah beberapa informasi selengkapnya tentang autentikasi dengan SDK.

Mulailah dengan membuat instans DigitalTwinsClient kelas. Konstruktor memerlukan informasi masuk yang dapat diperoleh dengan berbagai metode autentikasi dalam paket Azure.Identity. Untuk informasi selengkapnya tentang Azure.Identity, lihat dokumentasi namespace-nya.
Anda mungkin menemukan InteractiveBrowserCredential yang berguna saat memulai, tetapi ada beberapa opsi lain, termasuk informasi masuk untuk identitas terkelola, yang kemungkinan akan Anda gunakan untuk mengautentikasi penyiapan fungsi Azure dengan MSI terhadap Azure Digital Twins. Untuk informasi selengkapnya tentang InteractiveBrowserCredential, lihat dokumentasi kelasnya.

Berikut adalah beberapa informasi selengkapnya tentang fungsi dan data yang dikembalikan.

Semua panggilan API layanan diekspos sebagai fungsi anggota di kelas DigitalTwinsClient.
Semua fungsi layanan ada dalam versi sinkron dan asinkron.
Semua fungsi layanan memberikan pengecualian untuk status pengembalian 400 atau lebih. Pastikan Anda membungkus panggilan ke dalam try bagian, dan menangkap setidaknyaRequestFailedExceptions. Untuk informasi selengkapnya tentang jenis pengecualian ini, lihat dokumentasi referensinya.
Sebagian besar metode layanan kembali Response<T> atau (Task<Response<T>> untuk panggilan asinkron), di mana T kelas objek pengembalian untuk panggilan layanan. Kelas respons merangkum pengembalian layanan dan menyajikan nilai pengembalian di Value bidangnya.
Metode layanan dengan hasil halaman kembali Pageable<T> atau AsyncPageable<T> sebagai hasil. Untuk informasi selengkapnya tentang kelas Pageable<T>, lihat dokumentasi referensinya; untuk informasi selengkapnya tentang AsyncPageable<T>, lihat dokumentasi referensinya.
Anda dapat mengulangi hasil halaman menggunakan await foreach perulangan. Untuk informasi selengkapnya tentang proses ini, lihat Iterasi dengan Async Enumerables di C# 8.
Metode servis sebisa mungkin menampilkan objek yang diketik tebal. Namun, karena Azure Digital Twins didasarkan pada model yang dikonfigurasi khusus oleh pengguna pada waktu proses (melalui model DTDL yang diunggah ke layanan), banyak API layanan mengambil dan mengembalikan data kembar dalam format JSON.

Pembantu serialisasi di .NET (C#) SDK

Pembantu serialisasi adalah fungsi pembantu yang tersedia dalam .NET (C#) SDK untuk membuat atau mendeserialisasi data kembar dengan cepat untuk akses ke informasi dasar. Karena metode SDK inti menampilkan data kembar sebagai JSON secara default, sebaiknya gunakan kelas pembantu ini untuk membagi data kembar lebih lanjut.

Kelas pembantu yang tersedia adalah:

BasicDigitalTwin: Secara umum mewakili data inti dari kembar digital
BasicDigitalTwinComponent: Secara umum mewakili komponen di Contentsproperti BasicDigitalTwin
BasicRelationship: Secara umum mewakili data inti dari hubungan
DigitalTwinsJsonPropertyName: Berisi konstanta string untuk digunakan dalam serialisasi dan deserialisasi JSON untuk jenis kembar digital kustom

Impor massal dengan API Impor Pekerjaan

API Pekerjaan Impor adalah API sarana data yang memungkinkan Anda mengimpor sekumpulan model, kembar, dan/atau hubungan dalam satu panggilan API. Operasi API Pekerjaan Impor juga disertakan dengan perintah CLI dan SDK sarana data. Menggunakan API Impor Pekerjaan memerlukan penggunaan Azure Blob Storage.

Periksa izin

Untuk menggunakan API Impor Pekerjaan, Anda harus mengaktifkan pengaturan izin yang dijelaskan di bagian ini.

Pertama, Anda memerlukan identitas terkelola yang ditetapkan sistem untuk instans Azure Digital Twins Anda. Untuk petunjuk menyiapkan identitas yang dikelola sistem untuk instans, lihat Mengaktifkan/menonaktifkan identitas terkelola untuk instans.

Anda harus memiliki izin tulis di instans Azure Digital Twins Anda untuk kategori tindakan data berikut:

Microsoft.DigitalTwins/jobs/*
Elemen grafik apa pun yang ingin Anda sertakan dalam panggilan Pekerjaan. Ini mungkin termasuk Microsoft.DigitalTwins/models/*, , Microsoft.DigitalTwins/digitaltwins/*dan/atau Microsoft.DigitalTwins/digitaltwins/relationships/*.

Peran bawaan yang menyediakan semua izin ini adalah Pemilik Data Azure Digital Twins. Anda juga dapat menggunakan peran kustom untuk memberikan akses terperinci hanya ke jenis data yang Anda butuhkan. Untuk informasi selengkapnya tentang peran di Azure Digital Twins, lihat Keamanan untuk solusi Azure Digital Twins.

Catatan

Jika Anda mencoba panggilan Impor API Pekerjaan dan Anda kehilangan izin tulis ke salah satu jenis elemen grafik yang ingin Anda impor, pekerjaan akan melewati jenis tersebut dan mengimpor yang lain. Misalnya, jika Anda memiliki akses tulis ke model dan kembar, tetapi bukan hubungan, upaya untuk mengimpor ketiga jenis elemen secara massal hanya akan berhasil mengimpor model dan kembar. Status pekerjaan akan mencerminkan kegagalan dan pesan akan menunjukkan izin mana yang hilang.

Anda juga harus memberikan izin RBAC berikut ke identitas terkelola yang ditetapkan sistem instans Azure Digital Twins Anda sehingga dapat mengakses file input dan output dalam kontainer Azure Blob Storage:

Pembaca Data Blob Penyimpanan untuk kontainer blob input Azure Storage
Kontributor Data Blob Penyimpanan untuk kontainer blob output Azure Storage

Terakhir, buat token pembawa yang dapat digunakan dalam permintaan Anda ke JOBS API. Untuk petunjuknya, lihat Mendapatkan token pembawa.

Memformat data

API menerima input informasi grafik dari file NDJSON , yang harus diunggah ke kontainer penyimpanan blob Azure. File dimulai dengan Header bagian , diikuti oleh bagian Modelsopsional , , Twinsdan Relationships. Anda tidak perlu menyertakan ketiga jenis data grafik dalam file, tetapi bagian apa pun yang ada harus mengikuti urutan tersebut. Kembar dan hubungan yang dibuat dengan API ini dapat secara opsional menyertakan inisialisasi properti mereka.

Berikut adalah contoh file data input untuk API impor:

{"Section": "Header"}
{"fileVersion": "1.0.0", "author": "foobar", "organization": "contoso"}
{"Section": "Models"}
{"@id":"dtmi:com:microsoft:azure:iot:model0;1","@type":"Interface","contents":[{"@type":"Property","name":"property00","schema":"integer"},{"@type":"Property","name":"property01","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}},{"@type":"Relationship","name":"has","target":"dtmi:com:microsoft:azure:iot:model1;1","properties":[{"@type":"Property","name":"relationshipproperty1","schema":"string"},{"@type":"Property","name":"relationshipproperty2","schema":"integer"}]}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"@id":"dtmi:com:microsoft:azure:iot:model1;1","@type":"Interface","contents":[{"@type":"Property","name":"property10","schema":"string"},{"@type":"Property","name":"property11","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"Section": "Twins"}
{"$dtId":"twin0","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model0;1"},"property00":10,"property01":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"$dtId":"twin1","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model1;1"},"property10":"propertyValue1","property11":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"Section": "Relationships"}
{"$dtId":"twin0","$relationshipId":"relationship","$targetId":"twin1","$relationshipName":"has","relationshipProperty1":"propertyValue1","relationshipProperty2":10}

Tip

Untuk proyek sampel yang mengonversi model, kembar, dan hubungan ke dalam NDJSON yang didukung oleh API impor, lihat Generator NDJSON Impor Massal Azure Digital Twins. Proyek sampel ditulis untuk .NET dan dapat diunduh atau disesuaikan untuk membantu Anda membuat file impor Anda sendiri.

Setelah file dibuat, unggah ke blob blok di Azure Blob Storage menggunakan metode unggahan pilihan Anda (beberapa opsi adalah perintah AzCopy, Azure CLI, atau portal Azure). Anda akan menggunakan URL penyimpanan blob file NDJSON dalam isi panggilan API Pekerjaan Impor.

Menjalankan pekerjaan impor

Sekarang Anda dapat melanjutkan dengan memanggil API Impor Pekerjaan. Untuk petunjuk terperinci tentang mengimpor grafik lengkap dalam satu panggilan API, lihat Mengunggah model, kembar, dan hubungan secara massal dengan API Impor Pekerjaan. Anda juga dapat menggunakan API Impor Pekerjaan untuk mengimpor setiap jenis sumber daya secara independen. Untuk informasi selengkapnya tentang menggunakan API Impor Pekerjaan dengan jenis sumber daya individual, lihat Instruksi API Impor Pekerjaan untuk model, kembar, dan hubungan.

Dalam isi panggilan API, Anda akan menyediakan URL penyimpanan blob dari file input NDJSON. Anda juga akan menyediakan URL penyimpanan blob baru untuk menunjukkan di mana Anda ingin log output disimpan setelah layanan membuatnya.

Penting

Pastikan identitas terkelola yang ditetapkan sistem instans Azure Digital Twins Anda memiliki izin RBAC blob penyimpanan yang dijelaskan di bagian Periksa izin.

Saat pekerjaan impor dijalankan, log output terstruktur dihasilkan oleh layanan dan disimpan sebagai blob tambahan baru di kontainer blob Anda, di lokasi URL yang Anda tentukan untuk blob output dalam permintaan. Berikut adalah contoh log output untuk pekerjaan yang berhasil mengimpor model, kembar, dan hubungan:

{"timestamp":"2022-12-30T19:50:34.5540455Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Started"}}
{"timestamp":"2022-12-30T19:50:37.2406748Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Started"}}
{"timestamp":"2022-12-30T19:50:38.1445612Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:38.5475921Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Started"}}
{"timestamp":"2022-12-30T19:50:39.2744802Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:39.7494663Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Started"}}
{"timestamp":"2022-12-30T19:50:40.4480645Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:41.3043264Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Succeeded"}}

Ketika pekerjaan selesai, Anda dapat melihat jumlah total entitas yang diserap menggunakan metrik BulkOperationEntityCount.

Anda juga dapat membatalkan pekerjaan impor yang sedang berjalan dengan operasi Batalkan dari API Pekerjaan Impor. Setelah pekerjaan dibatalkan dan tidak lagi berjalan, Anda dapat menghapusnya.

Batasan dan pertimbangan

Ingatlah pertimbangan berikut saat bekerja dengan API Impor Pekerjaan:

Impor Pekerjaan bukan operasi atomik. Tidak ada pembatalan dalam kasus kegagalan, penyelesaian pekerjaan parsial, atau penggunaan operasi Batal.
Hanya satu pekerjaan massal yang didukung pada satu waktu dalam instans Azure Digital Twins. Anda dapat melihat informasi ini dan batas numerik lainnya dari API Pekerjaan di batas Azure Digital Twins.

Hapus massal dengan API Hapus Pekerjaan

DELETE Jobs API adalah API sarana data yang memungkinkan Anda menghapus semua model, kembar, dan hubungan dalam instans dengan satu panggilan API. Operasi Delete Jobs API juga tersedia sebagai perintah CLI. Kunjungi dokumentasi API untuk melihat detail permintaan untuk membuat pekerjaan penghapusan dan memeriksa statusnya.

Untuk memastikan semua elemen dihapus, ikuti rekomendasi ini saat menggunakan Delete Jobs API:

Untuk petunjuk tentang cara membuat token pembawa untuk mengautentikasi permintaan API, lihat Mendapatkan token pembawa.
Jika Anda baru-baru ini mengimpor sejumlah besar entitas ke grafik Anda, tunggu beberapa waktu dan verifikasi bahwa semua elemen disinkronkan dalam grafik Anda sebelum memulai pekerjaan penghapusan.
Hentikan semua operasi pada instans, terutama operasi unggah, hingga pekerjaan penghapusan selesai.

Bergantung pada ukuran grafik yang dihapus, pekerjaan penghapusan dapat berlangsung dari beberapa menit hingga beberapa jam.

Periode batas waktu default untuk pekerjaan penghapusan adalah 12 jam, yang dapat disesuaikan dengan nilai apa pun antara 15 menit dan 24 jam dengan menggunakan parameter kueri pada API. Ini adalah jumlah waktu pekerjaan penghapusan akan berjalan sebelum waktu habis, di mana layanan akan mencoba menghentikan pekerjaan jika belum selesai.

Batasan dan pertimbangan lainnya

Ingatlah pertimbangan berikut saat bekerja dengan Delete Jobs API:

Hapus Pekerjaan bukan operasi atomik. Tidak ada pembatalan dalam kasus kegagalan, penyelesaian pekerjaan parsial, atau batas waktu pekerjaan.
Hanya satu pekerjaan massal yang didukung pada satu waktu dalam instans Azure Digital Twins. Anda dapat melihat informasi ini dan batas numerik lainnya dari API Pekerjaan di batas Azure Digital Twins.

Pantau metrik API

Metrik API seperti permintaan, latensi, dan tingkat kegagalan dapat dilihat di portal Microsoft Azure.

Untuk informasi tentang menampilkan dan mengelola metrik Azure Digital Twins, lihat Memantau instans Anda. Untuk daftar lengkap metrik API yang tersedia untuk Azure Digital Twins, lihat Metrik permintaan API Azure Digital Twins.

Langkah berikutnya

Lihat cara membuat permintaan langsung ke API Azure Digital Twins menggunakan Postman:

Memanggil API Azure Digital Twins dengan Postman

Atau, berlatih menggunakan SDK .NET dengan membuat aplikasi klien dengan tutorial ini:

Kode aplikasi klien