中繼資料

中繼資料是 Manufacturing Data Engine (MDE) 的重要概念。這代表事實的脈絡資料。例如感應器讀數或事件。中繼資料可協助回答下列問題：

哪個標籤發出數值讀取資料？
在取得數值讀數時，正在處理的產品為何？
感應器屬於哪部裝置？
事件發生時，當時正在進行哪個班次？
讀取時使用的食譜為何？

MDE 會根據變更速度區分兩種中繼資料：

緩慢變更雲端中繼資料。
快速變更內嵌中繼資料。

雲端中繼資料

緩慢變更的中繼資料代表長時間保持不變的脈絡資料，例如資產脈絡，說明特定感應器的機器、儲存格、生產線和工廠。MDE 可讓您建立、管理及探索緩慢變更的中繼資料，並將其連結至記錄。將中繼資料連結至記錄後，您就能使用相關聯的內容探索記錄。

MDE 中緩慢變更的中繼資料稱為雲端中繼資料。雲端中繼資料在解決方案中具有兩項功能：

為記錄加上脈絡資訊並分類。
做為製造業實體 (例如感應器、裝置和生產線) 版本化主資料的來源。

MDE 允許從邊緣取得雲端中繼資料、使用 MDE 網頁介面手動建立，或使用 API 以程式輔助方式建立。後者可讓您從現有的企業資產管理 (EAM) 或主要資料管理 (MDM) 系統取得中繼資料。

中繼資料 bucket

雲端中繼資料值區 (也稱為「值區」或「中繼資料值區」) 是設定實體，可模擬一組相關且緩慢變更的脈絡資料。舉例來說，bucket 可以模擬標記或食譜的屬性。在資料分析領域中，儲存區可視為資料維度。

中繼資料值區的主要屬性是結構定義。結構定義 (以 JSON 結構定義物件表示) 會定義並限制其中所含中繼資料例項的結構。您可以建立新的中繼資料 bucket 版本，但新版本必須遵守雲端中繼資料bucket 版本控管規則。

儲存空間是全域資源，因此可供任何類型參照。

中繼資料執行個體

中繼資料執行個體代表雲端中繼資料 bucket 的「內容」。每個執行個體都會描述某個實體，例如資產、程序或所擷取記錄的某個面向。執行個體有兩種類型的 ID：

系統產生的 UUID (通用唯一識別碼)，用於識別 MDE 中的執行個體。
用來在 MDE 外部識別實體的自然鍵 (例如感應器的序號)。

中繼資料執行個體會根據自然鍵進行版本控管。也就是說，MDE 會追蹤特定自然鍵的屬性演變。舉例來說，自然鍵為「tag-123」的標籤可能一開始位於儲存格「X」，但後來移至儲存格「Y」。MDE 會儲存每個執行個體並加上時間戳記，然後提供專屬 UUID。這個專屬 UUID 可讓您擷取自然鍵的執行個體記錄、在擷取時使用正確的執行個體記錄來建立記錄的脈絡，以及在查詢時將執行個體追溯套用至過去的記錄。

從 1.5.0 版開始，中繼資料執行個體會根據 event-time (而非 processing time) 進行版本控管和處理。當您傳送含有歷來記錄的中繼資料執行個體時，MDE 會根據訊息的 eventTimestamp 為這些中繼資料執行個體加上版本，這樣一來，歷來和最近的中繼資料就能共存，不必變更最新執行個體。詳情請參閱「中繼資料值區版本管理」。

MDE 只允許將執行個體新增至符合特定版本值區結構定義的值區。

中繼資料值區結構

每個中繼資料值區版本都包含結構定義，且中繼資料執行個體只能新增至特定版本的值區。結構定義會進一步限制可新增至值區版本的元資料執行個體結構。

中繼資料 bucket 結構定義會以 JSON 結構定義物件表示，且符合 JSON 結構定義規格的 2019 年 9 月版本。

舉例來說，如果稍後將結構定義新增至 bucket 版本，系統會指出每個執行個體物件都必須有稱為 deviceName 的屬性，且該屬性具有 string 值，而且是必要屬性。請參閱以下範例：

{
  "$schema": "https://json-schema.org/draft/2019-09/schema#",
  "type": "object",
  "properties": {
    "deviceName": {
      "type": "string"
    }
  },
  "required": ["deviceName"]
}

中繼資料執行個體驗證

中繼資料例項必須符合特定中繼資料 bucket 版本的定義結構，才能插入。

bucket 類型

MDE 定義了三種值區：

標記 bucket
記錄 bucket
查詢值區

儲存空間的類型是在建立時定義，之後就無法變更。

標記 bucket

標記 bucket 代表可提供標記脈絡的 bucket。也就是說，值區所含執行個體的自然鍵必須是標記名稱。

記錄值區

記錄值區代表可將共用自然鍵的任何記錄群組脈絡化的值區。記錄值區例項的自然鍵可以是任何值。

查詢 bucket

查閱值區代表不會直接將記錄脈絡化的值區，而是提供剖析器可使用的參照資料。查閱值區例項的自然鍵可以是任何值。

記錄檔執行個體一律不會連結至記錄。不過，您可以透過在 Whistle 指令碼中呼叫 mde::lookupByKey 函式，從查閱值區擷取執行個體。這個函式會將查閱 bucketName、bucketVersion 和 naturalKey 做為引數，並傳回所提供自然鍵的最新中繼資料執行個體。您可以使用這個執行個體，在剖析器中填入 proto 記錄的欄位。

版本化中繼資料 bucket

中繼資料 bucket 的結構定義可能會演變，但您必須建立 bucket 的新版本，才能修改結構定義。現有 bucket 版本和參照先前 bucket 版本的任何現有設定實體，都不會受到這項作業影響。為確保中繼資料 bucket 在整個生命週期內資料一致，新版中繼資料 bucket 結構定義須遵守下列限制：

新版本可能：

新增選填欄位。
將必填欄位標示為選填。

新版本可能無法：

移除欄位。
變更現有欄位的資料類型。
將選填屬性標示為必填。

自 1.5.0 版起，中繼資料執行個體的解析度也會以事件時間戳記為準。也就是說，MDE 會解析與記錄事件時間相比最新的中繼資料例項。這項功能會將 MDE 連結中繼資料的概念一般化，以便在不同時間運作，而這些時間是由來源訊息控管。為提升中繼資料執行個體的查詢可讀性，MDE 1.5.0 版導入了名為「validFrom」的新欄位，用於指定特定中繼資料執行個體的生效時間。MDE 會根據來源訊息事件時間，使用這個欄位檢查要挑選哪個中繼資料例項。

舉例來說，假設您今天將一個中繼資料執行個體傳送至 MDE，自然鍵為 sensor-a，值如下所示：


{
    "naturalKey": "sensor-a",
    "instance": {
        "site": "ONE",
        "factory": "ONE",
        "floor": "ONE",
        "line": "ONE",
        "cell": "ONE"
    }
}

MDE 會根據傳入訊息的 eventTimestamp 值，為這個執行個體設定版本，而這個中繼資料執行個體已傳送，且時間戳記設為今天，因此 MDE 會將這個執行個體視為該自然鍵目前收到的最新版本。這個新版本中繼資料執行個體的 validFrom 值，會是傳入訊息的 eventTimestamp 值。

現在假設您為同一個自然鍵 sensor-a 傳送歷史中繼資料執行個體 (例如去年)，值如下：


{
    "naturalKey": "sensor-a",
    "instance": {
        "site": "OLD",
        "factory": "OLD",
        "floor": "OLD",
        "line": "OLD",
        "cell": "OLD"
    }
}

在本例中，MDE 會比較這個執行個體與 eventTimestamp (例如去年) 收到時或之前可用的最新中繼資料執行個體，並將其插入時間軸的正確位置，這是 1.4.x 版和 1.5.0 版之間的基本差異。MDE 收到歷來記錄事件時，會解析事件時間的最新歷來中繼資料項目。下圖顯示處理和連結邏輯的運作方式：

中繼資料邏輯的版本管理

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

為記錄新增背景資訊時，需要將記錄連結至中繼資料執行個體。方法是在記錄中儲存中繼資料執行個體 UUID 的參照。MDE 提供兩種在剖析器中建立這個連結的方式：

提供執行個體的自然鍵。
提供 Proto 中繼資料執行個體。

舉例來說，BigQuery 資料接收器會在名為 cloud_metadata_ref 的欄位中，儲存每個 bucket 的中繼資料執行個體參照。以下範例說明中繼資料執行個體參照在 BigQuery 記錄中的顯示方式：

{
  "id": "e4b66cb9-7c60-4473-b1a1-1954eca92405",
  "tag_name": "primepaintingrobot-01-airpressure",
  "type_version": "1",
  "event_timestamp": "2023-06-20 07:11:59.757000 UTC",
  "value": "762.53",
  "embedded_metadata": {},
  "materialized_cloud_metadata": {
    "device-metadata": {
      "deviceName": "example-device"
    }
  },
  "cloud_metadata_ref": {
    "device-metadata": {
      "bucket_number": 143,
      "bucket_version": 1,
      "instance_id": "50e156a0-dbd9-4f9b-bdc8-1e77574bc4b1"
    }
  },
  "ingest_timestamp": "2023-06-20 07:12:06.335000 UTC",
  "source_message_id": "8434396321424812"
}

使用自然鍵將記錄連結至雲端中繼資料執行個體

您可以在剖析器中提供雲端中繼資料 bucket 版本的參照，以及 proto 記錄中執行個體的自然鍵，將記錄連結至中繼資料執行個體。如果執行個體有 UUID，MDE 會自動將自然鍵換成 UUID，並將連結儲存在記錄中。如果提供的自然鍵有多個執行個體，MDE 會選擇最近的執行個體 (具有最新 created_timestamp 的執行個體)。

如果參照的值區是 TAG 值區，則可選擇是否提供自然鍵。如果省略自然鍵，MDE 預設會使用 tagName 欄位的值。

如要瞭解如何使用自然鍵將記錄連結至中繼資料執行個體，請參閱「使用自然鍵解析中繼資料 instance_id」。

使用 Proto 中繼資料執行個體將記錄連結至雲端中繼資料執行個體

您可以提供雲端中繼資料 bucket 版本的參照，並提供 proto 中繼資料執行個體，以及 (選用) 在剖析器中提供 proto 記錄的自然鍵，將記錄連結至中繼資料執行個體。如果來源訊息已包含建構有效 Proto 執行個體的脈絡資訊，這個連結中繼資料執行個體的方法就特別實用。

使用 Proto 中繼資料執行個體將記錄連結至雲端中繼資料執行個體時，請注意下列事項：

如果省略自然鍵，MDE 會根據 bucket 類型自動為您選擇。
如果在 TAG bucket 的環境中省略 proto 執行個體中的自然鍵，MDE 會自動選取 tagName 做為自然鍵。

如果您在 RECORD bucket 的環境中省略 proto 執行個體中的自然鍵，MDE 會自動產生訊息物件的雜湊值，並將該值做為自然鍵。

如果提供的 proto 執行個體與所提供自然鍵的最新中繼資料執行個體相符，MDE 會將提供的 proto 執行個體換成相符執行個體的 UUID，並將 UUID 儲存在記錄中。

如果提供的 Proto 執行個體與所提供自然鍵的最新中繼資料執行個體不符，MDE 會為所提供的自然鍵建立新的中繼資料執行個體，並將新建立執行個體的 UUID 儲存在記錄中。系統的這項行為可讓您使用來源訊息產生的執行個體，動態填入中繼資料 bucket。

如要瞭解如何使用 Proto 中繼資料執行個體將記錄連結至中繼資料執行個體，請參閱「依執行個體值解析中繼資料執行個體 ID」。

執行個體具體化

記錄可以選擇性地包含整個執行個體，而不只是儲存中繼資料執行個體的 UUID。這就是所謂的具體化。您可以在類型層級為每個接收器設定這項行為，方法是將接收器的 materializeCloudMetadata 欄位值設為 true。

舉例來說，為 BigQuery 接收器啟用中繼資料具體化功能後，如果記錄包含中繼資料例項參照，就會產生類似下列的資料列：

