Metadati

I metadati sono un concetto chiave in Manufacturing Data Engine (MDE). Rappresenta dati contestuali sui fatti. Ad esempio, letture o eventi dei sensori. I metadati aiutano a rispondere a domande come:

Quale tag ha emesso una lettura numerica?
Quale prodotto è stato elaborato al momento della lettura numerica?
A quale dispositivo appartiene un sensore?
Quale turno era in corso al momento in cui si è verificato un evento?
Quale ricetta era attiva al momento di una lettura?

MDE distingue due tipi di metadati in base alla velocità di modifica:

Modifica lenta dei metadati cloud.
Metadati incorporati in rapido cambiamento.

Metadati del cloud

I metadati a variazione lenta rappresentano dati contestuali che rimangono invariati per un periodo di tempo prolungato, ad esempio il contesto dell'asset che descrive la macchina, la cella, la linea e l'impianto di un determinato sensore. MDE ti consente di modellare, gestire ed esplorare i metadati che cambiano lentamente e collegarli ai record. Una volta collegati i metadati ai record, puoi esplorarli utilizzando il contesto associato.

I metadati che cambiano lentamente in MDE sono chiamati metadati cloud. I metadati cloud svolgono due funzioni nella soluzione:

Per contestualizzare e classificare i record.
Fungere da fonte di dati master con controllo delle versioni sulle entità di produzione, come sensori, dispositivi e linee.

MDE consente di recuperare i metadati cloud dall'edge, di crearli manualmente utilizzando l'interfaccia web MDE o di crearli a livello di programmazione utilizzando l'API. Quest'ultima consente di recuperare i metadati dai sistemi esistenti di gestione delle risorse aziendali (EAM) o di gestione dei dati master (MDM).

Bucket di metadati

I bucket di metadati cloud (chiamati anche "bucket" o "bucket di metadati") sono entità di configurazione che modellano un insieme correlato di dati contestuali a variazione lenta. Ad esempio, un bucket può modellare gli attributi di un tag o di una ricetta. I bucket possono essere considerati come dimensioni dei dati nel dominio dell'analisi dei dati.

L'attributo chiave di un bucket di metadati è il suo schema. Lo schema (espresso come oggetto schema JSON) definisce e vincola la struttura delle istanze di metadati contenute al suo interno. Puoi creare una nuova versione del bucket di metadati, ma le nuove versioni devono rispettare le regole di controllo delle versioni dei bucket.

I bucket sono globali, il che significa che possono essere referenziati da qualsiasi tipo.

Istanze dei metadati

Le istanze di metadati rappresentano i "contenuti" dei bucket di metadati cloud. Ogni istanza descrive un'entità, ad esempio un asset, un processo o un aspetto dei record acquisiti. Le istanze hanno due tipi di identificatori:

Un UUID (Universally Unique Identifier) generato dal sistema che identifica l'istanza all'interno di MDE.
Una chiave naturale che identifica l'entità al di fuori di MDE (ad esempio, un numero di serie di un sensore).

Le istanze dei metadati sono versionate in base alla chiave naturale. Ciò significa che MDE tiene traccia dell'evoluzione degli attributi per una determinata chiave naturale. Ad esempio, un tag con una chiave naturale "tag-123" potrebbe iniziare nella cella "X", ma in seguito essere spostato nella cella "Y". MDE memorizza e timestamp ogni istanza e le assegna un UUID univoco. Questo UUID univoco ti consente di recuperare la cronologia delle istanze per una chiave naturale, contestualizzare i record con l'istanza corretta durante l'importazione, nonché applicare retroattivamente un'istanza ai record precedenti al momento della query.

A partire dalla versione 1.5.0, le istanze di metadati sono versionate ed elaborate in base a event-time e non a processing time. Quando invii istanze di metadati con record storici, MDE esegue il controllo delle versioni di queste istanze di metadati in base al eventTimestamp del messaggio, in modo che i metadati storici e recenti possano coesistere senza modificare le istanze più recenti. Per saperne di più, consulta la sezione Bucket di metadati con controllo della versione.

MDE consente di aggiungere istanze a un bucket solo se conformi allo schema di una versione specifica del bucket.

Schema del bucket dei metadati

Ogni versione del bucket di metadati contiene uno schema e le istanze di metadati possono essere aggiunte solo a una versione specifica di un bucket. Gli schemi vincolano ulteriormente la struttura delle istanze di metadati che possono essere aggiunte a una versione del bucket.

Gli schemi dei bucket di metadati sono espressi come oggetti schema JSON in conformità con la versione 2019-09 della specifica dello schema JSON.

Ad esempio, se lo schema è stato aggiunto in un secondo momento a una versione del bucket, indicherebbe che ogni oggetto istanza deve avere una proprietà denominata deviceName con valore string e che questa proprietà è obbligatoria. Vedi il seguente esempio:

