將記錄連結至中繼資料執行個體

本指南說明如何將記錄連結至中繼資料執行個體。製造業資料引擎 (MDE) 會將中繼資料 bucket 的 instance_id 寫入記錄，藉此將記錄連結至中繼資料執行個體。不過，您不會直接在剖析器中的 proto 記錄中設定 instance_id。而是根據您在 Proto 記錄中提供的輸入內容，自動為您解決 instance_id。MDE 提供兩種解決 instance_id 中衝突的方法：

依中繼資料執行個體自然鍵。
依中繼資料執行個體值。

依自然鍵解析中繼資料 instance_id

中繼資料值區中的每個中繼資料例項都有自然鍵，且一個自然鍵可能有多個例項。您可以在剖析器中提供原型記錄的自然鍵，將記錄與自然鍵的最新中繼資料執行個體建立關聯。MDE 會負責擷取您提供的自然鍵的最新執行個體，並在記錄中插入該執行個體的 instance_id。

舉例來說，假設記錄中繼資料 bucket (名為 machine，bucket 編號為 1) 中有下列中繼資料執行個體：

[
  {
    "instance_id": "a614e25d-fded-41c3-9a56-3222cd30070d",
    "bucket_number": "1",
    "bucket_name": "machine",
    "bucket_version": "1",
    "natural_key": "m-234",
    "instance": {
      "machineName": "CNC Mill"
    },
    "created_timestamp": "2023-06-27 20:00:29.603000 UTC"
  },
  {
    "instance_id": "6cfdf894-2fb6-4951-82c6-c4eada587529",
    "bucket_number": "1",
    "bucket_name": "machine",
    "bucket_version": "1",
    "natural_key": "m-234",
    "instance": {
      "machineName": "5 Axis CNC Mill"
    },
    "created_timestamp": "2023-06-28 20:00:29.632000 UTC"
  }
]

假設來源訊息如下：

{
  "sensor": "rotation-speed-sensor",
  "machine": "m-234",
  "timestamp": "1687973092857",
  "value": 1200
}

以下 Whistle 指令碼：

package mde

[
    {
        tagName: $root.machine + "-" + $root.sensor;
        data: {
            numeric: $root.value;
        };
        timestamps: {
            eventTimestamp: $root.timestamp;
        }
        cloudMetadata: [{
            bucketReference: {
                bucketName: "machine";
                version: 1;
            }
            naturalKey: $root.machine
        }]
    }
]

會產生下列 proto 記錄：

[
  {
    "tagName": "m-234-rotation-speed-sensor",
    "data": {
      "numeric": 1200
    },
    "timestamps": {
      "eventTimestamp": "1687973092857"
    },
    "cloudMetadata": [
      {
        "bucketReference": {
          "bucketName": "machine",
          "number": 1
        },
        "naturalKey": "m-234"
      }
    ]
  }
]

MDE 處理完 proto 記錄後，會在 BigQuery 中產生下列記錄 (資料列) (假設 BigQuery 接收器和中繼資料具體化已開啟)：

[
  {
    "id": "6e008960-7f25-4418-899c-75b05c3d3186",
    "tag_name": "m-234-rotation-speed-sensor",
    "type_version": "1",
    "event_timestamp": "2023-06-28 17:24:52.526000 UTC",
    "value": "1200",
    "embedded_metadata": {},
    "materialized_cloud_metadata": {
      "machine": {
        "machineName": "5 Axis CNC Mill"
      }
    },
    "cloud_metadata_ref": {
      "machine": {
        "instance_id": "6cfdf894-2fb6-4951-82c6-c4eada587529"
      }
    },
    "event_timestamp": "2023-06-28 17:24:53.526000 UTC",
    "source_message_id": "8511923697775002"
  }
]

依執行個體值解析中繼資料 `instance_id`

或者，您也可以在剖析器中提供整個中繼資料執行個體物件，將記錄與自然鍵的最新中繼資料執行個體建立關聯。您可以視需要提供自然鍵。如果省略自然鍵，MDE 會根據 bucket 類型推斷自然鍵：

如果您為「標記」值區提供中繼資料執行個體值，並省略自然鍵，MDE 會自動將標記名稱做為自然鍵。
如果您要為 record bucket 提供中繼資料執行個體值，並省略自然鍵，MDE 會自動將執行個體物件的雜湊值做為自然鍵。

在剖析器中建構原型記錄後，MDE 會比較提供的中繼資料執行個體物件，以及所提供自然鍵的最新中繼資料執行個體物件。

如果執行個體物件相同，MDE 會將自然鍵的最新中繼資料執行個體 instance_id 插入記錄。

如果執行個體物件不相同，MDE 會使用 proto 記錄提供的中繼資料執行個體，為指定自然鍵建立新的中繼資料執行個體。MDE 接著會將新建立的執行個體插入記錄中。instance_id

當邊緣來源傳送完整訊息時，依執行個體值解析中繼資料 instance_id 特別實用。使用這個方法解析中繼資料執行個體，可參照現有執行個體，也能動態建立新的中繼資料執行個體。

依值參照現有執行個體

