Kelola twin digital
Entitas di lingkungan Anda diwakili oleh twin digital. Mengelola kembar digital Anda mungkin termasuk pembuatan, modifikasi, dan penghapusan.
Artikel ini berfokus pada pengelolaan kembaran digital; untuk bekerja dengan hubungan dan grafik kembar secara keseluruhan, lihat Cara: Mengelola grafik kembar dengan hubungan.
Tip
Semua fungsi SDK hadir dalam versi sinkron dan asinkron.
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:
Membuat twin digital
Untuk membuat twin, Anda menggunakan metode CreateOrReplaceDigitalTwinAsync() pada klien layanan seperti ini:
await client.CreateOrReplaceDigitalTwinAsync<BasicDigitalTwin>(twinId, initData);
Untuk membuat twin digital, Anda harus menyediakan:
- Nilai ID yang ingin Anda tetapkan ke kembar digital (Anda menentukan ID itu saat kembarannya dibuat)
- Model yang ingin Anda gunakan
- Setiap inisialisasi data kembar yang diinginkan, termasuk...
- Properti (inisialisasi opsional): Anda dapat mengatur nilai awal untuk properti kembar digital jika Anda mau. Properti diperlakukan secara opsional dan dapat diatur nanti, tetapi properti tersebut tidak akan muncul sebagai bagian dari kembarannya hingga properti tersebut diatur.
- Komponen (inisialisasi diperlukan jika ada pada kembaran): Jika kembaran Anda berisi komponen apa pun, ini harus diinisialisasi saat kembaran dibuat. Komponen dapat berupa objek kosong, tetapi komponen itu sendiri harus ada.
Model dan nilai properti awal apa pun disediakan melalui parameter initData, yang merupakan string JSON yang berisi data yang relevan. Untuk informasi selengkapnya tentang penataan objek ini, lanjutkan ke bagian berikutnya.
Tip
Setelah membuat atau memperbarui twin, mungkin ada latensi hingga 10 detik sebelum perubahan tersebut muncul dalam kueri. GetDigitalTwin API (dijelaskan nanti dalam artikel ini) tidak mengalami penundaan ini, jadi jika Anda memerlukan respons instan, gunakan panggilan API daripada mengkueri untuk melihat twin yang baru dibuat.
Menginisialisasi model dan properti
Anda dapat menginisialisasi properti twin pada saat twin dibuat.
API pembuatan twin menerima objek yang diserialkan menjadi deskripsi JSON yang valid dari properti twin. Lihat Kembaran digital dan grafik kembar untuk deskripsi format JSON untuk kembaran.
Pertama, Anda dapat membuat objek data untuk mewakili twin dan data propertinya. Anda dapat membuat objek parameter baik secara manual, atau dengan menggunakan kelas pembantu yang disediakan. Berikut adalah contoh masing-masing.
Membuat twin menggunakan data yang dibuat secara manual
Tanpa menggunakan kelas pembantu kustom apa pun, Anda dapat mewakili properti twin dalam Dictionary<string, object>, di mana string adalah nama properti dan object adalah objek yang mewakili properti dan nilainya.
// 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}");
}
}
Membuat twin dengan kelas pembantu
Kelas pembantu BasicDigitalTwin memungkinkan Anda untuk menyimpan bidang properti di objek "twin" secara langsung. Anda mungkin masih ingin membuat daftar properti menggunakan Dictionary<string, object>, yang kemudian dapat ditambahkan ke objek kembar secara CustomProperties langsung.
string twinId = "myTwinID";
var initData = new BasicDigitalTwin
{
Id = twinId,
Metadata = { ModelId = "dtmi:example:Room;1" },
// Initialize properties
Contents =
{
{ "Temperature", 25.0 },
{ "Humidity", 50.0 },
},
};
await client.CreateOrReplaceDigitalTwinAsync<BasicDigitalTwin>(twinId, initData);
Catatan
Objek BasicDigitalTwin dilengkapi dengan bidang Id. Anda dapat mengosongkan bidang ini, tetapi jika menambahkan nilai ID, bidang harus cocok dengan parameter ID yang diteruskan ke panggilan CreateOrReplaceDigitalTwinAsync(). Contohnya:
twin.Id = "myRoomId";
Membuat kembar secara massal dengan API Pekerjaan Impor
Anda dapat menggunakan API Impor Pekerjaan untuk membuat banyak kembar sekaligus dalam satu panggilan API. Metode ini memerlukan penggunaan Azure Blob Storage, dan menulis izin di instans Azure Digital Twins Anda untuk kembar dan pekerjaan massal.
Tip
API Pekerjaan Impor juga memungkinkan model 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 kembar secara massal, Anda perlu menyusun kembar Anda (dan sumber daya lain yang disertakan dalam pekerjaan impor massal) sebagai file NDJSON . Bagian Twins ini muncul setelah bagian Models (dan sebelum bagian Relationships ). Kembar yang ditentukan dalam file dapat mereferensikan model yang ditentukan dalam file ini atau sudah ada dalam instans, dan mereka dapat secara opsional menyertakan inisialisasi properti kembar.
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:
Kemudian, file dapat digunakan dalam panggilan Api Pekerjaan Impor. Anda menyediakan URL penyimpanan blob file input, dan URL penyimpanan blob baru untuk menunjukkan di mana Anda ingin log output disimpan setelah layanan membuatnya.
Mendapatkan data untuk twin digital
Anda dapat mengakses detail twin digital apa pun dengan memanggil metode GetDigitalTwin() seperti ini:
Response<BasicDigitalTwin> twinResponse = await client.GetDigitalTwinAsync<BasicDigitalTwin>(twinId);
twin = twinResponse.Value;
Panggilan ini menampilkan data twin sebagai jenis objek yang diketik dengan kuat seperti BasicDigitalTwin. BasicDigitalTwin adalah kelas pembantu serialisasi yang disertakan dengan SDK, yang mengembalikan metadata dan properti kembar inti dalam bentuk yang disiapkan. Anda selalu dapat mendeserialisasi data kembar menggunakan perpustakaan JSON pilihan Anda, seperti System.Text.Json atau Newtonsoft.Json. Namun, untuk akses dasar ke kembaran, kelas pembantu dapat membuatnya lebih mudah.
Catatan
BasicDigitalTwin menggunakan System.Text.Json atribut. Untuk menggunakan BasicDigitalTwin dengan digitalTwinsClient Anda, Anda harus menginisiasi klien dengan konstruktor default, atau, jika Anda ingin menyesuaikan opsi serializer, gunakan JsonObjectSerializer.
Kelas BasicDigitalTwin pembantu juga mengizinkan Anda mengakses properti yang ditentukan pada kembar melalui Dictionary<string, object>. Untuk mencantumkan properti kembar, Anda bisa menggunakan:
BasicDigitalTwin twin;
Response<BasicDigitalTwin> twinResponse = await client.GetDigitalTwinAsync<BasicDigitalTwin>(twinId);
twin = twinResponse.Value;
Console.WriteLine($"Model id: {twin.Metadata.ModelId}");
foreach (string prop in twin.Contents.Keys)
{
if (twin.Contents.TryGetValue(prop, out object value))
Console.WriteLine($"Property '{prop}': {value}");
}
Hanya properti yang telah diatur yang dihasilkan setidaknya sekali saat Anda mengambil twin dengan metode GetDigitalTwin().
Tip
displayName untuk twin adalah bagian dari metadata model twin, sehingga tidak akan ditampilkan saat mendapatkan data untuk instans twin. Untuk melihat nilai ini, Anda dapat mengambil nilai dari model.
Untuk mengambil beberapa kembar menggunakan satu panggilan API, lihat contoh API Kueri di Mengkueri grafik kembar.
Pertimbangkan model berikut (ditulis dalam Bahasa Definisi Twin Digital (DTDL)) yang menentukan Bulan:
{
"@id": "dtmi:example:Moon;1",
"@type": "Interface",
"@context": "dtmi:dtdl:context;3",
"contents": [
{
"@type": "Property",
"name": "radius",
"schema": "double",
"writable": true
},
{
"@type": "Property",
"name": "mass",
"schema": "double",
"writable": true
}
]
}
Hasil pemanggilan object result = await client.GetDigitalTwinAsync("my-moon"); pada twin jenis Bulan mungkin terlihat seperti ini:
{
"$dtId": "myMoon-001",
"$etag": "W/\"e59ce8f5-03c0-4356-aea9-249ecbdc07f9\"",
"radius": 1737.1,
"mass": 0.0734,
"$metadata": {
"$model": "dtmi:example:Moon;1",
"radius": {
"lastUpdateTime": "2022-12-06T20:00:32.8209188Z"
},
"mass": {
"lastUpdateTime": "2022-12-04T12:04:43.3859361Z"
}
}
}
Properti yang ditentukan dari twin digital ditampilkan sebagai properti tingkat atas pada twin digital. Metadata atau informasi sistem yang bukan bagian dari definisi DTDL dikembalikan dengan $ awalan. Properti metadata mencakup nilai berikut:
$dtId: ID twin digital dalam instans Azure Digital Twins ini$etag: Bidang HTTP standar yang ditetapkan oleh server web. Ini diperbarui ke nilai baru setiap kali twin diperbarui, yang dapat berguna untuk menentukan apakah data twin telah diperbarui di server sejak pemeriksaan sebelumnya. Anda dapat menggunakanIf-Matchuntuk melakukan pembaruan dan penghapusan yang hanya selesai jika etag entitas cocok dengan etag yang diberikan. Untuk informasi selengkapnya tentang operasi ini, lihat dokumentasi untuk Pembaruan DigitalTwins dan Penghapusan DigitalTwins.$metadata: Sekumpulan properti metadata, yang mungkin mencakup yang berikut ini:$model, DTMI model kembar digital.lastUpdateTimeuntuk properti kembar. Ini adalah tanda waktu yang menunjukkan tanggal dan waktu Azure Digital Twins memproses pesan pembaruan propertisourceTimeuntuk properti kembar. Ini adalah properti opsional yang dapat ditulis yang mewakili tanda waktu ketika pembaruan properti diamati di dunia nyata.
Anda dapat membaca selengkapnya tentang bidang yang terkandung dalam kembar digital dalam format Digital twin JSON. Anda dapat membaca selengkapnya tentang kelas pembantu serialisasi seperti BasicDigitalTwin di API dan SDK Azure Digital Twins.
Melihat semua twin digital
Untuk melihat semua twin digital dalam instans Anda, gunakan kueri. Anda dapat menjalankan kueri dengan API Kueri atau perintah CLI.
Berikut isi kueri dasar yang mengembalikan daftar semua kembar digital dalam instans:
SELECT * FROM DIGITALTWINS
Memperbarui kembaran digital
Untuk memperbarui properti kembar digital, tulis informasi yang ingin Anda ganti dalam format Patch JSON. Untuk daftar lengkap operasi Patch JSON yang dapat digunakan, termasuk , dan , lihat Operasi untuk JSON Patch.removeadd replace
Setelah membuat dokumen JSON Patch yang berisi informasi pembaruan, teruskan dokumen ke UpdateDigitalTwin() dalam metode :
await client.UpdateDigitalTwinAsync(twinId, updateTwinData);
Satu panggilan patch dapat memperbarui properti sebanyak mungkin pada satu kembaran yang Anda inginkan (bahkan semuanya). Jika Anda perlu memperbarui properti di beberapa kembar, Anda memerlukan panggilan pembaruan terpisah untuk setiap kembar.
Tip
Setelah membuat atau memperbarui twin, mungkin ada latensi hingga 10 detik sebelum perubahan tersebut muncul dalam kueri. GetDigitalTwin API (dijelaskan sebelumnya dalam artikel ini) tidak mengalami penundaan ini, jadi gunakan panggilan API daripada mengkueri untuk melihat twin Anda yang baru diperbarui jika memerlukan respons instan.
Berikut adalah contoh kode Patch JSON. Dokumen ini menggantikan nilai properti massa dan radius dari kembar digital yang diterapkannya. Contoh ini menunjukkan operasi JSON Patch replace, yang menggantikan nilai properti yang ada.
[
{
"op": "replace",
"path": "/mass",
"value": 0.0799
},
{
"op": "replace",
"path": "/radius",
"value": 0.800
}
]
Saat memperbarui kembaran dari proyek kode menggunakan .NET SDK, Anda dapat membuat patch JSON menggunakan JsonPatchDocument Azure .NET SDK. Berikut adalah contoh pembuatan dokumen Patch JSON dan menggunakan UpdateDigitalTwin() dalam kode proyek.
var updateTwinData = new JsonPatchDocument();
updateTwinData.AppendAdd("/Temperature", 25.0);
updateTwinData.AppendAdd("/myComponent/Property", "Hello");
// Un-set a property
updateTwinData.AppendRemove("/Humidity");
await client.UpdateDigitalTwinAsync("myTwin", updateTwinData).ConfigureAwait(false);
Tip
Anda dapat mempertahankan tanda waktu sumber pada kembar digital Anda dengan memperbarui $metadata.<property-name>.sourceTime bidang dengan proses yang dijelaskan di bagian ini. Untuk informasi selengkapnya tentang bidang ini dan bidang lain yang dapat ditulis pada kembar digital, lihat Format JSON digital twin.
Memperbarui subproperti dalam komponen twin digital
Ingat bahwa model mungkin berisi komponen, memungkinkannya terdiri dari model lain.
Untuk mem-patch properti dalam komponen twin digital, Anda dapat menggunakan sintaks jalur di Patch JSON:
[
{
"op": "replace",
"path": "/mycomponentname/mass",
"value": 0.0799
}
]
Memperbarui subproperti di properti jenis objek
Model mungkin berisi properti yang berjenis objek. Objek tersebut mungkin memiliki propertinya sendiri, dan Anda mungkin ingin memperbarui salah satu sub-properti milik properti jenis objek. Proses ini mirip dengan proses untuk memperbarui sub-properti dalam komponen, tetapi mungkin memerlukan beberapa langkah tambahan.
Pertimbangkan model dengan properti jenis objek, ObjectProperty. ObjectProperty memiliki properti string bernama StringSubProperty.
Saat twin dibuat menggunakan model ini, tidak perlu membuat instans ObjectProperty pada saat twin dibuat. Jika properti objek tidak dibuat selama pembuatan kembar, tidak ada jalur default yang dibuat untuk mengakses ObjectProperty dan StringSubProperty untuk operasi patch. Anda perlu menambahkan jalur ke ObjectProperty diri Anda sendiri sebelum dapat memperbarui propertinya.
Ini dapat dilakukan dengan operasi Patch JSON add, seperti ini:
[
{
"op": "add",
"path": "/ObjectProperty",
"value": {"StringSubProperty":"<string-value>"}
}
]
Catatan
Jika ObjectProperty memiliki lebih dari satu properti, Anda harus menyertakan semuanya di bidang value operasi ini, meskipun hanya memperbarui satu:
... "value": {"StringSubProperty":"<string-value>", "Property2":"<property2-value>", ...}
Setelah ini dilakukan sekali, jalur ke StringSubProperty ada, dan mulai sekarang dapat diperbarui secara langsung dengan operasi replace biasa:
[
{
"op": "replace",
"path": "/ObjectProperty/StringSubProperty",
"value": "<string-value>"
}
]
Meskipun langkah pertama tidak diperlukan dalam kasus di mana ObjectProperty dibuat ketika kembar dibuat, disarankan untuk menggunakannya setiap kali Anda memperbarui sub-properti untuk pertama kalinya, karena Anda mungkin tidak selalu tahu dengan pasti apakah properti objek awalnya dibuat atau tidak.
Memperbarui model twin digital
Fungsi UpdateDigitalTwin() juga dapat digunakan untuk memigrasikan twin digital ke model yang berbeda.
Misalnya, pertimbangkan dokumen Patch JSON berikut yang menggantikan bidang $model metadata twin digital:
[
{
"op": "replace",
"path": "/$metadata/$model",
"value": "dtmi:example:foo;1"
}
]
Operasi ini hanya berhasil jika kembar digital dimodifikasi oleh patch sesuai dengan model baru.
Pertimbangkan contoh berikut:
- Bayangkan twin digital dengan model foo_old. foo_old menentukan properti massa yang diperlukan.
- Model baru foo_new menentukan massa properti, dan menambahkan properti suhu baru yang diperlukan.
- Setelah patch, twin digital harus memiliki properti massa dan suhu.
Patch untuk situasi ini perlu memperbarui model dan properti suhu twin, seperti ini:
[
{
"op": "replace",
"path": "/$metadata/$model",
"value": "dtmi:example:foo_new;1"
},
{
"op": "add",
"path": "/temperature",
"value": 60
}
]
Memperbarui sourceTime properti
Anda mungkin secara opsional memutuskan untuk menggunakan sourceTime bidang pada properti kembar untuk merekam tanda waktu saat pembaruan properti diamati di dunia nyata. Azure Digital Twins secara asli mendukung sourceTime metadata untuk setiap properti kembar. Nilai sourceTime harus mematuhi format tanggal dan waktu ISO 8601. Untuk informasi selengkapnya tentang bidang ini dan bidang lain tentang kembar digital, lihat Format JSON digital twin.
Versi REST API stabil minimum untuk mendukung bidang ini adalah versi 2022-05-31 . Untuk bekerja dengan bidang ini menggunakan Azure Digital Twins SDK, sebaiknya gunakan versi terbaru SDK untuk memastikan bidang ini disertakan.
Berikut adalah contoh dokumen JSON Patch yang memperbarui nilai dan sourceTime bidang Temperature properti:
[
{
"op": "replace",
"path": "/Temperature",
"value": "22.3"
},
{
"op": "replace",
"path": "/$metadata/Temperature/sourceTime",
"value": "2021-11-30T18:47:53.7648958Z"
}
]
Untuk memperbarui sourceTime bidang pada properti yang merupakan bagian dari komponen, sertakan komponen di awal jalur. Dalam contoh di atas, Anda akan melakukan ini dengan mengubah nilai jalur dari /$metadata/Temperature/sourceTime ke myComponent/$metadata/Temperature/sourceTime.
Catatan
Jika Anda memperbarui sourceTime nilai dan pada properti, dan kemudian hanya memperbarui nilai properti, sourceTime tanda waktu dari pembaruan pertama akan tetap ada.
Menangani panggilan pembaruan yang bentrok
Azure Digital Twins memastikan bahwa semua permintaan yang masuk diproses satu demi satu. Ini berarti bahwa meskipun beberapa fungsi mencoba memperbarui properti yang sama pada twin secara bersamaan, tidak perlu bagi Anda untuk menulis kode penguncian eksplisit untuk menangani konflik.
Perilaku ini berdasarkan per-twin.
Sebagai contoh, bayangkan sebuah skenario di mana ketiga panggilan ini tiba pada saat yang bersamaan:
- Tulis properti A di Twin1
- Tulis properti B di Twin1
- Tulis properti A di Twin2
Dua panggilan yang memodifikasi Twin1 dijalankan satu demi satu, dan pesan perubahan dihasilkan untuk setiap perubahan. Panggilan untuk memodifikasi Twin2 dapat dijalankan secara bersamaan tanpa konflik, segera setelah tiba.
Menghapus twin digital
Anda dapat menghapus twin menggunakan metode DeleteDigitalTwin(). Namun, Anda hanya dapat menghapus twin jika tidak memiliki hubungan lagi. Jadi, hapus dulu hubungan masuk dan keluar twin.
Berikut adalah contoh kode untuk menghapus kembar dan hubungannya. Panggilan SDK DeleteDigitalTwin disorot untuk memperjelas lokasinya dalam konteks contoh yang lebih luas.
private static async Task CustomMethod_DeleteTwinAsync(DigitalTwinsClient client, string twinId)
{
await CustomMethod_FindAndDeleteOutgoingRelationshipsAsync(client, twinId);
await CustomMethod_FindAndDeleteIncomingRelationshipsAsync(client, twinId);
try
{
await client.DeleteDigitalTwinAsync(twinId);
Console.WriteLine("Twin deleted successfully");
}
catch (RequestFailedException ex)
{
Console.WriteLine($"*** Error:{ex.Message}");
}
}
private static async Task CustomMethod_FindAndDeleteOutgoingRelationshipsAsync(DigitalTwinsClient client, string dtId)
{
// Find the relationships for the twin
try
{
// GetRelationshipsAsync will throw an error if a problem occurs
AsyncPageable<BasicRelationship> rels = client.GetRelationshipsAsync<BasicRelationship>(dtId);
await foreach (BasicRelationship rel in rels)
{
await client.DeleteRelationshipAsync(dtId, rel.Id).ConfigureAwait(false);
Console.WriteLine($"Deleted relationship {rel.Id} from {dtId}");
}
}
catch (RequestFailedException ex)
{
Console.WriteLine($"*** Error {ex.Status}/{ex.ErrorCode} retrieving or deleting relationships for {dtId} due to {ex.Message}");
}
}
private static async Task CustomMethod_FindAndDeleteIncomingRelationshipsAsync(DigitalTwinsClient client, string dtId)
{
// Find the relationships for the twin
try
{
// GetRelationshipsAsync will throw an error if a problem occurs
AsyncPageable<IncomingRelationship> incomingRels = client.GetIncomingRelationshipsAsync(dtId);
await foreach (IncomingRelationship incomingRel in incomingRels)
{
await client.DeleteRelationshipAsync(incomingRel.SourceId, incomingRel.RelationshipId).ConfigureAwait(false);
Console.WriteLine($"Deleted incoming relationship {incomingRel.RelationshipId} from {dtId}");
}
}
catch (RequestFailedException ex)
{
Console.WriteLine($"*** Error {ex.Status}/{ex.ErrorCode} retrieving or deleting incoming relationships for {dtId} due to {ex.Message}");
}
}
Menghapus semua twin digital
Untuk contoh cara menghapus semua kembaran sekaligus, unduh aplikasi sampel yang digunakan di Menjelajahi dasar-dasar dengan aplikasi klien sampel. File CommandLoop.cs melakukan ini dalam fungsi CommandDeleteAllTwins().
Catatan
Jika Anda ingin menghapus semua model, kembar, dan hubungan dalam instans sekaligus, gunakan Delete Jobs API.
Sampel kode twin digital yang dapat dijalankan
Anda dapat menggunakan sampel kode yang dapat dijalankan di bawah ini untuk membuat twin, memperbarui detail, dan menghapus twin.
Menyiapkan file proyek sampel
Cuplikan menggunakan definisi model sampel, Room.json. Untuk mengunduh file model sehingga Anda dapat menggunakannya dalam kode, gunakan tautan ini untuk langsung membuka file di GitHub. Kemudian, klik kanan di mana saja pada layar, pilih Save as di menu klik kanan browser Anda, dan gunakan jendela Save As untuk menyimpan file sebagai Room.json.
Selanjutnya, buat proyek aplikasi konsol baru di Visual Studio atau editor pilihan Anda.
Kemudian, salin kode berikut dari sampel yang dapat dijalankan ke dalam proyek Anda:
using System;
using System.Threading.Tasks;
using System.Collections.Generic;
using Azure;
using Azure.DigitalTwins.Core;
using Azure.Identity;
using System.IO;
namespace DigitalTwins_Samples
{
class TwinOperationsSample
{
public static async Task Main(string[] args)
{
Console.WriteLine("Hello World!");
// Create the Azure Digital Twins client for API calls
string adtInstanceUrl = "https://<your-instance-hostname>";
var credentials = new DefaultAzureCredential();
var client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credentials);
Console.WriteLine($"Service client created – ready to go");
// Upload models
Console.WriteLine($"Upload a model");
string dtdl = File.ReadAllText("<path-to>/Room.json");
var models = new List<string> { dtdl };
// Upload the model to the service
await client.CreateModelsAsync(models);
// Create new digital twin
// <CreateTwin_withHelper>
string twinId = "myTwinID";
var initData = new BasicDigitalTwin
{
Id = twinId,
Metadata = { ModelId = "dtmi:example:Room;1" },
// Initialize properties
Contents =
{
{ "Temperature", 25.0 },
{ "Humidity", 50.0 },
},
};
// <CreateTwinCall>
await client.CreateOrReplaceDigitalTwinAsync<BasicDigitalTwin>(twinId, initData);
// </CreateTwinCall>
// </CreateTwin_withHelper>
Console.WriteLine("Twin created successfully");
//Print twin
Console.WriteLine("--- Printing twin details:");
await CustomMethod_FetchAndPrintTwinAsync(twinId, client);
Console.WriteLine("--------");
//Update twin data
var updateTwinData = new JsonPatchDocument();
updateTwinData.AppendAdd("/Temperature", 30.0);
// <UpdateTwinCall>
await client.UpdateDigitalTwinAsync(twinId, updateTwinData);
// </UpdateTwinCall>
Console.WriteLine("Twin properties updated");
Console.WriteLine();
//Print twin again
Console.WriteLine("--- Printing twin details (after update):");
await CustomMethod_FetchAndPrintTwinAsync(twinId, client);
Console.WriteLine("--------");
Console.WriteLine();
//Delete twin
await CustomMethod_DeleteTwinAsync(client, twinId);
}
private static async Task<BasicDigitalTwin> CustomMethod_FetchAndPrintTwinAsync(string twinId, DigitalTwinsClient client)
{
// <GetTwin>
BasicDigitalTwin twin;
// <GetTwinCall>
Response<BasicDigitalTwin> twinResponse = await client.GetDigitalTwinAsync<BasicDigitalTwin>(twinId);
twin = twinResponse.Value;
// </GetTwinCall>
Console.WriteLine($"Model id: {twin.Metadata.ModelId}");
foreach (string prop in twin.Contents.Keys)
{
if (twin.Contents.TryGetValue(prop, out object value))
Console.WriteLine($"Property '{prop}': {value}");
}
// </GetTwin>
return twin;
}
// <DeleteTwin>
private static async Task CustomMethod_DeleteTwinAsync(DigitalTwinsClient client, string twinId)
{
await CustomMethod_FindAndDeleteOutgoingRelationshipsAsync(client, twinId);
await CustomMethod_FindAndDeleteIncomingRelationshipsAsync(client, twinId);
try
{
await client.DeleteDigitalTwinAsync(twinId);
Console.WriteLine("Twin deleted successfully");
}
catch (RequestFailedException ex)
{
Console.WriteLine($"*** Error:{ex.Message}");
}
}
private static async Task CustomMethod_FindAndDeleteOutgoingRelationshipsAsync(DigitalTwinsClient client, string dtId)
{
// Find the relationships for the twin
try
{
// GetRelationshipsAsync will throw an error if a problem occurs
AsyncPageable<BasicRelationship> rels = client.GetRelationshipsAsync<BasicRelationship>(dtId);
await foreach (BasicRelationship rel in rels)
{
await client.DeleteRelationshipAsync(dtId, rel.Id).ConfigureAwait(false);
Console.WriteLine($"Deleted relationship {rel.Id} from {dtId}");
}
}
catch (RequestFailedException ex)
{
Console.WriteLine($"*** Error {ex.Status}/{ex.ErrorCode} retrieving or deleting relationships for {dtId} due to {ex.Message}");
}
}
private static async Task CustomMethod_FindAndDeleteIncomingRelationshipsAsync(DigitalTwinsClient client, string dtId)
{
// Find the relationships for the twin
try
{
// GetRelationshipsAsync will throw an error if a problem occurs
AsyncPageable<IncomingRelationship> incomingRels = client.GetIncomingRelationshipsAsync(dtId);
await foreach (IncomingRelationship incomingRel in incomingRels)
{
await client.DeleteRelationshipAsync(incomingRel.SourceId, incomingRel.RelationshipId).ConfigureAwait(false);
Console.WriteLine($"Deleted incoming relationship {incomingRel.RelationshipId} from {dtId}");
}
}
catch (RequestFailedException ex)
{
Console.WriteLine($"*** Error {ex.Status}/{ex.ErrorCode} retrieving or deleting incoming relationships for {dtId} due to {ex.Message}");
}
}
// </DeleteTwin>
}
}
Catatan
Saat ini ada masalah yang diketahui yang memengaruhi DefaultAzureCredential kelas pembungkus yang dapat mengakibatkan kesalahan saat mengautentikasi. Jika Anda mengalami masalah ini, Anda dapat mencoba membuat instans DefaultAzureCredential dengan parameter opsional berikut untuk mengatasinya: new DefaultAzureCredential(new DefaultAzureCredentialOptions { ExcludeSharedTokenCacheCredential = true });
Untuk informasi selengkapnya tentang masalah ini, lihat Masalah umum Azure Digital Twins.
Mengonfigurasi proyek
Selanjutnya, selesaikan langkah-langkah berikut untuk mengonfigurasi kode proyek Anda:
Tambahkan file Room.json yang Anda unduh sebelumnya ke proyek, dan ganti tempat penampung
<path-to>dalam kode untuk memberi tahu program di mana menemukan file.Ganti tempat penampung
<your-instance-hostname>dengan nama host instans Azure Digital Twins Anda.Tambahkan dua dependensi ke proyek Anda yang diperlukan untuk bekerja dengan Azure Digital Twins. Yang pertama adalah paket untuk SDK Azure Digital Twins untuk .NET, dan yang kedua menyediakan alat untuk membantu autentikasi terhadap Azure.
dotnet add package Azure.DigitalTwins.Core dotnet add package Azure.Identity
Anda juga perlu menyiapkan kredensial lokal jika Anda ingin menjalankan sampel secara langsung. Bagian selanjutnya membahas ini.
Siapkan kredensial Azure lokal
Sampel ini menggunakan DefaultAzureCredential (bagian dari pustaka Azure.Identity) untuk mengautentikasi pengguna dengan instans Azure Digital Twins saat Anda menjalankannya di komputer lokal Anda. Untuk informasi selengkapnya tentang berbagai cara aplikasi klien dapat mengautentikasi dengan Azure Digital Twins, lihat Menulis kode autentikasi aplikasi.
Dengan DefaultAzureCredential, sampel akan mencari kredensial di lingkungan lokal Anda, seperti masuk Azure di Azure CLI lokal atau di Visual Studio atau Visual Studio Code. Untuk alasan ini, Anda harus masuk ke Azure secara lokal melalui salah satu mekanisme ini untuk menyiapkan kredensial untuk sampel tersebut.
Jika Anda menggunakan Visual Studio atau Visual Studio Code untuk menjalankan sampel kode, pastikan Anda masuk ke editor tersebut dengan kredensial Azure yang sama dengan yang ingin Anda gunakan untuk mengakses instans Azure Digital Twins Anda. Jika Anda menggunakan jendela CLI lokal, jalankan az login perintah untuk masuk ke akun Azure Anda. Setelah ini, saat menjalankan sampel kode, Anda harus diautentikasi secara otomatis.
Jalankan sampel
Setelah penyiapan selesai, Anda dapat menjalankan proyek kode sampel.
Berikut adalah output konsol dari program di atas:
Langkah berikutnya
Lihat cara membuat dan mengelola hubungan antara twin digital Anda: