Associer des enregistrements à des instances de métadonnées

Ce guide explique comment associer des enregistrements à des instances de métadonnées. Manufacturing Data Engine (MDE) associe les enregistrements aux instances de métadonnées en écrivant le instance_id du bucket de métadonnées dans l'enregistrement. Toutefois, vous ne définissez pas instance_id dans un enregistrement proto directement dans l'analyseur. Au lieu de cela, MDE résout automatiquement le instance_id pour vous en fonction des entrées que vous fournissez dans l'enregistrement proto. MDE propose deux façons de résoudre les problèmes dans instance_id :

Par clé naturelle de l'instance de métadonnées.
Par valeur d'instance de métadonnées.

Résoudre un instance_id de métadonnées par clé naturelle

Chaque instance de métadonnées d'un bucket de métadonnées possède une clé naturelle. Il peut y avoir plusieurs instances pour une clé naturelle. Vous pouvez associer un enregistrement à la dernière instance de métadonnées pour une clé naturelle en fournissant la clé naturelle dans l'enregistrement proto du fichier parser. MDE se charge de récupérer la dernière instance pour la clé naturelle que vous avez fournie et d'insérer le instance_id de l'instance dans l'enregistrement.

Par exemple, étant donné les instances de métadonnées suivantes dans un bucket de métadonnées d'enregistrement appelé machine avec le numéro de 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"
  }
]

Prenons l'exemple du message source suivant :

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

Le script Whistle suivant :

package mde

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

Cela produira l'enregistrement proto suivant :

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

Une fois que MDE a fini de traiter l'enregistrement proto, il génère l'enregistrement (ligne) suivant dans BigQuery (en supposant que le récepteur BigQuery et la matérialisation des métadonnées sont activés) :

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

Résoudre une valeur `instance_id` de métadonnées par instance

Vous pouvez également associer un enregistrement à la dernière instance de métadonnées pour une clé naturelle en fournissant l'intégralité de l'objet d'instance de métadonnées dans l'enregistrement proto du parser. Vous pouvez éventuellement fournir une clé naturelle. Si vous omettez la clé naturelle, MDE l'infère en fonction du type de bucket :

Si vous fournissez une valeur d'instance de métadonnées pour un bucket tag et que vous omettez la clé naturelle, MDE utilise automatiquement le nom du tag comme clé naturelle.
Si vous fournissez une valeur d'instance de métadonnées pour un bucket record et que vous omettez la clé naturelle, MDE utilise automatiquement la valeur de hachage de l'objet d'instance comme clé naturelle.

Une fois que vous avez créé un enregistrement proto dans l'analyseur, MDE compare l'objet d'instance de métadonnées fourni avec l'objet d'instance de métadonnées le plus récent pour la clé naturelle fournie.

Si les objets d'instance sont identiques, MDE insère dans l'enregistrement le instance_id de l'instance de métadonnées la plus récente pour la clé naturelle.

Si les objets d'instance ne sont pas identiques, MDE utilise l'instance de métadonnées fournie par l'enregistrement proto pour créer une instance de métadonnées pour la clé naturelle donnée. MDE insère ensuite le instance_id de l'instance nouvellement créée dans l'enregistrement.

La résolution d'un instance_id de métadonnées par valeur d'instance est particulièrement utile lorsque vos sources Edge fournissent des messages complets. Cette méthode de résolution des instances de métadonnées vous permet de faire référence à une instance existante et de créer dynamiquement de nouvelles instances de métadonnées.

Faire référence à une instance existante par valeur

Exemple d'instances de métadonnées dans un bucket de métadonnées de tag appelé asset avec le numéro de 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"
  }
]

Voici un message source :

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

Et le script Whistle suivant :

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'application du script Whistle produit l'enregistrement proto suivant :

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

Créer une instance par valeur

Si l'instance de métadonnées fournie dans l'enregistrement proto n'est pas identique à l'instance de métadonnées la plus récente pour la clé naturelle fournie, MDE crée une instance.

Vous pouvez configurer la création de la nouvelle instance à l'aide du paramètre instanceOverwriteMode sur les buckets :

Si instanceOverwriteMode est défini sur "true", la nouvelle instance est créée à partir de l'objet d'instance fourni dans l'enregistrement proto. La nouvelle instance est stockée dans le bucket de métadonnées si elle réussit la validation du schéma du bucket.
Si instanceOverwriteMode est défini sur "false", la nouvelle instance est créée en fusionnant l'instance la plus récente pour la clé naturelle avec l'objet d'instance fourni dans l'enregistrement proto. L'objet obtenu est stocké en tant que nouvelle instance de métadonnées dans le bucket de métadonnées s'il réussit la validation du schéma du bucket.

Par exemple, en utilisant l'instance de métadonnées suivante dans un bucket de métadonnées de tag appelé asset avec le numéro de 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"
  }
]

Le message source suivant :

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

Avec le script Whistle suivant :

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