Collegare i record alle istanze di metadati

Questa guida descrive come collegare i record alle istanze di metadati. Manufacturing Data Engine (MDE) collega i record alle istanze di metadati scrivendo il instance_id del bucket dei metadati nel record. Tuttavia, non imposti instance_id direttamente in un record proto nel parser. Al contrario, MDE risolve automaticamente instance_id per te in base agli input forniti nel record proto. MDE offre due modi per risolvere il problema in instance_id:

Per chiave naturale dell'istanza dei metadati.
Per valore dell'istanza dei metadati.

Risoluzione di un metadata instance_id in base alla chiave naturale

Ogni istanza di metadati in un bucket di metadati ha una chiave naturale e potrebbe esserci più di un'istanza per una chiave naturale. Puoi associare un record all'istanza di metadati più recente per una chiave naturale fornendo la chiave naturale nel record proto nel parser. MDE si occupa di recuperare l'ultima istanza per la chiave naturale che hai fornito e di inserire instance_id dell'istanza nel record.

Ad esempio, date le seguenti istanze di metadati in un bucket di metadati dei record denominato machine con numero di 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"
  }
]

Considerando il seguente messaggio di origine come esempio:

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

Il seguente script di 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
        }]
    }
]

Verrà prodotto il seguente record proto:

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

Al termine dell'elaborazione del record proto, MDE produce il seguente record (riga) in BigQuery (supponendo che il sink BigQuery e la materializzazione dei metadati siano attivi):

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

Risoluzione di un metadato `instance_id` in base al valore dell'istanza

In alternativa, puoi associare un record all'istanza di metadati più recente per una chiave naturale fornendo l'intero oggetto istanza di metadati nel record proto nel parser. Facoltativamente, puoi fornire una chiave naturale. Se ometti la chiave naturale, MDE la deduce in base al tipo di bucket:

Se fornisci un valore dell'istanza dei metadati per un bucket tag e ometti la chiave naturale, MDE utilizza automaticamente il nome del tag come chiave naturale.
Se fornisci un valore dell'istanza dei metadati per un bucket record e ometti la chiave naturale, MDE calcola automaticamente il valore hash dell'oggetto istanza come chiave naturale.

Dopo aver creato un record proto nel parser, MDE confronta l'oggetto istanza dei metadati fornito con l'oggetto istanza dei metadati più recente per la chiave naturale fornita.

Se gli oggetti istanza sono identici, MDE inserisce nel record il instance_id dell'istanza di metadati più recente per la chiave naturale.

Se gli oggetti istanza non sono identici, MDE utilizza l'istanza dei metadati fornita dal record proto per creare una nuova istanza dei metadati per la chiave naturale specificata. MDE inserisce quindi il instance_id dell'istanza appena creata nel record.

La risoluzione di un instance_id dei metadati in base al valore dell'istanza è particolarmente utile quando le origini perimetrali forniscono messaggi completi. L'utilizzo di questo metodo di risoluzione delle istanze di metadati consente di fare riferimento a un'istanza già esistente e di creare dinamicamente una nuova istanza di metadati.

Fare riferimento a un'istanza esistente per valore

Esempio di istanze di metadati in un bucket di metadati dei tag denominato asset con numero di 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"
  }
]

Dato il seguente messaggio di origine:

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

E il seguente script di 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;
              }
            }
        }]
    }
]

L'applicazione dello script Whistle produce il seguente record 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"
        }
      }
    ]
  }
]

Al termine dell'elaborazione del record proto, MDE produce il seguente record (riga) in BigQuery (supponendo che il sink BigQuery e la materializzazione dei metadati siano attivi):

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

Creazione di una nuova istanza per valore

Se l'istanza dei metadati fornita nel record proto non è identica all'istanza dei metadati più recente per la chiave naturale fornita, MDE crea una nuova istanza.

Puoi configurare la modalità di creazione della nuova istanza utilizzando l'impostazione instanceOverwriteMode sui bucket:

Se instanceOverwriteMode è impostato su true, la nuova istanza viene creata dall'oggetto istanza fornito nel record proto. La nuova istanza viene archiviata nel bucket dei metadati se supera la convalida dello schema del bucket.
Se instanceOverwriteMode è impostato su false, la nuova istanza viene creata unendo l'istanza più recente per la chiave naturale con l'oggetto istanza fornito nel record proto. L'oggetto risultante viene archiviato come nuova istanza di metadati nel bucket dei metadati se supera la convalida dello schema del bucket.

Ad esempio, data la seguente istanza di metadati in un bucket di metadati dei tag denominato asset con numero di 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"
  }
]

E il seguente messaggio di origine:

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

Con il seguente script di 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;
              }
            }
        }]
    }
]

L'applicazione dello script Whistle produce il seguente record 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"
        }
      }
    ]
  }
]

Poiché l'istanza dei metadati fornita non è equivalente all'istanza dei metadati più recente per la chiave naturale, MDE crea una nuova istanza dei metadati. Il bucket dei metadati ora ha due istanze:

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

Al termine dell'elaborazione del record proto, MDE produce il seguente record (riga) in BigQuery (supponendo che il sink BigQuery e la materializzazione dei metadati siano attivi):

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

Collegare i record alle istanze di metadati

Risoluzione di un metadata instance_id in base alla chiave naturale

Risoluzione di un metadato instance_id in base al valore dell'istanza

Fare riferimento a un'istanza esistente per valore

Creazione di una nuova istanza per valore

Risoluzione di un metadato `instance_id` in base al valore dell'istanza