Vincula registros a instancias de metadatos

En esta guía, se describe cómo vincular registros a instancias de metadatos. Manufacturing Data Engine (MDE) vincula los registros a las instancias de metadatos escribiendo el instance_id del bucket de metadatos en el registro. Sin embargo, no estableces instance_id en un registro .proto del analizador directamente. En cambio, MDE resuelve automáticamente el instance_id por ti según los datos que proporcionas en el registro .proto. El MDE proporciona dos formas de resolver en instance_id:

Es la clave natural de la instancia de metadatos.
Por valor de instancia de metadatos.

Cómo resolver un instance_id de metadatos por clave natural

Cada instancia de metadatos en un bucket de metadatos tiene una clave natural, y puede haber más de una instancia para una clave natural. Puedes asociar un registro a la instancia de metadatos más reciente para una clave natural si proporcionas la clave natural en el registro .proto del analizador. MDE se encarga de recuperar la instancia más reciente para la clave natural que proporcionaste y de insertar el instance_id de la instancia en el registro.

Por ejemplo, dadas las siguientes instancias de metadatos en un bucket de metadatos de registros llamado machine con el número 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"
  }
]

Y, dado el siguiente mensaje fuente como ejemplo:

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

La siguiente secuencia de comandos de 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
        }]
    }
]

Se producirá el siguiente registro .proto:

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

Después de que el MDE termina de procesar el registro .proto, genera el siguiente registro (fila) en BigQuery (suponiendo que el receptor de BigQuery y la materialización de metadatos estén activados):

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

Cómo resolver un valor de metadatos `instance_id` por instancia

Como alternativa, puedes asociar un registro a la instancia de metadatos latest para una clave natural si proporcionas el objeto de instancia de metadatos completo en el registro .proto del analizador. De manera opcional, puedes proporcionar una clave natural. Si omites la clave natural, el MDE la inferirá según el tipo de bucket:

Si proporcionas un valor de instancia de metadatos para un bucket de etiqueta y omites la clave natural, MDE usará automáticamente el nombre de la etiqueta como clave natural.
Si proporcionas un valor de instancia de metadatos para un bucket de registro y omites la clave natural, el MDE calcula automáticamente el valor hash del objeto de instancia como la clave natural.

Después de que construyes un registro .proto en el analizador, MDE compara el objeto de instancia de metadatos proporcionado con el objeto de instancia de metadatos más reciente para la clave natural proporcionada.

Si los objetos de instancia son idénticos, MDE inserta en el registro el instance_id de la instancia de metadatos más reciente para la clave natural.

Si los objetos de instancia no son idénticos, el MDE usa la instancia de metadatos proporcionada por el registro .proto para crear una nueva instancia de metadatos para la clave natural determinada. Luego, MDE inserta el instance_id de la instancia recién creada en el registro.

Resolver un instance_id de metadatos por valor de instancia es particularmente útil cuando tus fuentes perimetrales entregan mensajes completamente calificados. Con este método para resolver instancias de metadatos, puedes hacer referencia a una instancia existente y crear instancias de metadatos nuevas de forma dinámica.

Cómo hacer referencia a una instancia existente por valor

Ejemplo de instancias de metadatos en un bucket de metadatos de etiquetas llamado asset con el número 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"
  }
]

Dado que el siguiente es un mensaje fuente:

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

Y la siguiente secuencia de comandos de 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;
              }
            }
        }]
    }
]

Si se aplica el script de Whistle, se produce el siguiente registro .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"
        }
      }
    ]
  }
]

Después de que MDE termina de procesar el registro .proto, genera el siguiente registro (fila) en BigQuery (suponiendo que el receptor de BigQuery y la materialización de metadatos estén activados):

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

Cómo crear una instancia nueva por valor

Si la instancia de metadatos proporcionada en el registro .proto no es idéntica a la instancia de metadatos más reciente para la clave natural proporcionada, MDE crea una instancia nueva.

Puedes configurar cómo se crea la instancia nueva con el parámetro de configuración instanceOverwriteMode en los buckets:

Si instanceOverwriteMode se establece como verdadero, la instancia nueva se crea a partir del objeto de instancia proporcionado en el registro proto. La instancia nueva se almacena en el bucket de metadatos si pasa la validación del esquema del bucket.
Si instanceOverwriteMode se establece en falso, la nueva instancia se crea combinando la instancia más reciente de la clave natural con el objeto de instancia proporcionado en el registro de proto. El objeto resultante se almacena como una nueva instancia de metadatos en el bucket de metadatos si pasa la validación del esquema del bucket.

Por ejemplo, dada la siguiente instancia de metadatos en un bucket de metadatos de etiquetas llamado asset con el número 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"
  }
]

Y el siguiente mensaje fuente:

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

Con la siguiente secuencia de comandos de 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;
              }
            }
        }]
    }
]