Kembar digital dan grafik kembar mereka

  • Artikel

Artikel ini menjelaskan apa kembar digital dalam konteks Azure Digital Twins, dan bagaimana hubungan di antara mereka dapat membentuk grafik kembar. Dalam solusi Azure Digital Twins, entitas di lingkungan Anda diwakili oleh kembar digital. Kembar digital adalah instans salah satu model yang Anda tentukan sendiri. Ini dapat dihubungkan ke kembar digital lainnya melaluihubungan untuk membentuk grafik kembar: grafik kembar ini adalah representasi dari seluruh lingkungan Anda.

Tip

"Azure Digital Twins" mengacu pada layanan Azure ini secara keseluruhan. "Kembaran digital" atau hanya "kembaran" mengacu pada simpul kembar individu di dalam instans layanan Anda.

Digital twins

Sebelum Anda dapat membuat kembaran digital di instans Azure Digital Twins, Anda harus memiliki model yang diunggah ke layanan. Model menjelaskan serangkaian properti dan hubungan yang dapat dimiliki kembar tertentu, antara lain. Untuk jenis informasi yang ditentukan dalam model, lihat Model kustom.

Setelah membuat dan mengunggah model, aplikasi klien Anda dapat membuat instance dari jenis tersebut. Contoh ini adalah kembaran digital. Misalnya, setelah membuat model Lantai, Anda dapat membuat satu atau beberapa kembar digital yang menggunakan tipe ini (seperti kembaran tipe Lantai yang disebut GroundFloor, yang lain disebut Floor2, dan seterusnya).

Catatan

Kembar digital di Azure Digital Twins berbeda dari kembar perangkat di IoT Hub. Kembar perangkat IoT Hub seringkali berfokus pada menggambarkan aspek dan kemampuan perangkat itu sendiri, sementara kembar di Azure Digital Twins adalah representasi konseptual yang lebih dapat menyimpan wawasan yang ditentukan pengguna tentang perangkat atau banyak perangkat terkait.

Perangkat di IoT Hub dapat dihubungkan ke Azure Digital Twins sebagai bagian dari solusi end-to-end yang mewakili perangkat Anda di seluruh layanan.

Hubungan: grafik kembar digital

Kembar terhubung ke dalam grafik kembar oleh hubungan mereka. Hubungan yang dapat didefinisikan oleh kembar sebagai bagian dari modelnya.

Misalnya, Lantai model mungkin menentukan contains hubungan yang menargetkan kembar jenis Ruangan. Dengan definisi ini, Azure Digital Twins akan memungkinkan Anda untuk membuat contains hubungan dari kembar Lantai apa pun ke kembar Kamar apa pun (termasuk kembar yang merupakan subjenis Kamar).

Hasil dari proses ini adalah seperangkat simpul (kembar digital) yang terhubung melalui tepi (hubungan mereka) dalam grafik.

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 sample models and twins.

Buat dengan API

Bagian ini menunjukkan bagaimana rasanya membuat kembar digital dan hubungan dari aplikasi klien. Ini berisi contoh .NET SDK yang menggunakan API DigitalTwins, untuk memberikan konteks lebih lanjut tentang apa yang terjadi di dalam masing-masing konsep ini.

Membuat digital twin

Di bawah ini adalah cuplikan kode klien yang menggunakan API DigitalTwins untuk membuat instans twin dari jenis Room dengan twinId yang ditentukan saat pembuatan instans.

Anda dapat menginisialisasi properti kembaran saat dibuat, atau mengaturnya nanti. Untuk membuat kembar dengan properti yang diinisialisasi, buat dokumen JSON yang menyediakan nilai inisialisasi yang diperlukan.

// Define a custom model type for the twin to be created

internal class CustomDigitalTwin
{
    [JsonPropertyName(DigitalTwinsJsonPropertyNames.DigitalTwinId)]
    public string Id { get; set; }

    [JsonPropertyName(DigitalTwinsJsonPropertyNames.DigitalTwinETag)]
    public string ETag { get; set; }

    [JsonPropertyName("temperature")]
    public double Temperature { get; set; }

    [JsonPropertyName("humidity")]
    public double Humidity{ get; set; }
}

// Initialize properties and create the twin
public class TwinOperationsCreateTwin
{
    public async Task CreateTwinAsync(DigitalTwinsClient client)
    {
        // Initialize the twin properties
        var myTwin = new CustomDigitalTwin
        {
            Temperature = 25.0,
            Humidity = 50.0,
        };

        // Create the twin
        const string twinId = "<twin-ID>";
        Response<CustomDigitalTwin> response = await client.CreateOrReplaceDigitalTwinAsync(twinId, myTwin);
        Console.WriteLine($"Temperature value: {response.Value.Temperature}");
    }
}

Anda juga dapat menggunakan kelas pembantu yang dipanggil BasicDigitalTwin untuk menyimpan bidang properti di objek "kembar" secara lebih langsung, sebagai alternatif untuk menggunakan kamus. Untuk informasi selengkapnya tentang kelas pembantu dan contoh penggunaannya, lihat Membuat kembar digital.

Catatan

Meskipun properti kembar diperlakukan sebagai opsional dan dengan demikian tidak harus diinisialisasi, komponen apa pun pada kembar perlu diatur ketika kembar dibuat. Mereka bisa menjadi objek kosong, tetapi komponen itu sendiri harus ada.

Buat hubungan

