Pelajari tentang model kembar dan cara menentukannya di Azure Digital Twins

Artikel
01/04/2024

Karakteristik utama Azure Digital Twins adalah kemampuan untuk menentukan kosakata Anda sendiri dan membangun grafik kembar dalam istilah bisnis yang ditentukan sendiri. Kemampuan ini disediakan melalui model yang disediakan pengguna. Anda dapat menganggap model sebagai kata benda dalam deskripsi dunia. Model Azure Digital Twins direpresentasikan dalam Bahasa Definisi Kembaran Digital (DTDL) berbasis JSON-LD.

Model mirip dengan kelas dalam bahasa pemrogram berorientasi objek, yang menentukan bentuk data untuk satu konsep tertentu di lingkungan kerja Anda yang sebenarnya. Model memiliki nama (seperti Room atau TemperatureSensor), dan berisi elemen seperti properti, komponen, dan hubungan yang menjelaskan jenis entitas ini di lingkungan Anda. Nantinya, Anda akan menggunakan model ini untuk membuat digital twins yang mewakili entitas tertentu yang memenuhi deskripsi jenis ini.

Bahasa Definisi Kembaran Digital (DTDL) untuk model

Model untuk Azure Digital Twins ditentukan menggunakan Bahasa Definisi Kembaran Digital (DTDL).

Anda dapat melihat deskripsi bahasa lengkap untuk DTDL v3 di GitHub: Deskripsi Bahasa DTDL Versi 3. Halaman ini mencakup detail referensi DTDL dan contoh untuk membantu Anda mulai menulis model DTDL Anda sendiri.

DTDL didasarkan pada JSON-LD dan tidak bergantung pada bahasa pemrogram. DTDL tidak eksklusif untuk Azure Digital Twins. Ini juga digunakan untuk mewakili data perangkat di layanan IoT lain seperti IoT Plug and Play.

Sisa artikel ini merangkum bagaimana bahasa digunakan di Azure Digital Twins.

Versi DTDL yang didukung

Azure Digital Twins mendukung DTDL versi 2 dan 3 (masing-masing dipersingkat dalam dokumentasi ke v2 dan v3). V3 adalah pilihan yang direkomendasikan untuk pemodelan di Azure Digital Twins berdasarkan kemampuannya yang diperluas, termasuk:

Relaksasi versi DTMI
Dukungan array untuk properti
Peningkatan batas untuk pewarisan model
Ekstensi fitur
- Kemampuan untuk menghias skema antarmuka kustom dengan jenis semantik (disediakan dengan ekstensi QuantitativeTypes)

Jika fitur-fitur ini dibahas dalam dokumentasi, fitur ini disertai dengan catatan bahwa fitur tersebut hanya tersedia di DTDL v3. Untuk daftar lengkap perbedaan antara DTDL v2 dan v3, lihat Deskripsi Bahasa DTDL v3: Perubahan dari Versi 2.

Azure Digital Twins juga mendukung penggunaan campuran model v2 dan v3 dalam instans yang sama. Saat menggunakan model kedua versi bersama-sama, ingatlah batasan berikut:

Antarmuka v2 tidak dapat memperluas antarmuka v3, atau memiliki komponen dengan antarmuka v3 sebagai skemanya.
Sebaliknya, antarmuka v3 dapat memperluas antarmuka v2, dan antarmuka v3 dapat memiliki komponen dengan antarmuka v2 sebagai skemanya.
Hubungan dapat mengarah ke kedua arah, dari sumber model v2 ke target model v3, atau sebaliknya dari sumber model v3 ke target model v2.

Anda juga dapat memigrasikan model v2 yang ada ke v3. Untuk petunjuk tentang cara melakukannya, lihat Mengonversi model v2 ke v3.

Catatan

Saat ini, Azure Digital Twins Explorer sepenuhnya mendukung model DTDL v2 dan mendukung fungsionalitas terbatas untuk model DTDL v3. Di Azure Digital Twins Explorer, model DTDL v3 dapat dilihat di panel Model, dan kembar yang dibuat dengan model DTDL v3 dapat dilihat dan diedit (termasuk yang memiliki properti array). Namun, model DTDL v3 tidak akan muncul di panel Grafik Model, dan tidak dapat diimpor menggunakan Azure Digital Twins Explorer. Untuk mengimpor model DTDL v3 ke instans Anda, gunakan antarmuka pengembang lain seperti API dan SDK atau Azure CLI.

Ringkasan model

Model jenis kembaran dapat ditulis dalam editor teks apa pun. Bahasa DTDL mengikuti sintaks JSON, jadi Anda harus menyimpan model dengan ekstensi .json. Menggunakan ekstensi JSON akan memungkinkan banyak editor teks pemrograman untuk memberikan pemeriksaan sintaks dasar dan penyorotan untuk dokumen DTDL Anda. Ada juga ekstensi DTDL yang tersedia untuk Visual Studio Code.

Berikut adalah bidang dalam antarmuka model:

Bidang	Deskripsi
`@id`	Pengidentifikasi Model Digital Twin (DTMI) untuk model, dalam format `dtmi:<domain>:<unique-model-identifier>;<model-version-number>`. Di DTDL v3, nomor versi dapat dihilangkan, atau disusun sebagai nomor versi dua bagian (`<major>.<minor>`).
`@type`	Mengidentifikasi jenis informasi yang dijelaskan. Untuk antarmuka, jenisnya adalah `Interface`.
`@context`	Mengatur konteks untuk dokumen JSON. Model harus digunakan `dtmi:dtdl:context;2` untuk DTDL v2, atau `dtmi:dtdl:context;3` untuk DTDL v3. Model DTDL v3 juga dapat memberi nama ekstensi fitur tambahan di bidang ini.
`displayName`	[opsional] Memberi Anda pilihan untuk menentukan nama yang mudah diingat untuk model. Jika Anda tidak menggunakan bidang ini, model akan menggunakan nilai DTMI lengkapnya.
`contents`	Semua data antarmuka yang tersisa ditempatkan di sini, sebagai larik definisi atribut. Setiap atribut harus menyediakan `@type` (`Property`, `Relationship`, atau `Component`) untuk mengidentifikasi jenis informasi antarmuka yang dijelaskannya, lalu sekumpulan properti yang menentukan atribut aktual. Bagian berikutnya menjelaskan atribut model secara rinci.

Berikut adalah contoh model DTDL dasar. Model ini menjelaskan sebuah Rumah, dengan satu properti untuk ID. Model Rumah juga menentukan hubungan dengan model Lantai, yang dapat digunakan untuk menunjukkan bahwa kembaran Rumah tersambung ke kembaran Lantai tertentu.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "contents": [
    {
      "@type": "Property",
      "name": "id",
      "schema": "string"     
    },    
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1"
    }
  ]
}

Atribut model

Informasi utama tentang model diberikan oleh atributnya, yang didefinisikan dalam bagian contents antarmuka model.

Berikut adalah atribut yang tersedia di DTDL yang didukung di Azure Digital Twins. Antarmuka model DTDL yang digunakan untuk Azure Digital Twins mungkin berisi nol, satu, atau banyak dari masing-masing bidang berikut:

Properti - Properti adalah bidang data yang mewakili status entitas (seperti properti dalam banyak bahasa pemrogram berorientasi objek). Properti memiliki penyimpanan cadangan dan dapat dibaca kapan saja. Untuk informasi selengkapnya, lihat Properti di bawah ini.
Hubungan - Hubungan memungkinkan Anda merepresentasikan bagaimana kembaran digital dapat terlibat dengan kembaran digital lainnya. Hubungan dapat mewakili arti semantik yang berbeda, seperti contains ("lantai berisi ruangan"), cools ("hvac cools room"), isBilledTo ("kompresor ditagihkan kepada pengguna"), dan sebagainya. Hubungan memungkinkan solusi untuk memberikan grafik entitas yang saling terkait. Hubungan juga dapat memiliki properti mereka sendiri. Untuk informasi selengkapnya, lihat Hubungan di bawah.
Komponen - Komponen memungkinkan Anda membangun antarmuka model sebagai rakitan antarmuka lain, jika diinginkan. Contoh komponen adalah antarmuka front Kamera (dan antarmuka komponen lainnya Kamera) yang digunakan dalam menentukan model untuk ponsel. Pertama, tentukan antarmuka untuk frontCamera seolah-olah itu adalah modelnya sendiri, lalu Anda dapat merujuk antarmuka saat menentukan Telepon.

