Mengelola model Azure Digital Twins

  • Artikel

Artikel ini menjelaskan cara mengelola model di instans Azure Digital Twins Anda. Operasi manajemen meliputi pengunggahan, validasi, pengambilan, dan penghapusan model.

Prasyarat

Untuk bekerja dengan Azure Digital Twins dalam artikel ini, Anda memerlukan instans Azure Digital Twins dan izin yang diperlukan untuk menggunakannya. Jika Anda sudah menyiapkan instans Azure Digital Twins, Anda dapat menggunakan instans tersebut dan melompat ke bagian berikutnya. Jika tidak, ikuti instruksi dalam Menyiapkan instans dan autentikasi. Instruksi berisi informasi untuk membantu Anda memverifikasi bahwa Anda telah menyelesaikan setiap langkah dengan sukses.

Setelah Anda menyiapkan instans, catat nama host instans. Anda dapat menemukan nama host di portal Microsoft Azure.

Antarmuka pengembang

Artikel ini menyoroti cara menyelesaikan berbagai operasi pengelolaan menggunakan .NET (C#) SDK. Anda juga dapat membuat panggilan pengelolaan yang sama ini menggunakan SDK bahasa lain yang dijelaskan di Azure Digital Twins API dan SDK.

Antarmuka pengembang lain yang dapat digunakan untuk menyelesaikan operasi ini meliputi:

Visualisasi

Azure Digital Twins Explorer adalah alat visual untuk menjelajahi data di grafik Azure Digital Twins Anda. Anda bisa menggunakan explorer untuk menampilkan, mengkueri, dan mengedit model, twin, dan hubungan Anda.

Baca Alat Penjelajah Azure Digital Twins di Penjelajah Azure Digital Twins. Untuk langkah-langkah mendetail tentang cara menggunakan fiturnya, lihat Menggunakan Penjelajah Azure Digital Twins.

Berikut tampilan visualisasinya:

Screenshot of Azure Digital Twins Explorer showing a sample model graph.

Membuat model

Anda dapat membuat model Anda sendiri dari awal, atau menggunakan ontologi yang ada yang tersedia untuk industri Anda.

Model penulis

Model untuk Azure Digital Twins ditulis dalam DTDL, dan disimpan sebagai file JSON. Ada juga ekstensi DTDL yang tersedia untuk Visual Studio Code, yang menyediakan validasi sintaksis dan fitur lainnya untuk mempermudah penulisan dokumen DTDL.

Pertimbangkan contoh tempat rumah sakit ingin mewakili kamar mereka secara digital. Setiap kamar berisi dispenser sabun pintar untuk memantau mencuci tangan, dan sensor untuk memantau lalu lintas melalui ruangan.

Langkah pertama menuju solusi adalah membuat model untuk mewakili aspek rumah sakit. Ruang pasien dalam skenario ini mungkin digambarkan seperti ini:

{
    "@id": "dtmi:com:contoso:PatientRoom;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "displayName": "Patient Room",
    "contents": [
      {
        "@type": "Property",
        "name": "visitorCount",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "handWashCount",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "handWashPercentage",
        "schema": "double"
      },
      {
        "@type": "Relationship",
        "name": "hasDevices"
      }
    ]
  }

Catatan

Ini adalah isi sampel untuk file JSON tempat model didefinisikan dan disimpan, untuk diunggah sebagai bagian dari proyek klien. Panggilan REST API, di sisi lain, mengambil array definisi model seperti yang di atas (yang dipetakan ke IEnumerable<string> dalam .NET SDK). Jadi untuk menggunakan model ini di REST API secara langsung, kelilingi dengan tanda kurung.

Model ini menentukan nama dan ID unik untuk ruangan pasien dan properti untuk mewakili jumlah pengunjung dan status cuci tangan. Penghitung ini akan diperbarui dari sensor gerakan dan dispenser sabun pintar, dan akan digunakan bersama-sama untuk menghitung handwash percentage properti. Model ini juga mendefinisikan hubungan hasDevices, yang akan digunakan untuk menghubungkan kembar digital apa pun berdasarkan model Ruangan ini ke perangkat aktual.

Catatan

Ada beberapa fitur DTDL yang saat ini tidak didukung Oleh Azure Digital Twins, termasuk writable atribut pada properti dan hubungan, dan minMultiplicity untuk maxMultiplicity hubungan. Untuk informasi selengkapnya, lihat Catatan DTDL khusus layanan.

Dengan mengikuti metode ini, Anda dapat menentukan model untuk bangsal rumah sakit, zona, atau rumah sakit itu sendiri.

Jika tujuan Anda adalah membangun set model komprehensif yang menjelaskan domain industri Anda, pertimbangkan apakah ada ontologi industri yang ada yang dapat Anda gunakan untuk mempermudah penulisan model. Bagian berikutnya menjelaskan ontologi industri secara lebih rinci.

Menggunakan ontologi standar industri yang ada

Ontologi adalah serangkaian model yang secara komprehensif menggambarkan domain tertentu, seperti manufaktur, struktur bangunan, sistem IoT, kota pintar, kisi energi, konten web, dan banyak lagi.

Jika solusi Anda adalah untuk industri tertentu yang menggunakan standar pemodelan apa pun, pertimbangkan untuk memulai dengan serangkaian model yang sudah ada sebelumnya yang dirancang untuk industri Anda alih-alih merancang model Anda dari awal. Microsoft telah bermitra dengan pakar domain untuk membuat ontologi model DTDL berdasarkan standar industri, untuk membantu meminimalkan penemuan ulang dan mendorong konsistensi dan kesederhanaan di seluruh solusi industri. Anda dapat membaca lebih lanjut tentang ontologi ini, termasuk cara menggunakannya dan ontologi apa yang tersedia sekarang, di Apa itu ontologi?.

Memvalidasi sintaks

Setelah membuat model, disarankan untuk memvalidasi model Anda secara offline sebelum mengunggahnya ke instans Azure Digital Twins Anda.

Untuk membantu Anda memvalidasi model, pustaka penguraian DTDL sisi klien .NET disediakan di NuGet: DTDLParser. Anda dapat menggunakan pustaka pengurai langsung dalam kode C#Anda. Anda juga dapat melihat penggunaan sampel pengurai di DTDLParserResolveSample di GitHub.

Mengunggah model

Setelah model dibuat, Anda dapat mengunggahnya ke instans Azure Digital Twins.

Saat Anda siap mengunggah model, Anda dapat menggunakan cuplikan kode berikut untuk .NET SDK:

// 'client' is an instance of DigitalTwinsClient
// Read model file into string (not part of SDK)
// fileName is the name of the JSON model file
string dtdl = File.ReadAllText(fileName);
await client.CreateModelsAsync(new[] { dtdl });

Saat diunggah, file model divalidasi oleh layanan.

Anda biasanya perlu mengunggah lebih dari satu model ke layanan. Ada beberapa cara agar Anda dapat mengunggah banyak model sekaligus dalam satu transaksi. Untuk membantu Anda memilih strategi, pertimbangkan ukuran set model saat Anda melanjutkan melalui bagian lainnya.

Mengunggah set model kecil

Untuk set model yang lebih kecil, Anda dapat mengunggah beberapa model sekaligus menggunakan panggilan API individual. Anda dapat memeriksa batas saat ini untuk berapa banyak model yang dapat diunggah dalam satu panggilan API di batas Azure Digital Twins.

Jika Anda menggunakan SDK, Anda dapat mengunggah beberapa file model dengan metode CreateModels seperti ini:

var dtdlFiles = Directory.EnumerateFiles(sourceDirectory, "*.json");

var dtdlModels = new List<string>();
foreach (string fileName in dtdlFiles)
{
    // Read model file into string (not part of SDK)
    string dtdl = File.ReadAllText(fileName);
    dtdlModels.Add(dtdl);
}
await client.CreateModelsAsync(dtdlModels);

Jika Anda menggunakan REST API atau Azure CLI, Anda dapat mengunggah beberapa model dengan menempatkan beberapa definisi model dalam satu file JSON untuk diunggah bersama-sama. Dalam hal ini, model harus ditempatkan dalam array JSON dalam file, seperti dalam contoh berikut:

[
    {
      "@id": "dtmi:com:contoso:Planet;1",
      "@type": "Interface",
      "@context": "dtmi:dtdl:context;3"
    },
    {
      "@id": "dtmi:com:contoso:Moon;1",
      "@type": "Interface",
      "@context": "dtmi:dtdl:context;3"
    }
]

Mengunggah set model besar dengan API Impor Pekerjaan

Untuk set model besar, Anda dapat menggunakan API Impor Pekerjaan untuk mengunggah banyak model sekaligus dalam satu panggilan API. API dapat secara bersamaan menerima hingga batas Azure Digital Twins untuk jumlah model dalam instans, dan secara otomatis menyusun ulang model jika diperlukan untuk menyelesaikan dependensi di antaranya. Metode ini memerlukan penggunaan Azure Blob Storage, serta izin tulis di instans Azure Digital Twins Anda untuk model dan pekerjaan massal.

Tip

API Pekerjaan Impor juga memungkinkan kembar dan hubungan diimpor dalam panggilan yang sama, untuk membuat semua bagian grafik sekaligus. Untuk informasi selengkapnya tentang proses ini, lihat Mengunggah model, kembar, dan hubungan secara massal dengan API Impor Pekerjaan.

Untuk mengimpor model secara massal, Anda harus menyusun model Anda (dan sumber daya lain yang disertakan dalam pekerjaan impor massal) sebagai file NDJSON . Bagian ini Models datang segera setelah Header bagian, menjadikannya bagian data grafik pertama dalam file. Anda dapat melihat contoh file impor dan proyek sampel untuk membuat file-file ini dalam pengantar Api Pekerjaan Impor.

Selanjutnya, file perlu diunggah ke dalam blob tambahan di Azure Blob Storage. Untuk petunjuk tentang cara membuat kontainer penyimpanan Azure, lihat Membuat kontainer. Kemudian, unggah file menggunakan metode pengunggahan pilihan Anda (beberapa opsi adalah perintah AzCopy, Azure CLI, atau portal Azure).

Setelah file NDJSON diunggah ke kontainer, dapatkan URL-nya dalam kontainer blob. Anda akan menggunakan nilai ini nanti dalam isi panggilan API impor massal.

Berikut adalah cuplikan layar yang menunjukkan nilai URL file blob di portal Azure:

Screenshot of the Azure portal showing the URL of a file in a storage container.

Kemudian, file dapat digunakan dalam panggilan Api Pekerjaan Impor. Anda akan menyediakan URL penyimpanan blob file input, serta URL penyimpanan blob baru untuk menunjukkan di mana Anda ingin log output disimpan saat dibuat oleh layanan.

Ambil model

Anda dapat mencantumkan dan mengambil model yang disimpan di instans Azure Digital Twins Anda.

Opsinya meliputi:

  • Mengambil satu model
  • Mengambil semua model
  • Mengambil metadata dan dependensi untuk model

Berikut adalah beberapa contoh panggilan:

// 'client' is a valid DigitalTwinsClient object

// Get a single model, metadata and data
Response<DigitalTwinsModelData> md1 = await client.GetModelAsync("<model-Id>");
DigitalTwinsModelData model1 = md1.Value;

// Get a list of the metadata of all available models; print their IDs
AsyncPageable<DigitalTwinsModelData> md2 = client.GetModelsAsync();
await foreach (DigitalTwinsModelData md in md2)
{
    Console.WriteLine($"Type ID: {md.Id}");
}

// Get models and metadata for a model ID, including all dependencies (models that it inherits from, components it references)
AsyncPageable<DigitalTwinsModelData> md3 = client.GetModelsAsync(new GetModelsOptions { IncludeModelDefinition = true });

SDK memanggil untuk mengambil model yang menampilkan objek DigitalTwinsModelData. DigitalTwinsModelData berisi metadata tentang model yang disimpan dalam instans Azure Digital Twins, seperti nama, DTMI, dan tanggal pembuatan model. DigitalTwinsModelData Objek juga secara opsional menyertakan model itu sendiri. Bergantung pada parameter, Anda dapat menggunakan panggilan pengambilan untuk mengambil metadata saja (yang berguna dalam skenario tempat Anda ingin menampilkan daftar UI alat yang tersedia, misalnya), atau seluruh model.

RetrieveModelWithDependencies Panggilan tidak hanya mengembalikan model yang diminta, tetapi juga semua model yang tergantung pada model yang diminta.

Model belum tentu ditampilkan dalam bentuk dokumen yang diunggah. Azure Digital Twins hanya menjamin bahwa formulir pengembalian akan setara secara semantik.

Perbarui model

Bagian ini menjelaskan pertimbangan dan strategi untuk memperbarui model Anda.

Sebelum memperbarui: Pikirkan dalam konteks seluruh solusi Anda

Sebelum membuat pembaruan pada model Anda, sebaiknya pertimbangkan secara holistik seluruh solusi Anda dan dampak dari perubahan model yang akan Anda buat. Model dalam solusi Azure Digital Twins sering saling berhubungan, jadi penting untuk menyadari penurunan perubahan di mana memperbarui satu model memerlukan pembaruan beberapa lainnya. Memperbarui model akan berdampak pada twin yang menggunakan model dan juga dapat mempengaruhi kode masuk dan pemrosesan, aplikasi klien, dan laporan otomatis.

Berikut adalah beberapa rekomendasi untuk membantu Anda mengelola transisi model dengan lancar:

  • Daripada memikirkan model sebagai entitas yang terpisah, pertimbangkan untuk mengembangkan seluruh rangkaian model Anda jika perlu untuk menjaga model dan hubungannya tetap terbarui.
  • Perlakukan model seperti kode sumber dan kelola dalam kontrol sumber. Berikan ketelitian dan perhatian yang sama pada model dan perubahan model yang Anda terapkan ke kode lain dalam solusi Anda.

Ketika Anda siap untuk melanjutkan proses memperbarui model, sisa bagian ini menjelaskan strategi yang dapat Anda gunakan untuk menerapkan pembaruan.

Strategi untuk memperbarui model

Setelah model diunggah ke instans Azure Digital Twins, antarmuka model tidak berubah, yang berarti tidak ada "pengeditan" model tradisional. Azure Digital Twins juga tidak mengizinkan pengunggahan kembali model yang sama persis sementara model yang cocok sudah ada dalam kasus ini.

Sebagai gantinya, jika Anda ingin membuat perubahan pada model—seperti memperbarui displayName atau description, atau menambahkan dan menghapus properti—Anda harus mengganti model aslinya.

Ada dua strategi yang dapat dipilih ketika mengganti model:

  • Strategi 1: Mengunggah versi model baru: Unggah model, dengan nomor versi baru, dan perbarui twin untuk menggunakan model baru tersebut. Baik versi baru dan lama dari model akan ada dalam instans sampai Anda menghapusnya.
    • Gunakan strategi ini saat Anda ingin memperbarui hanya beberapa twin yang menggunakan model atau saat Anda ingin memastikan twin tetap sesuai dengan modelnya dan memiliki kemampuan bisa-tulis melalui transisi model.
  • Strategi 2: Menghapus model lama dan mengunggah kembali: Hapus model asli dan unggah model baru dengan nama dan ID yang sama (nilai DTMI) sebagai gantinya. Sepenuhnya menggantikan model lama dengan yang baru.
    • Gunakan strategi ini saat Anda ingin memperbarui semua kembaran yang menggunakan model ini sekaligus, di samping semua kode yang bereaksi terhadap model. Jika pembaruan model Anda berisi perubahan yang melanggar pembaruan model, twin akan mengalami ketidaksesuaian dengan modelnya dalam waktu yang singkat saat Anda mengalihkannya dari model lama ke model baru. Artinya, twin tidak akan dapat mengambil pembaruan apa pun sampai model baru diunggah yang sesuai dengannya.

Catatan

Membuat perubahan pada model Anda tidak disarankan di luar pengembangan.

Lanjutkan ke bagian berikutnya untuk membaca lebih lanjut tentang setiap opsi strategi secara mendetail.

Strategi 1: Mengunggah versi model baru

Opsi ini melibatkan pembuatan versi baru dari model dan mengunggahnya ke instans Anda.

Operasi ini tidak menimpa versi model yang lebih lama, sehingga beberapa versi model akan berdampingan dalam instans Anda sampai Anda menghapusnya. Karena versi model baru dan versi model lama berfungsi berdampingan, twin dapat menggunakan versi baru dari model atau versi yang lebih lama. Artinya, mengunggah versi baru dari model tidak secara otomatis memengaruhi twin yang ada. Twin yang ada akan tetap sebagai instans dari versi model lama dan Anda dapat memperbarui twin ini ke versi model baru dengan mem-patchnya.

Untuk menggunakan strategi ini, ikuti langkah-langkah di bawah ini.

1. Buat dan unggah versi model baru

Untuk membuat versi baru model yang sudah ada, mulailah dengan DTDL model aslinya. Perbarui, tambahkan, atau hapus bidang yang ingin Anda ubah.

Selanjutnya, tandai ini sebagai versi model yang lebih baru dengan memperbarui bidang id model. Bagian terakhir dari ID model, setelah ;, menunjukkan nomor model. Untuk menunjukkan bahwa model ini sekarang adalah versi yang lebih baru, tambah angka di akhir nilai id ke angka yang lebih besar dari nomor versi saat ini.

Misalnya, jika ID model Anda sebelumnya terlihat seperti ini:

"@id": "dtmi:com:contoso:PatientRoom;1",

Versi 2 dari model ini mungkin terlihat seperti ini:

"@id": "dtmi:com:contoso:PatientRoom;2",

Kemudian, unggah versi baru model ke instans Anda.

Versi model ini kemudian akan tersedia dalam instans Anda untuk digunakan untuk kembar digital. Ini tidak menimpa versi model yang lebih lama, sehingga beberapa versi model sekarang hidup berdampingan dalam instans Anda.

2. Perbarui elemen grafis saat diperlukan

Kemudian, perbarui twin dan hubungan dalam instans Anda untuk menggunakan versi model yang baru daripada yang lama.

Anda dapat menggunakan instruksi berikut untuk memperbarui twin dan memperbarui hubungan. Operasi patch untuk memperbarui model twin akan terlihat seperti ini:

[
  {
    "op": "replace",
    "path": "/$metadata/$model",
    "value": "dtmi:example:foo;1"
  }
]

Penting

Dalam patch yang sama, Anda harus memperbarui patch yang sama untuk memperbarui baik ID model (ke versi model yang baru) dan bidang apa pun yang harus diubah pada twin agar sesuai dengan model yang baru.

Anda mungkin juga harus memperbarui hubungan dan model lain di instans Anda yang mereferensikan model ini, untuk membuatnya merujuk ke model yang baru. Anda harus melakukan operasi pembaruan model lain untuk mencapai tujuan ini, jadi kembali ke awal bagian ini dan ulangi proses untuk model lain yang perlu diperbarui.

3. (Opsional) Nonaktifkan atau hapus versi model lama

Jika Anda tidak akan menggunakan versi model yang lama lagi, Anda dapat menonaktifkan model yang lebih lama. Tindakan ini memungkinkan model untuk tetap ada dalam kasus ini, tetapi tidak dapat digunakan untuk membuat twin digital baru.

Anda juga dapat menghapus model lama secara menyeluruh jika Anda tidak ingin model tersebut berada di instans Anda.

Bagian yang ditautkan di atas berisi kode contoh dan pertimbangan untuk menonaktifkan dan menghapus model.

Strategi 2: Menghapus model lama dan mengunggah kembali

Alih-alih meningkatkan versi model, Anda dapat menghapus model sepenuhnya dan mengunggah ulang model yang diedit ke instans.

Azure Digital Twins tidak mengingat model lama yang pernah diunggah, jadi tindakan ini akan seperti mengunggah model yang sama sekali baru. Kembar yang menggunakan model akan secara otomatis beralih ke definisi baru setelah tersedia. Tergantung pada bagaimana definisi baru berbeda dari yang lama, twin ini mungkin memiliki properti dan hubungan yang sesuai dengan definisi yang dihapus dan tidak valid dengan yang baru, jadi Anda mungkin perlu melakukan patch untuk memastikannya agar tetap valid.

Untuk menggunakan strategi ini, ikuti langkah-langkah di bawah ini.

1. Hapus model lama

Karena Azure Digital Twins tidak mengizinkan dua model dengan ID yang sama, mulailah dengan menghapus model asli dari instans Anda.

Catatan

Jika Anda memiliki model lain yang bergantung pada model ini (melalui warisan atau komponen), Anda harus menghapus referensi tersebut sebelum Anda dapat menghapus model. Anda dapat memperbarui model dependen tersebut terlebih dahulu untuk menghapus referensi sementara atau menghapus model dependen dan mengunggahnya kembali di langkah selanjutnya.

Gunakan instruksi berikut untuk menghapus model asli Anda. Tindakan ini akan membuat twin Anda yang menggunakan model itu menjadi "tanpa induk" secara sementara karena twin sekarang menggunakan model yang tidak lagi ada. Keadaan ini akan diperbaiki pada langkah berikutnya ketika Anda mengunggah ulang model yang diperbarui.

2. Buat dan unggah model baru

Mulailah dengan DTDL dari model aslinya. Perbarui, tambahkan, atau hapus bidang yang ingin Anda ubah.

Kemudian, unggah model ke instans, anggap bahwa model tersebut adalah model baru yang pertama kali diunggah.

3. Perbarui elemen grafik sesuai kebutuhan

Sekarang model baru Anda telah diunggah sebagai pengganti yang lama, twin dalam grafik Anda akan secara otomatis mulai menggunakan definisi model baru setelah penembolokan dalam instans Anda berakhir dan diatur ulang. Proses ini mungkin butuh waktu 10-15 menit, tergantung ukuran grafik Anda. Setelah itu, properti baru dan berubah pada model Anda harusnya dapat diakses dan properti yang dihapus tidak akan dapat diakses lagi.

Catatan

Jika Anda menghapus model dependen lainnya sebelumnya untuk menghapus model asli, unggah ulang model sekarang setelah cache telah diatur ulang. Jika Anda sudah memperbarui model dependen untuk menghapus referensi untuk sementara ke model asli, Anda dapat memperbaruinya lagi untuk mengembalikan referensi.

Selanjutnya, perbaruitwin dan hubungan dalam instans Anda sehingga propertinya sesuai dengan properti yang ditentukan oleh model baru. Sebelum langkah ini selesai, twin yang tidak cocok dengan modelnya masih dapat dibaca, tetapi tidak dapat ditulis. Untuk informasi lebih lanjut keadaan twin tanpa model yang valid, lihat Twin tanpa model.

Ada dua cara untuk memperbarui twin dan hubungan untuk model baru sehingga twin dapat ditulis lagi:

  • Patch twin dan hubungan sesuai kebutuhan sehingga sesuai dengan model baru. Anda dapat menggunakan instruksi berikut untuk memperbarui twin dan memperbarui hubungan.
    • Jika Anda telah menambahkan properti: Memperbarui twin dan hubungan untuk memiliki nilai-nilai baru tidak diperlukan, karena twin yang kehilangan nilai-nilai baru masih akan menjadi twin yang valid. Anda dapat mem-patch namun Anda ingin menambahkan nilai untuk properti baru.
    • Jika Anda telah menghapus properti: Diperlukan untuk melakukan patch twin untuk menghapus properti yang sekarang tidak valid dengan model baru.
    • Jika Anda telah memperbarui properti: Anda diminta untuk mem-patch twin untuk memperbarui nilai properti yang diubah agar valid dengan model baru.
  • Hapus twin dan hubungan yang menggunakan model dan buat kembali. Anda dapat menggunakan instruksi berikut ini untuk menghapus twin dan membuat kembali twin, dan menghapus hubungan dan membuat kembali hubungan.
    • Anda mungkin ingin melakukan operasi ini jika Anda membuat banyak perubahan pada model dan akan sulit untuk memperbarui twin yang ada agar sesuai dengan operasi tersebut. Namun, pembuatan ulang bisa menjadi proses yang rumit jika Anda memiliki banyak twin yang saling terhubung dengan banyak hubungan.

Hapus model

Model juga dapat dihapus dari layanan, dengan salah satu dari dua cara:

  • Penonaktifan: Setelah model dinonaktifkan, Anda tidak dapat lagi menggunakannya untuk membuat digital twin baru. Kembar digital yang sudah ada yang sudah menggunakan model ini tidak terpengaruh, jadi Anda masih dapat memperbaruinya dengan hal-hal seperti perubahan properti dan menambah atau menghapus hubungan.
  • Penghapusan: Operasi ini akan sepenuhnya menghapus model dari solusi. Setiap kembar yang menggunakan model ini tidak lagi dikaitkan dengan model yang valid, sehingga mereka diperlakukan seolah-olah mereka tidak memiliki model sama sekali. Anda masih dapat membaca twin ini, tetapi tidak akan dapat membuat pembaruan apa pun padanya sampai ditugaskan kembali ke model yang berbeda.

Operasi ini adalah fitur terpisah dan tidak saling berdampak, meskipun operasi tersebut dapat digunakan bersama-sama untuk menghapus model secara bertahap.

Catatan

Jika Anda ingin menghapus semua model, kembar, dan hubungan dalam instans sekaligus, gunakan Delete Jobs API.

Penonaktifan

Untuk menonaktifkan model, Anda dapat menggunakan metode DecommissionModel dari SDK:

// 'client' is a valid DigitalTwinsClient
await client.DecommissionModelAsync(dtmiOfPlanetInterface);
// Write some code that deletes or transitions digital twins
//...

Anda juga dapat menonaktifkan model dengan menggunakan panggilan REST API Perbarui DigitalTwinModels. Properti decommissioned adalah satu-satunya properti yang dapat diganti dengan panggilan API ini. Dokumen JSON Patch akan terlihat seperti ini:

[
  {
    "op": "replace",
    "path": "/decommissioned",
    "value": true
  }
]

Status penonaktifan model disertakan dalam ModelData catatan yang dikembalikan oleh API pengambilan model.

Penghapusan

Anda dapat menghapus semua model dalam instans Anda sekaligus, atau Anda dapat melakukannya secara individual.

Untuk contoh terkait cara menghapus semua model secara bersamaan, lihat repositori Sampel end-to-end Azure Digital Twins di GitHub. File CommandLoop.cs berisi fungsi CommandDeleteAllModels dengan kode untuk menghapus semua model dalam instans.

Untuk menghapus model individual, ikuti petunjuk dan pertimbangan dari lanjutan dari bagian ini.

Sebelum penghapusan: Persyaratan penghapusan

Umumnya, model dapat dihapus kapan saja.

Pengecualian adalah model yang diandalkan model lain, baik dengan extends hubungan atau sebagai komponen. Misalnya, jika model ConferenceRoom memperluas model Room, dan memiliki model ACUnit sebagai komponen, Anda tidak dapat menghapus Room atau ACUnit hingga ConferenceRoom menghapus referensi masing-masing.

Anda dapat melakukannya dengan memperbarui model dependen untuk menghapus dependensi, atau menghapus model dependen sepenuhnya.

Selama penghapusan: Proses penghapusan

Bahkan jika model memenuhi persyaratan untuk segera menghapusnya, Anda mungkin ingin melalui beberapa langkah terlebih dahulu untuk menghindari konsekuensi yang tidak diinginkan bagi si kembar yang ditinggalkan. Berikut adalah beberapa langkah yang dapat membantu Anda mengelola proses:

  1. Pertama, menonaktifkan model
  2. Tunggu beberapa menit, untuk memastikan layanan telah memproses permintaan pembuatan kembar menit-menit terakhir yang dikirim sebelum penonaktifan
  3. Kueri kembar berdasarkan model untuk melihat semua kembar yang menggunakan model yang sekarang dinonaktifkan
  4. Hapus si kembar jika Anda tidak lagi membutuhkannya, atau patch mereka ke model baru jika diperlukan. Anda juga dapat memilih untuk membiarkannya, dalam hal ini akan menjadi twin tanpa model setelah model dihapus. Lihat bagian berikutnya untuk implikasi negara ini.
  5. Tunggu beberapa menit lagi untuk memastikan perubahan telah meresap
  6. Menghapus model

Untuk menghapus model, Anda dapat menggunakan panggilan SDK DeleteModel:

// 'client' is a valid DigitalTwinsClient
await client.DeleteModelAsync(IDToDelete);

Anda juga dapat menghapus suatu model dengan panggilan REST API Hapus DigitalTwinModels.

Setelah penghapusan: Kembar tanpa model

Setelah model dihapus, setiap kembar digital yang menggunakan model sekarang dianggap tanpa model. Perhatikan bahwa tidak ada kueri yang dapat memberi Anda daftar semua twin dalam keadaan ini—meskipun Anda masih dapat mengkueri twin dengan model yang dihapus untuk mengetahui twin mana yang terpengaruh.

Berikut adalah gambaran umum apa yang dapat dan tidak dapat Anda lakukan dengan twin yang tidak memiliki model.

Hal-hal yang dapat Anda lakukan:

  • Kueri kembar
  • Membaca properti
  • Membaca hubungan keluar
  • Menambahkan dan menghapus hubungan masuk (seperti dalam, kembar lain masih dapat membentuk hubungan dengan kembaran ini)
    • target Dalam definisi hubungan masih dapat mencerminkan DTMI dari model yang dihapus. Hubungan tanpa target yang ditentukan juga dapat bekerja di sini.
  • Hapus hubungan
  • Menghapus kembaran

Hal-hal yangtidak dapat Anda lakukan:

  • Edit hubungan keluar (seperti dalam, hubungan dari kembar ini ke kembar lainnya)
  • Edit properti

Setelah penghapusan: Mengunggah ulang model

Setelah model dihapus, Anda dapat memutuskan nanti untuk mengunggah model baru dengan ID yang sama dengan model yang Anda hapus. Inilah yang terjadi dalam kasus itu.

  • Dari perspektif penyimpanan solusi, ini sama dengan mengunggah model yang baru. Layanan ini tidak ingat yang lama pernah diunggah.
  • Jika ada twin yang tersisa dalam grafik yang merujuk model yang dihapus, twin tidak lagi bersifat tanpa induk; ID model ini kembali berlaku dengan definisi baru. Namun, jika definisi baru model berbeda dari definisi model yang dihapus, twin tersebut mungkin memiliki properti dan hubungan yang cocok dengan definisi yang dihapus dan tidak valid dengan definisi baru.

Azure Digital Twins tidak mencegah keadaan ini, jadi berhati-hatilah untuk mem-patch twin dengan tepat untuk memastikan twin tetap valid melalui pengalihan definisi model.

Mengonversi model v2 ke v3

Azure Digital Twins mendukung DTDL versi 2 dan 3 (masing-masing dipersingkat dalam dokumentasi ke v2 dan v3). V3 adalah pilihan yang direkomendasikan berdasarkan kemampuannya yang diperluas. Bagian ini menjelaskan cara memperbarui model DTDL v2 yang ada ke DTDL v3.

  1. Perbarui konteks. Fitur utama yang mengidentifikasi model sebagai v2 atau v3 adalah @context bidang pada antarmuka. Untuk mengonversi model dari v2 ke v3, ubah nilai konteks menjadi dtmi:dtdl:context;2dtmi:dtdl:context;3. Untuk banyak model, ini akan menjadi satu-satunya perubahan yang diperlukan.
    1. Nilai dalam v2: "@context": "dtmi:dtdl:context;2"
    2. Nilai dalam v3: "@context": "dtmi:dtdl:context;3".
  2. Jika diperlukan, perbarui jenis semantik. Di DTDL v2, jenis semantik didukung secara asli. Di DTDL v3, mereka disertakan dengan ekstensi fitur QuantitativeTypes. Jadi, jika model v2 Anda menggunakan jenis semantik, Anda harus menambahkan ekstensi fitur saat mengonversi model ke v3. Untuk melakukan ini, pertama-tama @context ubah bidang pada antarmuka dari satu nilai menjadi array nilai, lalu tambahkan nilai dtmi:dtdl:extension:quantitativeTypes;1.
    1. Nilai dalam v2: "@context": "dtmi:dtdl:context;2"
    2. Nilai dalam v3: "@context": ["dtmi:dtdl:context;3", "dtmi:dtdl:extension:quantitativeTypes;1"]
  3. Jika diperlukan, pertimbangkan batas ukuran. V2 dan v3 memiliki batas ukuran yang berbeda, jadi jika antarmuka Anda sangat besar, Anda mungkin ingin meninjau batasan perbedaan antara DTDL v2 dan v3.

Setelah perubahan ini, model DTDL v2 sebelumnya telah dikonversi ke model DTDL v3.

Anda mungkin juga ingin mempertimbangkan kemampuan baru DTDL v3, seperti properti jenis array, relaksasi versi, dan ekstensi fitur tambahan, untuk melihat apakah salah satu dari mereka akan menjadi tambahan yang bermanfaat. Untuk daftar lengkap perbedaan antara DTDL v2 dan v3, lihat Perubahan dari Versi 2 di Deskripsi Bahasa DTDL v3.

Langkah berikutnya

Lihat cara membuat dan mengelola kembar digital berdasarkan model Anda: