将记录关联到元数据实例

本指南介绍了如何将记录关联到元数据实例。 Manufacturing Data Engine (MDE) 通过将元数据存储桶的 instance_id 写入记录，将记录关联到元数据实例。不过，您无法直接在解析器中的 proto 记录中设置 instance_id。相反，MDE 会根据您在 proto 记录中提供的输入自动为您解析 instance_id。MDE 提供了两种在 instance_id 中解决问题的方式：

按元数据实例自然键。
按元数据实例值。

通过自然键解析元数据 instance_id

元数据存储桶中的每个元数据实例都有一个自然键，并且一个自然键可能对应多个实例。您可以在解析器中通过在 proto 记录中提供自然键，将记录与自然键的最新元数据实例相关联。MDE 会负责检索您提供的自然键的最新实例，并将该实例的 instance_id 插入到记录中。

例如，假设在存储桶编号为 1 的记录元数据存储桶（名为 machine）中存在以下元数据实例：

[
  {
    "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 sink 和元数据具体化已开启）：

[
  {
    "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`

或者，您也可以通过在解析器中的 proto 记录中提供整个元数据实例对象，将记录与自然键的最新元数据实例相关联。您可以视需要提供自然键。如果您省略自然键，MDE 会根据分桶类型推断自然键：

如果您要为 tag 桶提供元数据实例值，但省略了自然键，MDE 会自动将标记名称用作自然键。
如果您要为记录存储桶提供元数据实例值，但省略了自然键，MDE 会自动将实例对象的哈希值作为自然键。

在解析器中构建 proto 记录后，MDE 会将提供的元数据实例对象与所提供自然键的最新元数据实例对象进行比较。

如果实例对象相同，MDE 会将自然键的最新元数据实例的 instance_id 插入到记录中。

如果实例对象不相同，MDE 会使用 proto 记录提供的元数据实例为给定的自然键创建新的元数据实例。然后，MDE 会将新创建的实例的 instance_id 插入到记录中。

当边缘来源提供完全限定的消息时，按实例值解析元数据 instance_id 特别有用。使用此方法解析元数据实例可让您引用现有实例，并动态创建新的元数据实例。

按值引用现有实例

以下示例展示了标记元数据存储桶（名为 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"
  },
  {
    "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 记录中提供的实例对象合并来创建新实例。如果生成的对象通过了存储桶的架构验证，则会作为新的元数据实例存储在元数据存储桶中。

例如，假设在存储桶编号为 1 的标记元数据存储桶（名为 asset）中，有以下元数据实例：

[
  {
    "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;
              }
            }
        }]
    }
]