Gunakan komponen untuk menjelaskan sesuatu yang merupakan bagian integral dari solusi Anda tetapi tidak memerlukan identitas terpisah, dan tidak perlu dibuat, dihapus, atau disusun ulang dalam grafik kembar secara terpisah. Jika Anda ingin entitas memiliki keberadaan independen dalam grafik kembar, nyatakan mereka sebagai kembaran digital terpisah dari model yang berbeda, disambungkan oleh hubungan.

Tip

Komponen juga dapat digunakan untuk organisasi, untuk mengelompokkan set properti terkait dalam antarmuka model. Dalam situasi ini, Anda dapat menganggap setiap komponen sebagai namespace atau "folder" di dalam antarmuka.

Untuk informasi selengkapnya, lihat Komponen di bawah.

Deskripsi Bahasa DTDL v3 juga menentukan Perintah dan Telemetri, tetapi tidak satu pun digunakan di Azure Digital Twins. Perintah tidak didukung, dan Telemetri—meskipun diizinkan dalam definisi model—tidak memiliki kasus penggunaan unik dalam pemodelan Azure Digital Twins. Alih-alih menggunakan telemetri DTDL, Anda harus menggunakan properti DTDL untuk menyimpan informasi status kembar.

Catatan

Meskipun tidak perlu menentukan bidang Telemetri dalam model DTDL Anda untuk menyimpan data perangkat masuk, Azure Digital Twins dapat memancarkan peristiwa sebagai telemetri menggunakan API SendTelemetry. Ini memicu peristiwa Pesan Telemetri Digital Twin yang dapat diterima oleh penanganan aktivitas untuk mengambil tindakan pada kembar lain atau memicu layanan hilir.

Properti

Bagian ini masuk ke detail selengkapnya tentang properti dalam model DTDL.

Untuk informasi komprehensif tentang bidang yang mungkin muncul sebagai bagian dari properti, lihat Properti di Deskripsi Bahasa DTDL v3.

Catatan

Atribut writable DTDL untuk properti saat ini tidak didukung di Azure Digital Twins. Ini dapat ditambahkan ke model, tetapi Azure Digital Twins tidak akan memberlakukannya. Untuk informasi selengkapnya, lihat Catatan DTDL khusus layanan.

Skema

Sesuai DTDL, skema untuk atribut properti dapat menjadi jenis primitif standar—integer, , doublestring, dan —dan booleanjenis lainnya seperti dateTime dan duration.

Selain jenis primitif, bidang properti dapat memiliki jenis kompleks ini:

Object
Map
Enum
Array, hanya di DTDL v3. Array jenis untuk properti tidak didukung di DTDL v2.

Bidang properti dan telemetri juga dapat berupa jenis semantik, yang memungkinkan Anda untuk memberi anotasi keterangan nilai dengan unit. Di DTDL v2, jenis semantik didukung secara asli; di DTDL v3, Anda dapat menyertakannya dengan ekstensi fitur.

Contoh properti dasar

Berikut adalah contoh dasar properti pada model DTDL. Contoh ini menunjukkan properti ID dari sebuah Rumah.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "contents": [
    {
      "@type": "Property",
      "name": "id",
      "schema": "string"     
    },    
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1"
    }
  ]
}

Contoh jenis Objek Kompleks

Properti bisa dari jenis kompleks, termasuk Object jenis.

Contoh berikut menunjukkan versi lain dari model Rumah, dengan properti untuk alamatnya. address adalah objek, dengan bidangnya sendiri untuk jalan, kota, negara, dan kode pos.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {
      "@type": "Property",
      "name": "address",
      "schema": {
        "@type": "Object",
        "fields": [
          {
            "name": "street",
            "schema": "string"
          },
          {
            "name": "city",
            "schema": "string"
          },
          {
            "name": "state",
            "schema": "string"
          },
          {
            "name": "zip",
            "schema": "string"
          }
        ]
      }
    },
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1",
      "properties": [
        {
          "@type": "Property",
          "name": "lastOccupied",
          "schema": "dateTime"
        }
      ]
    }
  ]
}

Contoh jenis semantik DTDL v2