Berikut ini beberapa contoh kode klien yang menggunakan DigitalTwins API untuk membangun hubungan dari satu kembaran digital (kembar "sumber") ke kembaran digital lainnya (kembaran "target").

public async Task CreateRelationship(DigitalTwinsClient client)
{
    var rel = new BasicRelationship
    {
        TargetId = "myTargetTwin",
        Name = "contains", // a relationship with this name must be defined in the model
        // Initialize properties
        Properties =
        {
            { "active", true },
        },
    };
    await client.CreateOrReplaceRelationshipAsync("mySourceTwin", "rel001", rel);
}

Membuat kembar dan hubungan secara massal dengan API Impor Pekerjaan

Anda dapat mengunggah banyak kembar dan hubungan dalam satu panggilan API menggunakan API Impor Pekerjaan. Kembar dan hubungan yang dibuat dengan API ini dapat secara opsional menyertakan inisialisasi properti mereka. Untuk instruksi dan contoh terperinci yang menggunakan API ini, lihat instruksi impor massal untuk kembar dan hubungan.

Menghapus elemen grafik

Untuk menghapus kembar dan hubungan tertentu, gunakan DIGITALTwins Delete dan DigitalTwins DeleteRelationship API (juga tersedia sebagai perintah CLI dan panggilan SDK).

Untuk menghapus semua model, kembar, dan hubungan dalam instans sekaligus, gunakan Delete Jobs API.

Representasi JSON dari elemen grafik

Data kembar digital dan data hubungan keduanya disimpan dalam format JSON, yang berarti bahwa saat Anda meminta grafik kembar dalam instans Azure Digital Twins, hasilnya akan menjadi representasi JSON dari kembaran digital dan hubungan yang Anda miliki dibuat.

Format JSON kembar digital

Ketika dinyatakan sebagai objek JSON, kembar digital akan menampilkan bidang berikut:

Nama bidang Deskripsi
$dtId Untai yang disediakan pengguna yang mewakili ID dari kembaran digital
$etag Bidang HTTP standar yang ditetapkan oleh server web
$metadata.$model ID antarmuka model yang mencirikan kembar digital ini
$metadata.<property-name> Informasi metadata lainnya tentang properti kembar digital
$metadata.<property-name>.lastUpdateTime Tanggal/waktu pesan pembaruan properti diproses oleh Azure Digital Twins
$metadata.<property-name>.sourceTime Properti opsional yang dapat ditulis yang mewakili tanda waktu ketika pembaruan properti diamati di dunia nyata. Properti ini hanya dapat ditulis menggunakan versi 2022-05-31 dari API/SDK Azure Digital Twins dan nilai harus mematuhi format tanggal dan waktu ISO 8601. Untuk informasi selengkapnya tentang cara memperbarui properti ini, lihat Memperbarui sourceTime properti.
<property-name> Nilai properti di JSON (string, jenis angka, atau objek)
$relationships URL jalur ke pengumpulan hubungan. Bidang ini tidak ada jika kembar digital tidak memiliki tepi hubungan keluar.
<component-name> Objek JSON yang berisi nilai properti dan metadata komponen, mirip dengan objek akar. Obyek ini ada meskipun komponen tak memiliki properti.
<component-name>.$metadata Informasi metadata untuk komponen, mirip dengan tingkat akar $metadata
<component-name>.<property-name> Nilai properti komponen di JSON (string, jenis angka, atau objek)

Berikut adalah contoh kembar digital yang diformat sebagai objek JSON. Kembar ini memiliki dua sifat, Kelembaban dan Suhu, dan komponen yang disebut Termostat.

{
    "$dtId": "myRoomID",
    "$etag": "W/\"8e6d3e89-1166-4a1d-9a99-8accd8fef43f\"",
    "$metadata": {
        "$model": "dtmi:example:Room23;1",
        "Humidity": {
          "lastUpdateTime": "2021-11-30T18:47:53.7648958Z"
        },
        "Temperature": {
          "lastUpdateTime": "2021-11-30T18:47:53.7648958Z"
        }
    },
    "Humidity": 55,
    "Temperature": 35,
    "Thermostat": {
        "$metadata": {}
    }

Format Hubungan JSON

Saat direpresentasikan sebagai objek JSON, hubungan dari kembaran digital akan menampilkan bidang berikut:

Nama bidang Deskripsi
$relationshipId Untai yang disediakan pengguna yang mewakili ID hubungan ini. Untai ini unik dalam konteks kembar digital sumber, yang juga berarti sourceId + relationshipId unik dalam konteks instans Azure Digital Twins.
$etag Bidang HTTP standar yang ditetapkan oleh server web
$sourceId ID dari kembar digital sumber
$targetId ID dari kembar digital target
$relationshipName Nama hubungan
<property-name> [Opsional] Nilai properti hubungan ini, di JSON (string, jenis angka, atau objek)

Berikut adalah contoh hubungan yang diformat sebagai objek JSON:

{
  "$relationshipId": "relationship-01",
  "$etag": "W/\"506e8391-2b21-4ac9-bca3-53e6620f6a90\"",
  "$sourceId": "GroundFloor",
  "$targetId": "Cafe",
  "$relationshipName": "contains",
  "startDate": "2020-02-04"
}

Langkah berikutnya

Lihat cara mengelola elemen grafik dengan Azure Digital Twin API:

Atau, pelajari tentang mengkueri grafik kembar Azure Digital Twins untuk informasi: