數位對應項和其對應項圖表

文章
05/12/2024

本文說明什麼是 Azure Digital Twins 的數位對應項，以及它們之間的關聯性如何能形成對應項圖表。在 Azure Digital Twins 解決方案中，您環境中的實體會以「數位對應項」表示。數位對應項是其中一個自訂定義模型的執行個體。可以透過「關聯性」連線到其他數位對應項以形成「對應項圖表」：此對應項圖表代表整個環境。

提示

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

Digital Twins

您必須先將「模型」上傳至服務，才能在 Azure Digital Twins 執行個體中建立數位對應項。模型說明特定對應項可擁有的屬性、關聯性及其他項目的集合。如需模型中定義的資訊類型，請參閱自訂模型 (機器翻譯)。

建立和上傳模型之後，您的用戶端應用程式可以建立該類型的執行個體。這個執行個體是數位對應項。例如，建立 Floor 模型之後，您可以建立使用此類型的一或多個數位對應項 (例如名為 GroundFloor 的 Floor 類型對應項，另一個名為 Floor2，以此類推)。

注意

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

IoT 中樞中的裝置可連線到 Azure Digital Twins，加入在服務間代表您裝置的端對端解決方案。

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

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

例如，Floor 模型可能會定義 contains 關聯性，鎖定 Room 類型的對應項。使用此定義，Azure Digital Twins 可讓您從任何 Floor 對應項，建立與任何 Room 對應項 (包括 Room 子類型對應項) 的 contains 關聯性。

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

視覺效果

「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 的協助程式類別，更直接將屬性欄位儲存在「對應項」物件中，當作使用字典的替代方法。如需協助程式類別及其使用範例的詳細資訊，請參閱建立數位對應項 (機器翻譯)。

注意

將對應項屬性視為選用，因此不必初始化，但在建立對應項時，必須設定對應項上的任何元件。可以是空物件，但是元件本身必須存在。

建立關聯

以下範例用戶端程式碼使用 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 的詳細指示和範例，請參閱對應項的大量匯入指示和關聯性。

刪除圖表元素

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

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

圖形元素的 JSON 表示法

數位對應項資料和關聯性資料都以 JSON 格式儲存，這表示當您在 Azure Digital Twins 執行個體中查詢對應項圖形時，結果會是已建立之數位對應項和關聯性的 JSON 表示法。

數位對應項 JSON 格式

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

欄位名稱	描述
`$dtId`	使用者提供的字串，代表數位對應項的識別碼
`$etag`	網頁伺服器指派的標準 HTTP 欄位
`$metadata.$model`	模型介面的識別碼，描述此數位對應項的特性
`$metadata.<property-name>`	數位對應項屬性的其他中繼資料資訊
`$metadata.<property-name>.lastUpdateTime`	Azure Digital Twins 處理屬性更新訊息的日期/時間
`$metadata.<property-name>.sourceTime`	選用的可寫入屬性，代表實際觀察到屬性更新時的時間戳記。此屬性只能使用 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 物件的數位對應項範例。此對應項有兩個屬性：Humidity 和 Temperature，以及 Thermostat 元件。

{
    "$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`	網頁伺服器指派的標準 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 對應項圖表以取得資訊：

查詢語言

分享方式：