{
  "$schema": "https://json-schema.org/draft/2019-09/schema#",
  "type": "object",
  "properties": {
    "deviceName": {
      "type": "string"
    }
  },
  "required": ["deviceName"]
}

Convalida dell'istanza dei metadati

Per essere inserite, le istanze dei metadati devono essere conformi allo schema definito per una versione specifica del bucket dei metadati.

Tipi di bucket

MDE definisce tre tipi di bucket:

Bucket Tag
Bucket Record
Bucket Lookup

Il tipo di bucket viene definito al momento della creazione e non può essere modificato in seguito.

Bucket dei tag

I bucket di tag rappresentano i bucket che contestualizzano i tag. Ciò significa che la chiave naturale delle istanze contenute nel bucket deve essere il nome del tag.

Bucket dei record

I bucket di record rappresentano i bucket che possono contestualizzare qualsiasi gruppo di record che condividono una chiave naturale comune. La chiave naturale delle istanze del bucket di record può essere qualsiasi valore.

Bucket di ricerca

I bucket di ricerca rappresentano bucket che non contestualizzano direttamente i record, ma forniscono dati di riferimento che possono essere utilizzati nel parser. La chiave naturale delle istanze del bucket di ricerca può essere qualsiasi valore.

Le istanze del bucket di record non sono mai collegate ai record. Le istanze possono invece essere recuperate da un bucket di ricerca chiamando la funzione mde::lookupByKey in uno script Whistle. La funzione accetta come argomenti la ricerca bucketName, bucketVersion e naturalKey e restituisce l'ultima istanza dei metadati per la chiave naturale fornita. Puoi utilizzare l'istanza per compilare i campi di un record proto nel parser.

Bucket di metadati con controllo delle versioni

Lo schema dei bucket di metadati può evolvere, ma devi creare una nuova versione di un bucket per modificare lo schema. Le versioni del bucket esistenti e le entità di configurazione esistenti che fanno riferimento a versioni precedenti di un bucket non sono interessate da questa operazione. Per garantire la coerenza dei dati durante l'intero ciclo di vita di un bucket di metadati, le nuove versioni degli schemi dei bucket di metadati sono soggette alle seguenti limitazioni:

Le nuove versioni potrebbero:

Aggiungi nuovi campi facoltativi.
Contrassegnare un campo obbligatorio come facoltativo.

Le nuove versioni non possono:

Rimuovi i campi.
Modifica il tipo di dati dei campi esistenti.
Contrassegnare un attributo facoltativo come obbligatorio.

A partire dalla versione 1.5.0, la risoluzione delle istanze di metadati si basa anche sul timestamp dell'evento. Ciò significa che MDE risolve l'istanza di metadati più recente rispetto all'ora dell'evento del record. Questo generalizza il concetto di metadati di collegamento MDE per funzionare in periodi di tempo diversi, controllati dal messaggio di origine. Per migliorare la leggibilità delle query delle istanze dei metadati, MDE v1.5.0 introduce un nuovo campo denominato validFrom che indica l'ora in cui una particolare istanza dei metadati è effettiva. Questo campo viene utilizzato da MDE per verificare quale istanza di metadati scegliere in base all'ora dell'evento del messaggio di origine.

Ad esempio, per una chiave naturale sensor-a, supponiamo che oggi invii a MDE un'istanza di metadati con il seguente valore:


{
    "naturalKey": "sensor-a",
    "instance": {
        "site": "ONE",
        "factory": "ONE",
        "floor": "ONE",
        "line": "ONE",
        "cell": "ONE"
    }
}

MDE esegue il controllo delle versioni di questa istanza in base al valore eventTimestamp del messaggio in arrivo, al luogo in cui è stata inviata questa istanza di metadati e poiché il timestamp è stato impostato su oggi, MDE tratterà questa istanza come l'ultima ricevuta finora per quella chiave naturale. Il valore di validFrom per questa istanza di metadati con nuova versione sarà il valore di eventTimestamp del messaggio in arrivo.

Supponiamo ora di inviare un'istanza di metadati storici (ad esempio, l'anno scorso) per la stessa chiave naturale sensor-a con il seguente valore:


{
    "naturalKey": "sensor-a",
    "instance": {
        "site": "OLD",
        "factory": "OLD",
        "floor": "OLD",
        "line": "OLD",
        "cell": "OLD"
    }
}

