Datensätze mit Metadateninstanzen verknüpfen

In diesem Leitfaden wird beschrieben, wie Sie Datensätze mit Metadateninstanzen verknüpfen. In Manufacturing Data Engine (MDE) werden Datensätze mit Metadateninstanzen verknüpft, indem die instance_id des Metadaten-Buckets in den Datensatz geschrieben wird. Sie legen instance_id jedoch nicht direkt in einem Proto-Datensatz im Parser fest. Stattdessen löst MDE die instance_id automatisch für Sie auf, basierend auf den Eingaben, die Sie im Proto-Datensatz machen. MDE bietet zwei Möglichkeiten, instance_id aufzulösen:

Nach dem natürlichen Schlüssel der Metadateninstanz.
Nach Metadateninstanzwert.

Auflösen einer Metadaten-instance_id nach natürlichem Schlüssel

Jede Metadateninstanz in einem Metadaten-Bucket hat einen natürlichen Schlüssel. Es kann mehr als eine Instanz für einen natürlichen Schlüssel geben. Sie können einen Datensatz der aktuellsten Metadateninstanz für einen natürlichen Schlüssel zuordnen, indem Sie den natürlichen Schlüssel im Proto-Datensatz im Parser angeben. MDE ruft die letzte Instanz für den von Ihnen angegebenen natürlichen Schlüssel ab und fügt die instance_id der Instanz in den Datensatz ein.

Angenommen, Sie haben die folgenden Metadateninstanzen in einem Bucket mit Datensatzmetadaten namens machine mit der Bucket-Nummer 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"
  }
]

Angenommen, die folgende Quellnachricht ist ein Beispiel:

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

Das folgende Whistle-Skript:

package mde

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

Dadurch wird der folgende Proto-Datensatz generiert:

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

Nachdem MDE die Verarbeitung des Proto-Datensatzes abgeschlossen hat, wird der folgende Datensatz (Zeile) in BigQuery erstellt (vorausgesetzt, die BigQuery-Senke und die Materialisierung von Metadaten sind aktiviert):

[
  {
    "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`-Metadaten nach Instanzwert auflösen

Alternativ können Sie einen Datensatz der Metadateninstanz latest für einen natürlichen Schlüssel zuordnen, indem Sie das gesamte Metadateninstanzobjekt im Proto-Datensatz im Parser angeben. Optional können Sie einen natürlichen Schlüssel angeben. Wenn Sie den natürlichen Schlüssel weglassen, leitet MDE ihn anhand des Bucket-Typs ab:

Wenn Sie einen Metadateninstanzwert für einen Tag-Bucket angeben und den natürlichen Schlüssel weglassen, verwendet MDE automatisch den Tag-Namen als natürlichen Schlüssel.
Wenn Sie einen Metadateninstanzwert für einen record-Bucket angeben und den natürlichen Schlüssel weglassen, verwendet MDE automatisch den Hashwert des Instanzobjekts als natürlichen Schlüssel.

Nachdem Sie einen Proto-Datensatz im Parser erstellt haben, vergleicht MDE das bereitgestellte Metadateninstanzobjekt mit dem neuesten Metadateninstanzobjekt für den angegebenen natürlichen Schlüssel.

Wenn die Instanzobjekte identisch sind, fügt MDE die instance_id der letzten Metadateninstanz für den natürlichen Schlüssel in den Datensatz ein.

Wenn die Instanzobjekte nicht identisch sind, verwendet MDE die vom Proto-Datensatz bereitgestellte Metadateninstanz, um eine neue Metadateninstanz für den angegebenen natürlichen Schlüssel zu erstellen. MDE fügt dann die instance_id der neu erstellten Instanz in den Datensatz ein.

Das Auflösen einer Metadaten-instance_id nach Instanzwert ist besonders nützlich, wenn Ihre Edge-Quellen vollständig qualifizierte Nachrichten liefern. Mit dieser Methode zum Auflösen von Metadateninstanzen können Sie auf eine bereits vorhandene Instanz verweisen und gleichzeitig dynamisch neue Metadateninstanzen erstellen.

Auf eine vorhandene Instanz nach Wert verweisen

Beispiel für Metadateninstanzen in einem Tag-Metadaten-Bucket mit dem Namen asset und der Bucket-Nummer 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"
  }
]

Angenommen, die folgende Nachricht ist eine Quellnachricht:

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

Und das folgende Whistle-Skript:

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

Wenn Sie das Whistle-Skript anwenden, wird der folgende Proto-Datensatz erstellt:

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

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

Neue Instanz nach Wert erstellen

Wenn die bereitgestellte Metadateninstanz im Proto-Datensatz nicht mit der letzten Metadateninstanz für den angegebenen natürlichen Schlüssel identisch ist, erstellt MDE eine neue Instanz.

Sie können konfigurieren, wie die neue Instanz erstellt wird, indem Sie die Einstellung instanceOverwriteMode für Buckets verwenden:

Wenn instanceOverwriteMode auf „true“ gesetzt ist, wird die neue Instanz aus dem im Proto-Datensatz angegebenen Instanzobjekt erstellt. Die neue Instanz wird im Metadaten-Bucket gespeichert, wenn sie die Schemavalidierung des Buckets besteht.
Wenn instanceOverwriteMode auf „false“ gesetzt ist, wird die neue Instanz durch Zusammenführen der letzten Instanz für den natürlichen Schlüssel mit dem im Proto-Datensatz bereitgestellten Instanzobjekt erstellt. Das resultierende Objekt wird als neue Metadateninstanz im Metadaten-Bucket gespeichert, wenn es die Schemavalidierung des Buckets besteht.

Angenommen, Sie haben die folgende Metadateninstanz in einem Tag-Metadaten-Bucket namens asset mit der Bucket-Nummer 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"
  }
]

Und die folgende Quellnachricht:

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

Mit dem folgenden Whistle-Skript:

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