數位對應項及其對應項圖形

發行項
01/04/2024

本文說明 Azure Digital Twins 內容中的數位對應項，以及它們之間的關聯性如何形成對應項圖形。在 Azure Digital Twins 解決方案中，您環境中的實體會以 數位對應項 表示。數位對應項是其中一個自訂定義模型的實例。它可以透過關聯性連接到其他數位對應項，以形成 對應項圖形 ：此對應項圖形是整個環境的標記法。

提示

「Azure Digital Twins」是指整個 Azure 服務。「數位對應項」或只有「對應項」是指服務執行個體內的個別對應項節點。

Digital Twins

您必須先將模型 上傳至服務， 才能在 Azure Digital Twins 實例中建立數位對應項。模型描述特定對應項可以擁有的屬性和關聯性集合，以及其他專案。如需模型中定義的資訊類型，請參閱自訂模型。

建立和上傳模型之後，用戶端應用程式可以建立類型的實例。這個實例是數位對應項。例如，在建立 Floor 的模型之後，您可以建立一或多個使用此類型的數位對應項（例如 Floor 類型對應項，稱為 GroundFloor、另一個稱為 Floor2 等等）。

注意

Azure Digital Twins 中的數位對應項與IoT 中樞中的裝置對應項不同。 IoT 中樞裝置對應項通常著重于描述裝置本身的層面和功能，而 Azure Digital Twins 中的對應項則是更概念性的標記法，可儲存裝置或許多相關裝置的使用者定義深入解析。

IoT 中樞中的裝置可以連線到 Azure Digital Twins，做為端對端解決方案的一部分，代表您裝置跨服務。

關聯性：數位對應項的圖表

對應項會依其關聯性連接到對應項圖表。對應項可以擁有的關聯性會定義為其模型的一部分。

例如，Model Floor 可能會定義 contains 以 Room 類型對應項為目標的關聯性。透過此定義，Azure Digital Twins 可讓您建立 contains 從任何 Floor 對應項到任何會議室對應項的關聯性（包括 Room 子類型的對應項）。

此程序的結果是圖表中透過邊緣 (其關聯性) 連接的一組節點 (數位對應項)。

視覺效果

Azure Digital Twins Explorer 是一種視覺化檢視，可用來探索 Azure Digital Twins 圖表中的資料。您可以使用總管來檢視、查詢和編輯模型、對應項和關聯性。

若要閱讀 Azure Digital Twins Explorer 工具，請參閱 Azure Digital Twins Explorer 。如需如何使用其功能的詳細步驟，請參閱使用 Azure Digital Twins Explorer 。

以下是視覺效果的外觀：

使用 API 建立

本節說明如何從用戶端應用程式建立數位對應項和關聯性。它包含使用 DigitalTwins API 的 .NET SDK 範例，以提供每個概念內所發生內容的詳細資訊。

建立數位對應項

以下是用戶端程式程式碼片段，其使用 DigitalTwins API 來具現化 Room 類型的對應項，以及 twinId 具現化期間定義的。

您可以在建立對應項時初始化對應項的屬性，或稍後加以設定。若要建立具有初始化屬性的對應項，請建立提供必要初始化值的 JSON 檔。

// 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}");
    }
}

您也可以使用稱為 BasicDigitalTwin 的協助程式類別，更直接地將屬性欄位儲存在「twin」物件中，作為使用字典的替代方案。如需協助程式類別及其使用範例的詳細資訊，請參閱建立數位對應項。

注意

雖然對應項屬性被視為選擇性屬性，因此不需要初始化，但當建立對應項時，必須在對應項上設定任何元件。可以是空物件，但是元件本身必須存在。

建立關聯

以下是一些使用 DigitalTwins API 建置從一個數位對應項（「來源」對應項）到另一個數位對應項（「目標」對應項的關聯性的範例用戶端程式代碼。

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);
}

使用匯入作業 API 大量建立對應項和關聯性

您可以使用匯入作業 API API ，在單一 API 呼叫中上傳許多對應項和關聯性。使用此 API 建立的對應項和關聯性可以選擇性地包含其屬性的初始化。如需使用此 API 的詳細指示和範例，請參閱對應項和關聯性的大量匯入指示。

刪除圖形元素

若要刪除特定的對應項和關聯性，請使用 DigitalTwins Delete 和 DigitalTwins DeleteRelationship API（也可以在 CLI 命令和 SDK 呼叫中使用）。

若要一次刪除實例中的所有模型、對應項和關聯性，請使用刪除作業 API 。

圖形元素的 JSON 標記法

數位對應項資料和關聯性資料都是以 JSON 格式儲存，這表示當您在 Azure Digital Twins 實例中查詢對應項圖形時，結果會是數位對應項的 JSON 標記法和您所建立的關聯性。

數位對應項 JSON 格式

以 JSON 物件表示時，數位對應項會顯示下欄欄位：

欄位名稱	描述
`$dtId`	使用者提供的字串，代表數位對應項的識別碼
`$etag`	Web 服務器指派的標準 HTTP 欄位
`$metadata.$model`	此數位對應項特徵之模型介面的識別碼
`$metadata.<property-name>`	有關數位對應項屬性的其他中繼資料資訊
`$metadata.<property-name>.lastUpdateTime`	Azure Digital Twins 處理屬性更新訊息的日期/時間
`$metadata.<property-name>.sourceTime`	選擇性的可寫入屬性，表示在真實世界中觀察到屬性更新時的時間戳記。此屬性只能使用 Azure Digital Twins API/SDK 的 2022-05-31 版本撰寫，且此值必須符合 ISO 8601 日期和時間格式。如需如何更新此屬性的詳細資訊，請參閱更新屬性的 sourceTime 。
`<property-name>`	JSON 中屬性的值（ `string` 數位類型或物件）
`$relationships`	關聯性集合路徑的 URL。如果數位對應項沒有連出關聯性邊緣，則此欄位不存在。
`<component-name>`	JSON 物件，包含元件的屬性值和中繼資料，類似于根物件的屬性值和中繼資料。即使元件沒有屬性，這個物件仍存在。
`<component-name>.$metadata`	元件的中繼資料資訊，類似于根層級 `$metadata`
`<component-name>.<property-name>`	JSON 中元件屬性的值（ `string` 數位類型或物件）

以下是格式化為 JSON 物件的數位對應項範例。此對應項有兩個屬性：濕度和溫度，以及稱為控溫器的元件。

{
    "$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": {}
    }

關聯性 JSON 格式

以 JSON 物件表示時，來自數位對應項的關聯性會顯示下欄欄位：

欄位名稱	描述
`$relationshipId`	使用者提供的字串，表示這個關聯性的識別碼。此字串在來源數位對應項的內容中是唯一的，這也表示 `sourceId` + `relationshipId` 在 Azure Digital Twins 實例的內容中是唯一的。
`$etag`	Web 服務器指派的標準 HTTP 欄位
`$sourceId`	來源數位對應項的識別碼
`$targetId`	目標數位對應項的識別碼
`$relationshipName`	關聯性的名稱
`<property-name>`	[選擇性]此關聯性屬性的值，以 JSON 為單位（ `string` 數位類型或物件）

以下是格式化為 JSON 物件的關聯性範例：

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

下一步

瞭解如何使用 Azure Digital Twin API 管理圖形元素：

或者，瞭解如何查詢 Azure Digital Twins 對應項圖表以取得資訊：

查詢語言