以下是名為 asset 的標記中繼資料 bucket 中的中繼資料執行個體範例，bucket 編號為 1：

[
  {
    "instance_id": "a614e25d-fded-41c3-9a56-3222cd30070d",
    "bucket_number": "1",
    "bucket_name": "asset",
    "bucket_version": "1",
    "natural_key": "s-446-pressure",
    "instance": {
      "machineName": "Stamping M. 446"
    },
    "created_timestamp": "2023-06-27 20:00:29.603000 UTC"
  },
  {
    "instance_id": "6cfdf894-2fb6-4951-82c6-c4eada587529",
    "bucket_number": "1",
    "bucket_name": "asset",
    "bucket_version": "1",
    "natural_key": "s-446-pressure",
    "instance": {
      "machineName": "Stamping Machine 446"
    },
    "created_timestamp": "2023-06-28 20:00:29.632000 UTC"
  }
]

假設來源訊息如下：

{
  "sensor": "pressure",
  "machine": "s-446",
  "timestamp": "1687973092857",
  "machineName": "Stamping Machine 446",
  "value": 24
}

以及下列 Whistle 指令碼：

package mde

var tagName: $root.machine + "-" + $root.sensor;

[
    {
        tagName: tagName;
        data: {
            numeric: $root.value;
        };
        timestamps: {
            eventTimestamp: $root.timestamp;
        }
        cloudMetadata: [{
            bucketReference: {
                bucketName: "asset";
                version: 1;
            }
            instance: {
              // optional. Since bucketReference points to a tag bucket, if omitted, the natural is inferred to be tagName
              naturalKey: tagName
              attributes: {
                machineName: $root.machineName;
              }
            }
        }]
    }
]

套用 Whistle 指令碼會產生下列 proto 記錄：

[
  {
    "tagName": "s-446-pressure",
    "data": {
      "numeric": 24
    },
    "timestamps": {
      "eventTimestamp": "1687973092857"
    },
    "cloudMetadata": [
      {
        "bucketReference": {
          "bucketName": "asset",
          "number": 1
        },
        "naturalKey": "s-446-pressure",
        "attributes": {
          "machineName": "Stamping Machine 446"
        }
      }
    ]
  }
]

MDE 處理完 proto 記錄後，會在 BigQuery 中產生下列記錄 (資料列) (假設 BigQuery 接收器和中繼資料具體化已啟用)：

[
  {
    "id": "6e008960-7f25-4418-899c-75b05c3d3186",
    "tag_name": "s-446-pressure",
    "type_version": "1",
    "event_timestamp": "2023-06-28 17:24:52.526000 UTC",
    "value": "24",
    "embedded_metadata": {},
    "materialized_cloud_metadata": {
      "asset": {
        "machineName": "Stamping Machine 446"
      }
    },
    "cloud_metadata_ref": {
      "asset": {
        "instance_id": "6cfdf894-2fb6-4951-82c6-c4eada587529"
      }
    },
    "event_timestamp": "2023-06-28 17:24:53.526000 UTC",
    "source_message_id": "8511923697775002"
  }
]

依值建立新執行個體

如果 proto 記錄中提供的中繼資料執行個體，與所提供自然鍵的最新中繼資料執行個體不相同，MDE 就會建立新的執行個體。

您可以使用值區的 instanceOverwriteMode 設定，設定新執行個體的建立方式：

如果 instanceOverwriteMode 設為 true，系統會從 proto 記錄中提供的執行個體物件建立新執行個體。如果通過值區的結構定義驗證，新執行個體就會儲存在中繼資料值區中。
如果 instanceOverwriteMode 設為 false，系統會合併自然鍵的最新例項，以及 Proto 記錄中提供的例項物件，藉此建立新例項。如果產生的物件通過值區的結構定義驗證，就會以新的中繼資料執行個體形式儲存在中繼資料值區中。

舉例來說，假設標記中繼資料值區 (名為 asset，值區編號為 1) 中有下列中繼資料執行個體：

[
  {
    "instance_id": "a614e25d-fded-41c3-9a56-3222cd30070d",
    "bucket_number": "1",
    "bucket_name": "asset",
    "bucket_version": "1",
    "natural_key": "s-446-pressure",
    "instance": {
      "machineName": "Stamping M. 446"
    },
    "created_timestamp": "2023-06-27 20:00:29.603000 UTC"
  }
]

以及下列來源訊息：

{
  "sensor": "pressure",
  "machine": "s-446",
  "timestamp": "1687973092857",
  "machineName": "Stamping Machine 446",
  "value": 24
}

使用下列 Whistle 指令碼：

package mde

var tagName: $root.machine + "-" + $root.sensor;

[
    {
        tagName: tagName;
        data: {
            numeric: $root.value;
        };
        timestamps: {
            eventTimestamp: $root.timestamp;
        }
        cloudMetadata: [{
            bucketReference: {
                bucketName: "asset";
                number: 1;
            }
            instance: {
              // optional. Since bucketReference points to a tag bucket, if omitted, the natural is inferred to be tagName
              naturalKey: tagName
              attributes: {
                machineName: $root.machineName;
              }
            }
        }]
    }
]