Jenis semantik adalah untuk mengekspresikan nilai dengan unit. Properti untuk Azure Digital Twins dapat menggunakan salah satu jenis semantik yang didukung oleh DTDL.

Di DTDL v2, jenis semantik didukung secara asli. Untuk informasi selengkapnya tentang jenis semantik di DTDL v2, lihat Jenis semantik dalam Deskripsi Bahasa DTDL v2. Untuk mempelajari tentang jenis semantik di DTDL v3, lihat ekstensi fitur QuantitativeTypes DTDL v3.

Contoh berikut menunjukkan model Sensor DTDL v2 dengan properti jenis semantik untuk Kelembaban dan Suhu.

{
  "@id": "dtmi:com:adt:dtsample:v2sensor;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;2",
  "displayName": "Sensor (v2 model)",
  "contents": [
    {
      "@type": ["Property", "Temperature"],
      "name": "Temperature",
      "schema": "double",
      "unit": "degreeFahrenheit"    
    },
    {
      "@type": ["Property", "Humidity"],
      "name": "Humidity",
      "schema": "double",
      "unit": "gramPerCubicMetre" 
    }
  ]
}

Penting

"Properti" harus menjadi elemen pertama dari @type array, diikuti oleh jenis semantik. Jika tidak, bidang mungkin tidak terlihat di Azure Digital Twins Explorer.

Hubungan

Bagian ini membahas lebih detail tentang hubungan dalam model DTDL.

Untuk daftar lengkap bidang yang mungkin muncul sebagai bagian dari hubungan, lihat Hubungan dalam Deskripsi Bahasa DTDL v3.

Catatan

Atribut writableDTDL , minMultiplicity, dan maxMultiplicity untuk hubungan saat ini tidak didukung di Azure Digital Twins. Mereka dapat ditambahkan ke model, tetapi Azure Digital Twins tidak akan memberlakukannya. Untuk informasi selengkapnya, lihat Catatan DTDL khusus layanan.

Contoh hubungan dasar

Berikut adalah contoh dasar hubungan pada model DTDL. Contoh ini menunjukkan hubungan pada model Rumah yang memungkinkannya tersambung ke model Lantai.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "contents": [
    {
      "@type": "Property",
      "name": "id",
      "schema": "string"     
    },    
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1"
    }
  ]
}

Catatan

Untuk hubungan, @id adalah bidang opsional. Jika tidak ada @id yang disediakan, prosesor antarmuka kembar digital akan menetapkannya.

Hubungan yang ditargetkan dan tidak ditargetkan

Hubungan dapat ditentukan dengan atau tanpa target. Target menentukan jenis kembaran mana yang dapat dicapai oleh hubungan tersebut. Misalnya, Anda mungkin menyertakan target untuk menentukan bahwa model Rumah hanya dapat memiliki rel_has_floors hubungan dengan kembar yang merupakan kembar Lantai.

Terkadang, Anda mungkin ingin menentukan suatu hubungan tanpa target tertentu, sehingga hubungan tersebut dapat tersambung ke banyak jenis kembaran yang berbeda.

Berikut adalah contoh hubungan pada model DTDL yang tidak memiliki target. Dalam contoh ini, hubungan adalah untuk menentukan sensor apa yang mungkin dimiliki suatu Ruangan, dan hubungan tersebut dapat tersambung ke jenis apa pun.

{
  "@id": "dtmi:com:adt:dtsample:room;1",
  "@type": "Interface",
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:quantitativeTypes;1"
  ],
  "displayName": "Room",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {
      "@type": ["Property", "Humidity"],
      "name": "humidity",
      "schema": "double",
      "unit": "gramPerCubicMetre"
    },
    {
      "@type": "Component",
      "name": "thermostat",
      "schema": "dtmi:com:adt:dtsample:thermostat;1"
    },
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:room:rel_has_sensors;1",
      "name": "rel_has_sensors",
      "displayName": "Room has sensors"

Properti hubungan

DTDL juga memungkinkan hubungan memiliki propertinya sendiri. Saat Anda menentukan hubungan dalam model DTDL, hubungan dapat memiliki bidangnya sendiri properties di mana Anda dapat menentukan properti kustom untuk menjelaskan status khusus hubungan.

