Vincular registros a instâncias de metadados

Neste guia, descrevemos como vincular registros a instâncias de metadados. O Manufacturing Data Engine (MDE) vincula registros a instâncias de metadados gravando o instance_id do bucket de metadados no registro. No entanto, você não define o instance_id diretamente em um registro proto no analisador. Em vez disso, o MDE resolve automaticamente o instance_id para você com base nas entradas fornecidas no registro proto. O MDE oferece duas maneiras de resolver em instance_id:

Pela chave natural da instância de metadados.
Por valor da instância de metadados.

Como resolver um instance_id de metadados por chave natural

Cada instância de metadados em um bucket tem uma chave natural, e pode haver mais de uma instância para uma chave natural. É possível associar um registro à instância de metadados mais recente de uma chave natural fornecendo a chave natural no registro proto no analisador. O MDE recupera a instância mais recente da chave natural fornecida e insere o instance_id da instância no registro.

Por exemplo, considerando as seguintes instâncias de metadados em um bucket de metadados de registro chamado machine com o número 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"
  }
]

E considerando a seguinte mensagem de origem como exemplo:

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

O seguinte script do 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
        }]
    }
]

que vai gerar o seguinte registro proto:

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

Depois que o MDE termina de processar o registro proto, ele gera o seguinte registro (linha) no BigQuery (supondo que o gravador do BigQuery e a materialização de metadados estejam ativados):

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

Como resolver um metadado `instance_id` por valor de instância

Como alternativa, é possível associar um registro à instância de metadados latest para uma chave natural fornecendo todo o objeto da instância de metadados no registro proto no analisador. Você também pode fornecer uma chave natural. Se você omitir a chave natural, o MDE vai inferir com base no tipo de agrupamento em intervalos:

Se você fornecer um valor de instância de metadados para um bucket de tag e omitir a chave natural, o MDE usará automaticamente o nome da tag como chave natural.
Se você estiver fornecendo um valor de instância de metadados para um bucket de registro e omitir a chave natural, o MDE vai usar automaticamente o valor de hash do objeto de instância como a chave natural.

Depois de construir um registro proto no analisador, o MDE compara o objeto de instância de metadados fornecido com o objeto de instância de metadados mais recente para a chave natural fornecida.

Se os objetos de instância forem idênticos, o MDE vai inserir no registro o instance_id da instância de metadados mais recente para a chave natural.

Se os objetos de instância não forem idênticos, o MDE usará a instância de metadados fornecida pelo registro proto para criar uma nova instância de metadados para a chave natural especificada. Em seguida, o MDE insere o instance_id da instância recém-criada no registro.

Resolver um instance_id de metadados por valor de instância é especialmente útil quando suas fontes de borda entregam mensagens totalmente qualificadas. Com esse método de resolução de instâncias de metadados, é possível referenciar uma instância já existente e criar uma nova instância de metadados de forma dinâmica.

Como referenciar uma instância por valor

Exemplo de instâncias de metadados em um bucket de metadados de tag chamado asset com o número 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"
  }
]

Considere que esta é uma mensagem de origem:

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

E o seguinte script do 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;
              }
            }
        }]
    }
]

Aplicar o script Whistle produz o seguinte 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"
        }
      }
    ]
  }
]

Depois que o MDE termina de processar o registro proto, ele gera o seguinte registro (linha) no BigQuery (supondo que o coletor do BigQuery e a materialização de metadados estejam ativados):

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

Criar uma nova instância por valor

Se a instância de metadados fornecida no registro do proto não for idêntica à instância de metadados mais recente da chave natural fornecida, o MDE vai criar uma nova instância.

É possível configurar como a nova instância é criada usando a configuração instanceOverwriteMode em buckets:

Se instanceOverwriteMode for definido como "true", a nova instância será criada com base no objeto de instância fornecido no registro proto. A nova instância é armazenada no bucket de metadados se passar na validação de esquema do bucket.
Se instanceOverwriteMode for definido como "false", a nova instância será criada mesclando a instância mais recente da chave natural com o objeto de instância fornecido no registro proto. O objeto resultante é armazenado como uma nova instância de metadados no bucket de metadados se passar na validação de esquema do bucket.

Por exemplo, considerando a seguinte instância de metadados em um bucket de metadados de tag chamado asset com o número do 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 a seguinte mensagem de origem:

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

Com o seguinte script do 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;
              }
            }
        }]
    }
]