{ "id": "e4b66cb9-7c60-4473-b1a1-1954eca92405", "tag_name": "primepaintingrobot-01-airpressure", "type_version": "1", "event_timestamp": "2023-06-20 07:11:59.757000 UTC", "value": "762.53", "embedded_metadata": {}, "materialized_cloud_metadata": { "tag":{ "bucket_number":143, "bucket_version":1, "instance":{ "datatype":"float", "deviceID":"ppr-01", "deviceName":"primepaintingrobot-01", "vendor":"KUKA" } } }, "cloud_metadata_ref": { "device-metadata": { "bucket_number": 143, "bucket_version": 1, "instance_id": "50e156a0-dbd9-4f9b-bdc8-1e77574bc4b1" } }, "ingest_timestamp": "2023-06-20 07:12:06.335000 UTC", "source_message_id": "8434396321424812" }

內嵌中繼資料

快速變更的中繼資料代表快速變更的脈絡資料。快速變更的中繼資料通常包括自動遞增的計數器和 ID，例如序號或交易 ID。

MDE 可讓您使用 Whistle 快速建構、協調及轉換快速變更的中繼資料，並在剖析器的 proto 記錄中填入名為 embeddedMetadata 的欄位，直接將中繼資料嵌入記錄。

所有支援的 MDE 資料接收器都會提供內嵌中繼資料。舉例來說，在剖析器中填入 proto 記錄的 embeddedMetadata 欄位，會在 BigQuery 中產生如下所示的結果記錄列：

{ "id": "e4b66cb9-7c60-4473-b1a1-1954eca92405", "tag_name": "primepaintingrobot-01-airpressure", "type_version": "1", "event_timestamp": "2023-06-20 07:11:59.757000 UTC", "value": "762.53", "embedded_metadata": { "transactionNumber": "1234" }, "materialized_cloud_metadata": {}, "cloud_metadata_ref": {}, "ingest_timestamp": "2023-06-20 07:12:06.335000 UTC", "source_message_id": "8434396321424812" }

自動刪除中繼資料

不論是記錄或標記中繼資料，MDE 都會追蹤每個自然鍵中發生的變更，方法是比較每個新例項與舊例項。當任何執行個體屬性發生變化時，MDE 會建立新版本，並標示為最新有效執行個體。根據設計，標記和記錄中繼資料的精細程度應為數千，且少於十萬。這些限制可讓 MDE 在中繼資料執行個體來自邊緣或 API 時建立索引，不會影響處理輸送量。

有時由於設定錯誤，剖析器會在 metadata 執行個體中插入高基數欄位 (例如時間戳記)，導致每個自然鍵的版本快速增生。超過特定門檻後，這會對擷取作業的效能造成負面影響。在某些情況下，這可能會導致處理作業完全停止，直到解決方案管理員擴充基礎雲端基礎架構服務為止。

自 1.4.0 版起，MDE 會強制執行每個自然鍵的執行個體數量上限，確保效能一致。當自然鍵數量接近這個門檻 (預設為 200) 時，MDE 會將警告傳送至新的通知 API，告知使用者有大量中繼資料執行個體版本的自然鍵。當自然鍵執行個體大小超出門檻時，MDE 會自動從內部商店刪除舊執行個體。此外，系統也會傳送另一則通知給 Notifications API，告知使用者已刪除的自然鍵。

系統也會在記錄中回報警告和刪除活動，可用於在專案 Cloud Monitoring 中建立快訊政策。

注意： 刪除作業會在內部 MDE 商店中進行，而非在 BigQuery 等目標接收器中進行。每當建立新的中繼資料例項時，MDE 就會在 BigQuery 接收器中傳送新記錄，因此使用者仍可查詢中繼資料的歷來變更。類型中連結的事實記錄不會受到影響，因為這些記錄會參照 BigQuery 接收器中的歷來中繼資料例項。

中繼資料儲存空間的命名限制

中繼資料 Bucket 名稱可包含下列項目：

字母 (大寫和小寫)、數字和特殊字元 - 和 _。

長度上限為 255 個半形字元。

您可以使用下列規則運算式進行驗證：^[a-z][a-z0-9\\-_]{1,255}$。

如果您嘗試建立違反命名限制的實體，系統會顯示 400 error。