In questo esempio, MDE esegue il controllo delle versioni di questa istanza confrontandola con le ultime istanze di metadati disponibili alla data di ricezione eventTimestamp o prima (ad esempio, l'anno scorso) e le inserisce nella posizione corretta nelle cronologie, che è la differenza fondamentale tra la versione 1.4.x e la 1.5.0. Quando MDE riceve eventi di record storici, risolve la voce di metadati storici più recente al momento dell'evento. Il seguente diagramma mostra come funziona la logica di elaborazione e collegamento:

Logica dei metadati del controllo delle versioni

Collegamento di istanze di metadati cloud ai record

L'aggiunta di contesto a un record prevede il collegamento di un record a un'istanza di metadati. Ciò si ottiene memorizzando un riferimento all'UUID dell'istanza dei metadati nel record. MDE offre due modi per creare questo link nel parser:

Fornendo la chiave naturale di un'istanza.
Fornendo un'istanza di metadati proto.

Ad esempio, il sink di dati BigQuery archivia i riferimenti alle istanze di metadati per bucket in un campo denominato cloud_metadata_ref. Ecco un esempio di come appare un riferimento a un'istanza di metadati in un record BigQuery:

{
  "id": "e4b66cb9-7c60-4473-b1a1-1954eca92405",
  "tag_name": "primepaintingrobot-01-airpressure",
  "type_version": "1",
  "event_timestamp": "2023-06-20 07:11:59.757000 UTC",
  "value": "762.53",
  "embedded_metadata": {},
  "materialized_cloud_metadata": {
    "device-metadata": {
      "deviceName": "example-device"
    }
  },
  "cloud_metadata_ref": {
    "device-metadata": {
      "bucket_number": 143,
      "bucket_version": 1,
      "instance_id": "50e156a0-dbd9-4f9b-bdc8-1e77574bc4b1"
    }
  },
  "ingest_timestamp": "2023-06-20 07:12:06.335000 UTC",
  "source_message_id": "8434396321424812"
}

Collegamento di un record a un'istanza di metadati cloud utilizzando la chiave naturale

Puoi collegare un record a un'istanza di metadati fornendo, nel parser, un riferimento a una versione del bucket di metadati cloud e alla chiave naturale dell'istanza nel record proto. MDE scambia automaticamente la chiave naturale con l'UUID dell'istanza, se esistente, e memorizza il link nel record. Se esistono più istanze per la chiave naturale fornita, MDE sceglie l'istanza più recente (istanza con il created_timestamp più recente).

Se il bucket a cui viene fatto riferimento è un bucket TAG, fornire una chiave naturale è facoltativo. Se la chiave naturale viene omessa, MDE utilizza il valore del campo tagName per impostazione predefinita.

Per informazioni su come collegare i record alle istanze di metadati utilizzando una chiave naturale, consulta Risoluzione di un instance_id di metadati tramite chiave naturale.

Collegamento di un record a un'istanza di metadati cloud utilizzando un'istanza di metadati proto

Puoi collegare un record a un'istanza di metadati fornendo un riferimento a una versione del bucket di metadati cloud e fornendo un'istanza di metadati proto e, facoltativamente, una chiave naturale nel record proto nel parser. Questo metodo di collegamento delle istanze di metadati è particolarmente utile se i messaggi di origine contengono già informazioni contestuali per costruire un'istanza proto valida.

Considera quanto segue quando colleghi un record a un'istanza di metadati cloud utilizzando un'istanza di metadati proto:

Se ometti la chiave naturale, MDE ne sceglie automaticamente una per te a seconda del tipo di bucket.
Se ometti la chiave naturale in un'istanza proto nel contesto di un TAGbucket, MDE sceglie automaticamente tagName come chiave naturale.
Se ometti la chiave naturale in un'istanza proto nel contesto di un RECORDbucket, MDE genera automaticamente un valore hash dell'oggetto messaggio e lo utilizza come chiave naturale.
Se l'istanza proto fornita corrisponde all'istanza dei metadati più recente per la chiave naturale fornita, MDE scambia l'istanza proto fornita con l'UUID dell'istanza corrispondente e lo archivia nel record.
Se l'istanza proto fornita non corrisponde all'istanza di metadati più recente per la chiave naturale fornita, MDE crea una nuova istanza di metadati per la chiave naturale fornita e memorizza l'UUID dell'istanza appena creata nel record. Questo comportamento del sistema ti consente di compilare dinamicamente i bucket di metadati con le istanze generate dai messaggi di origine.

Per informazioni su come collegare i record alle istanze di metadati utilizzando un'istanza di metadati proto, consulta Risoluzione di un ID istanza di metadati in base al valore dell'istanza.

Materializzazione dell'istanza

Anziché memorizzare solo l'UUID di un'istanza di metadati, i record possono includere facoltativamente l'intera istanza. Questa operazione viene chiamata materializzazione. Questo comportamento può essere configurato per ogni sink a livello di tipo impostando il valore del campo materializeCloudMetadata per un sink su true.

Ad esempio, l'attivazione della materializzazione dei metadati per il sink BigQuery produrrà una riga simile alla seguente per un record che contiene un riferimento all'istanza dei metadati:

{
  "id": "e4b66cb9-7c60-4473-b1a1-1954eca92405",
  "tag_name": "primepaintingrobot-01-airpressure",
  "type_version": "1",
  "event_timestamp": "2023-06-20 07:11:59.757000 UTC",
  "value": "762.53",
  "embedded_metadata": {},
  "materialized_cloud_metadata": {
     "tag":{
       "bucket_number":143,
       "bucket_version":1,
       "instance":{
         "datatype":"float",
         "deviceID":"ppr-01",
         "deviceName":"primepaintingrobot-01",
         "vendor":"KUKA"
       }
     }
  },
  "cloud_metadata_ref": {
    "device-metadata": {
      "bucket_number": 143,
      "bucket_version": 1,
      "instance_id": "50e156a0-dbd9-4f9b-bdc8-1e77574bc4b1"
    }
  },
  "ingest_timestamp": "2023-06-20 07:12:06.335000 UTC",
  "source_message_id": "8434396321424812"
}

Metadati incorporati

I metadati in rapido cambiamento rappresentano dati contestuali che cambiano a un ritmo veloce. Esempi tipici di metadati in rapida evoluzione includono contatori e ID con incremento automatico, ad esempio numeri di serie o ID transazione.

MDE ti consente di strutturare, armonizzare e trasformare i metadati in rapida evoluzione utilizzando Whistle e di incorporarli direttamente nel record compilando un campo denominato embeddedMetadata nel record proto nel parser.

Tutti i sink di dati MDE supportati rendono disponibili i metadati incorporati. Ad esempio, il riempimento del campo embeddedMetadata nel record proto nel parser produrrebbe una riga come questa per il record risultante in BigQuery:

{
  "id": "e4b66cb9-7c60-4473-b1a1-1954eca92405",
  "tag_name": "primepaintingrobot-01-airpressure",
  "type_version": "1",
  "event_timestamp": "2023-06-20 07:11:59.757000 UTC",
  "value": "762.53",
  "embedded_metadata": {
    "transactionNumber": "1234"
  },
  "materialized_cloud_metadata": {},
  "cloud_metadata_ref": {},
  "ingest_timestamp": "2023-06-20 07:12:06.335000 UTC",
  "source_message_id": "8434396321424812"
}

Eliminazione automatica dei metadati

Per entrambi, i metadati del record e del tag, MDE tiene traccia delle modifiche apportate a ogni chiave naturale confrontando ogni nuova istanza con quella precedente. Quando viene modificato uno degli attributi dell'istanza, MDE crea una nuova versione e la contrassegna come l'istanza effettiva più recente. Per progettazione, i metadati dei tag e dei record devono avere una granularità di migliaia e inferiore a centomila. Queste limitazioni consentono a MDE di indicizzare le istanze di metadati così come provengono dall'edge o dall'API senza influire sulla velocità effettiva di elaborazione.

A volte, a causa di errori di configurazione, il parser inserisce un campo ad alta cardinalità come un timestamp nell'istanza dei metadati, il che comporta una rapida proliferazione di versioni per ogni chiave naturale. Dopo una determinata soglia, questo influisce negativamente sul rendimento dell'importazione. In alcuni casi, potrebbe comportare l'interruzione completa dell'elaborazione finché i servizi di infrastruttura cloud sottostanti non vengono scalati dall'amministratore della soluzione.

A partire dalla versione 1.4.0, MDE applica un numero massimo di istanze per chiave naturale per garantire prestazioni coerenti. Quando il numero di chiavi naturali si avvicina a questa soglia (il valore predefinito è 200), MDE invierà un avviso alla nuova API Notifications per informare l'utente delle chiavi naturali che hanno un numero elevato di versioni dell'istanza dei metadati. Quando le dimensioni dell'istanza con chiavi naturali superano la soglia, MDE elimina automaticamente le istanze precedenti dall'archivio interno. Invierà anche un'altra notifica all'API Notifications per informare l'utente delle chiavi naturali eliminate.

Sia l'avviso che le attività di eliminazione vengono segnalati anche nel log, che può essere utilizzato per creare un criterio di avviso nel progetto Cloud Monitoring.

Limitazioni di denominazione per i bucket di metadati

Un nome di bucket di metadati può contenere:

Lettere (maiuscole e minuscole), numeri e i caratteri speciali - e _.
Può contenere fino a 255 caratteri.

Puoi utilizzare la seguente espressione regolare per la convalida: ^[a-z][a-z0-9\\-_]{1,255}$.

Se tenti di creare un'entità che viola le limitazioni di denominazione, riceverai un 400 error.