Contoh berikut menunjukkan versi lain dari model Rumah, di mana hubungan rel_has_floors memiliki properti yang mewakili kapan Lantai terkait terakhir ditempati.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {
      "@type": "Property",
      "name": "address",
      "schema": {
        "@type": "Object",
        "fields": [
          {
            "name": "street",
            "schema": "string"
          },
          {
            "name": "city",
            "schema": "string"
          },
          {
            "name": "state",
            "schema": "string"
          },
          {
            "name": "zip",
            "schema": "string"
          }
        ]
      }
    },
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1",
      "properties": [
        {
          "@type": "Property",
          "name": "lastOccupied",
          "schema": "dateTime"
        }
      ]
    }
  ]
}

Komponen

Bagian ini membahas lebih detail tentang komponen dalam model DTDL.

Untuk daftar lengkap bidang yang mungkin muncul sebagai bagian dari komponen, lihat Komponen dalam Deskripsi Bahasa DTDL v3.

Contoh komponen dasar

Berikut adalah contoh dasar komponen pada model DTDL. Contoh ini menunjukkan model Ruangan yang menggunakan komponen termostat.

[
  {
    "@id": "dtmi:com:adt:dtsample:room;1",
    "@type": "Interface",
    "@context": [
      "dtmi:dtdl:context;3",
      "dtmi:dtdl:extension:quantitativeTypes;1"
    ],
    "displayName": "Room",
    "extends": "dtmi:com:adt:dtsample:core;1",
    "contents": [
      {
        "@type": ["Property", "Humidity"],
        "name": "humidity",
        "schema": "double",
        "unit": "gramPerCubicMetre"
      },
      {
        "@type": "Component",
        "name": "thermostat",
        "schema": "dtmi:com:adt:dtsample:thermostat;1"
      },
      {
        "@type": "Relationship",
        "@id": "dtmi:com:adt:dtsample:room:rel_has_sensors;1",
        "name": "rel_has_sensors",
        "displayName": "Room has sensors"
      }
    ]
  },
  {
    "@context": [
      "dtmi:dtdl:context;3",
      "dtmi:dtdl:extension:quantitativeTypes;1"
    ],
    "@id": "dtmi:com:adt:dtsample:thermostat;1",
    "@type": "Interface",
    "displayName": "thermostat",
    "contents": [
      {
        "@type": ["Property", "Temperature"],
        "name": "temperature",
        "schema": "double",
        "unit": "degreeFahrenheit"
      }
    ]
  }
]

Jika model lain dalam solusi ini juga harus berisi termostat, mereka dapat merujuk model termostat yang sama sebagai komponen dalam definisi mereka sendiri, seperti yang dilakukan Ruang.

Penting

Antarmuka komponen (termostat dalam contoh di atas) harus didefinisikan dalam array yang sama dengan antarmuka apa pun yang menggunakannya (Ruang dalam contoh di atas) agar referensi komponen dapat ditemukan.

Warisan model

Terkadang, Anda mungkin ingin mengkhususkan model lebih jauh. Misalnya, mungkin berguna untuk memiliki model Ruangan generik, dan varian khusus ConferenceRoom dan Gimnasium. Untuk mengekspresikan spesialisasi, DTDL mendukung pewarisan. Antarmuka dapat mewarisi dari satu atau lebih antarmuka lainnya. Hal ini dilakukan dengan menambahkan bidang extends ke model.

Bagian extends adalah nama antarmuka, atau larik nama antarmuka (memungkinkan antarmuka yang diperluas untuk mewarisi dari beberapa model induk). Induk tunggal dapat berfungsi sebagai model dasar untuk beberapa antarmuka yang diperluas.

Catatan

Di DTDL v2, masing-masing extends dapat memiliki paling banyak dua antarmuka yang tercantum untuk itu. Di DTDL v3, tidak ada batasan jumlah nilai langsung untuk extends.

Di DTDL v2 dan v3, batas kedalaman total untuk extends hierarki adalah 10.

Contoh berikut membayangkan kembali model Rumah dari contoh DTDL sebelumnya sebagai subjenis model "inti" yang lebih besar. Model induk (Core) ditentukan terlebih dahulu, lalu model anak (Home) dibangun di atasnya dengan menggunakan extends.

{
    "@id": "dtmi:com:adt:dtsample:core;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "displayName": "Core",
    "contents": [
        {
            "@type": "Property",
            "name": "id",
            "schema": "string"
        },
        {
            "@type": "Property",
            "name": "name",
            "schema": "string"
        }
    ]
}

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {

Dalam hal ini, Inti mengkontribusikan ID dan nama ke Rumah. Model lain juga dapat memperluas model Inti untuk mendapatkan properti ini juga. Berikut adalah model Ruangan yang memperluas antarmuka induk yang sama:

{
  "@id": "dtmi:com:adt:dtsample:room;1",
  "@type": "Interface",
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:quantitativeTypes;1"
  ],
  "displayName": "Room",

Setelah pewarisan diterapkan, antarmuka perluasan mengekspos semua properti dari seluruh rantai pewarisan.

Antarmuka yang diperluas tidak dapat mengubah definisi antarmuka induk apa pun; antarmuka hanya dapat menambah definisi. Antarmuka juga tidak dapat menentukan ulang kemampuan yang sudah ditentukan di salah satu antarmuka induknya (bahkan jika kemampuan ditentukan sama). Misalnya, jika antarmuka induk mendefinisikan double properti mass, antarmuka yang diperluas tidak dapat berisi deklarasi mass, bahkan jika itu juga .double

Ekstensi fitur DTDL v3

DTDL v3 memungkinkan ekstensi bahasa yang menentukan kelas metamodel tambahan, yang dapat Anda gunakan untuk menulis model yang lebih kaya. Bagian ini menjelaskan kelas ekstensi fitur yang dapat Anda gunakan untuk menambahkan fitur non-inti ke model DTDL v3 Anda.

Setiap ekstensi fitur diidentifikasi oleh penentu konteksnya, yang merupakan nilai Pengidentifikasi Model Kembar Digital (DTMI) unik. Untuk mengaktifkan ekstensi fitur dalam model, tambahkan penentu konteks ekstensi ke bidang model @context (bersama penentu konteks DTDL umum ).dtmi:dtdl:context;3 Anda dapat menambahkan beberapa ekstensi fitur ke model yang sama.

Berikut adalah contoh tampilan bidang tersebut @context dengan ekstensi fitur. Kutipan berikut berasal dari model yang menggunakan ekstensi QuantitativeTypes dan ekstensi Anotasi.

  "@context": [
      "dtmi:dtdl:context;3",
      "dtmi:dtdl:extension:quantitativeTypes;1",
      "dtmi:dtdl:extension:annotation;1"
  ]

Setelah menambahkan ekstensi fitur ke model, Anda akan memiliki akses ke jenis adjunct ekstensi tersebut dalam model. Anda dapat menambahkan jenis adjunct ke @type bidang elemen DTDL, untuk memberikan elemen kemampuan tambahan. Jenis adjunct dapat menambahkan properti tambahan ke elemen .

Misalnya, berikut adalah kutipan dari model yang menggunakan ekstensi Anotasi. Ekstensi ini memiliki jenis adjunct yang disebut ValueAnnotation, yang ditambahkan dalam contoh di bawah ini ke elemen properti. Menambahkan jenis ajunct ini ke elemen properti memungkinkan elemen memiliki bidang tambahan annotates , yang digunakan untuk menunjukkan properti lain yang dianotasi oleh elemen ini.

{
  "@type": [ "Property", "ValueAnnotation" ],
  "name": "currentTempAccuracy",
  "annotates": "currentTemp",
  "schema": "double"
  },

Bagian lainnya menjelaskan ekstensi Anotasi dan ekstensi fitur DTDL v3 lainnya secara lebih rinci.

Ekstensi anotasi

Ekstensi Anotasi digunakan untuk menambahkan metadata kustom ke elemen properti dalam model DTDL v3. Penentu konteksnya adalah dtmi:dtdl:extension:annotation;1.

Ekstensi ini mencakup ValueAnnotation jenis adjunct, yang dapat ditambahkan ke elemen properti DTDL. Jenis menambahkan ValueAnnotation satu bidang ke elemen , annotates, yang memungkinkan Anda memberi nama properti lain yang diannotasi oleh elemen saat ini.

Untuk detail selengkapnya dan contoh ekstensi ini, lihat Ekstensi anotasi di Deskripsi Bahasa DTDL v3.

Ekstensi historisasi

Ekstensi Historisasi digunakan untuk menunjuk properti dalam model DTDL v3 sebagai sesuatu yang harus di historis (yang berarti urutan historis nilainya harus dicatat, bersama dengan waktu di mana nilai berubah). Penentu konteksnya adalah dtmi:dtdl:extension:historization;1.

Ekstensi ini mencakup Historized jenis ajunct, yang dapat ditambahkan sebagai jenis bersama ke elemen properti DTDL untuk menunjukkan bahwa layanan harus mempertahankan nilai historis elemen dan membuatnya tersedia untuk kueri dan analitik. Jenis Historized adjunct tidak menambahkan bidang apa pun ke elemen .

Untuk detail selengkapnya dan contoh ekstensi ini, lihat Ekstensi Historisasi di Deskripsi Bahasa DTDL v3.

Mengesampingkan ekstensi

Ekstensi penimpaan digunakan untuk mengambil alih properti dalam model DTDL V3 dengan nilai instans. Ini digunakan dalam kombinasi dengan ekstensi anotasi, dan penentu konteksnya adalah dtmi:dtdl:extension:overriding;1.

Ekstensi ini mencakup Override jenis ajunct, yang dapat ditambahkan ke properti DTDL yang juga ditiru dengan ValueAnnotation (dari ekstensi anotasi). Jenis menambahkan Override satu bidang ke elemen , overrides, yang memungkinkan Anda untuk memberi nama bidang pada elemen anotasi untuk ditimpa oleh nilai elemen saat ini.

Untuk detail selengkapnya dan contoh ekstensi ini, lihat Mengganti ekstensi di Deskripsi Bahasa DTDL v3.

Ekstensi QuantitativeTypes

Ekstensi QuantitativeTypes digunakan untuk mengaktifkan jenis semantik, jenis unit, dan unit dalam model DTDL v3. Penentu konteksnya adalah dtmi:dtdl:extension:quantitativeTypes;1.

Ekstensi ini memungkinkan penggunaan banyak jenis semantik sebagai jenis ajunct, yang dapat ditambahkan ke CommandRequest, Bidang, MapValue, atau properti di DTDL v3. Jenis semantik menambahkan satu bidang ke elemen , unit, yang menerima unit valid yang sesuai dengan jenis semantik.

Untuk detail selengkapnya tentang ekstensi, termasuk contoh dan daftar lengkap jenis dan unit semantik yang didukung, lihat ekstensi QuantitativeTypes di Deskripsi Bahasa DTDL v3.

Catatan DTDL khusus layanan

Tidak semua layanan yang menggunakan DTDL menerapkan fitur DTDL yang sama persis. Ada beberapa fitur DTDL yang saat ini tidak didukung Oleh Azure Digital Twins, termasuk:

Perintah DTDL
Atribut writable pada properti atau hubungan. Meskipun atribut ini dapat diatur sesuai spesifikasi DTDL, nilainya tidak digunakan oleh Azure Digital Twins. Sebaliknya, ini selalu berlaku sebagai dapat ditulis oleh klien eksternal yang memiliki izin menulis umum ke layanan Azure Digital Twins.
Properti minMultiplicity dan maxMultiplicity pada hubungan. Meskipun atribut ini dapat diatur sesuai spesifikasi DTDL, nilai tidak diberlakukan oleh Azure Digital Twins.

Agar model DTDL kompatibel dengan Azure Digital Twins, model tersebut juga harus memenuhi persyaratan berikut:

Semua elemen DTDL tingkat atas dalam model harus berjenis Interface. Persyaratan tersebut ada karena API model Azure Digital Twins dapat menerima objek JSON yang mewakili antarmuka atau larik antarmuka. Akibatnya, tidak ada jenis elemen DTDL lain yang diizinkan di tingkat atas.
DTDL untuk Azure Digital Twins tidak boleh menentukan perintah apa pun.
Azure Digital Twins hanya memungkinkan satu tingkat lapisan komponen, yang berarti bahwa antarmuka yang digunakan sebagai komponen tidak dapat memiliki komponen itu sendiri.
Antarmuka tidak dapat ditentukan secara sebaris dalam antarmuka DTDL lainnya; antarmuka harus didefinisikan sebagai entitas tingkat atas yang terpisah dengan ID mereka sendiri. Kemudian, ketika antarmuka lain ingin menyertakan antarmuka tersebut sebagai komponen atau melalui pewarisan, antarmuka dapat mereferensikan ID.

Alat pemodelan dan praktik terbaik

Bagian ini menjelaskan pertimbangan dan rekomendasi tambahan untuk pemodelan.

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?.

Pertimbangkan implikasi kueri

Saat mendesain model untuk mencerminkan entitas di lingkungan Anda, akan berguna untuk melihat ke depan dan mempertimbangkan implikasi kueri dari desain Anda. Anda mungkin ingin mendesain properti dengan cara yang akan menghindari tataan hasil besar dari traversal grafik. Anda mungkin juga ingin memodelkan hubungan yang perlu dijawab dalam satu kueri sebagai hubungan tingkat tunggal.

Memvalidasi model

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 dan menghapus model secara massal

Setelah selesai membuat, memperluas, atau memilih model, Anda perlu mengunggahnya ke instans Azure Digital Twins agar tersedia untuk digunakan dalam solusi Anda.

Anda dapat mengunggah banyak model dalam satu panggilan API menggunakan API Impor Pekerjaan. 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. Untuk instruksi dan contoh terperinci yang menggunakan API ini, lihat instruksi impor massal untuk model.

Alternatif untuk Api Pekerjaan Impor adalah sampel pengunggah Model, yang menggunakan API model individual untuk mengunggah beberapa file model sekaligus. Sampel juga mengimplementasikan pengulangan ulang otomatis untuk mengatasi dependensi model. Saat ini hanya berfungsi dengan DTDL versi 2.

Jika Anda perlu menghapus semua model dalam instans Azure Digital Twins sekaligus, Anda dapat menggunakan sampel Model Deleter. Ini adalah proyek yang berisi logika rekursif untuk menangani dependensi model melalui proses penghapusan. Saat ini hanya berfungsi dengan DTDL versi 2.

Atau, jika Anda ingin menghapus data dalam instans dengan menghapus semua model bersama dengan semua kembar dan hubungan, Anda dapat menggunakan Delete Jobs API.

Memvisualisasikan model

Setelah mengunggah model ke instans Azure Digital Twins, Anda dapat menggunakan Azure Digital Twins Explorer untuk melihatnya. Penjelajah berisi daftar semua model dalam instans, serta grafik model yang menggambarkan bagaimana mereka berhubungan satu sama lain, termasuk pewarisan dan hubungan model.

Catatan

Berikut adalah contoh tampilan grafik model:

Untuk informasi selengkapnya tentang pengalaman model di Azure Digital Twins Explorer, lihat Menjelajahi model dan Grafik Model.

Langkah berikutnya

Pelajari tentang pembuatan model berdasarkan ontologi standar industri: Apa itu ontologi?
Pelajari lebih lanjut tentang mengelola model dengan operasi API: Mengelola model DTDL
Pelajari tentang bagaimana model digunakan untuk membuat kembaran digital: Kembaran digital dan grafik kembar

Pelajari tentang model kembar dan cara menentukannya di Azure Digital Twins

Bahasa Definisi Kembaran Digital (DTDL) untuk model

Versi DTDL yang didukung

Ringkasan model

Atribut model

Properti

Skema

Contoh properti dasar

Contoh jenis Objek Kompleks

Contoh jenis semantik DTDL v2

Hubungan

Contoh hubungan dasar

Hubungan yang ditargetkan dan tidak ditargetkan

Properti hubungan

Komponen

Contoh komponen dasar

Warisan model

Ekstensi fitur DTDL v3

Ekstensi anotasi

Ekstensi historisasi

Mengesampingkan ekstensi

Ekstensi QuantitativeTypes

Catatan DTDL khusus layanan

Alat pemodelan dan praktik terbaik

Menggunakan ontologi standar industri yang ada

Pertimbangkan implikasi kueri

Memvalidasi model

Mengunggah dan menghapus model secara massal

Memvisualisasikan model

Langkah berikutnya

Sumber Daya Tambahan: