Métadonnées

Les métadonnées sont un concept clé dans Manufacturing Data Engine (MDE). Il représente les données contextuelles sur les faits. Par exemple, les lectures ou les événements des capteurs. Les métadonnées permettent de répondre à des questions telles que les suivantes :

Quelle balise a émis une lecture numérique ?
Quel produit était en cours de traitement au moment de la lecture numérique ?
À quel appareil appartient un capteur ?
Quel service était en cours au moment de l'événement ?
Quelle recette était active au moment de la lecture ?

MDE distingue deux types de métadonnées en fonction de leur rythme de changement :

Métadonnées cloud à évolution lente.
Métadonnées intégrées qui évoluent rapidement.

Métadonnées cloud

Les métadonnées à évolution lente représentent des données contextuelles qui restent inchangées pendant une longue période. Par exemple, le contexte d'un asset qui décrit la machine, la cellule, la ligne et l'usine d'un capteur donné. MDE vous permet de modéliser, de gérer et d'explorer vos métadonnées à évolution lente, et de les associer à des enregistrements. Une fois les métadonnées associées aux enregistrements, vous pouvez explorer ces derniers à l'aide du contexte associé.

Les métadonnées à changement lent dans MDE sont appelées métadonnées cloud. Les métadonnées Cloud remplissent deux fonctions dans la solution :

Pour contextualiser et catégoriser les enregistrements.
Servir de source de données de référence versionnées sur les entités de fabrication, telles que les capteurs, les appareils et les lignes.

MDE permet d'obtenir des métadonnées cloud à partir du périphérique Edge, de les créer manuellement à l'aide de l'interface Web MDE ou de les créer par programmation à l'aide de l'API. Cette dernière vous permet d'obtenir des métadonnées à partir de systèmes existants de gestion des actifs d'entreprise (EAM, Enterprise Asset Management) ou de gestion des données de référence (MDM, Master Data Management).

Buckets de métadonnées

Les buckets de métadonnées cloud (également appelés "buckets" ou "buckets de métadonnées") sont des entités de configuration qui modélisent un ensemble associé de données contextuelles qui évoluent lentement. Par exemple, un bucket peut modéliser les attributs d'un tag ou d'une recette. Les buckets peuvent être considérés comme des dimensions de données dans le domaine de l'analyse des données.

L'attribut clé d'un bucket de métadonnées est son schéma. Le schéma (exprimé sous la forme d'un objet de schéma JSON) définit et contraint la structure des instances de métadonnées qu'il contient. Vous pouvez créer une version de bucket de métadonnées, mais les nouvelles versions doivent respecter les règles de gestion des versions des buckets de métadonnées cloud.

Les buckets sont globaux, ce qui signifie qu'ils peuvent être référencés par n'importe quel type.

Instances de métadonnées

Les instances de métadonnées représentent le "contenu" des buckets de métadonnées cloud. Chaque instance décrit une entité, telle qu'un composant, un processus ou un aspect des enregistrements capturés. Les instances comportent deux types d'identifiants :

UUID (identifiant unique universel) généré par le système qui identifie l'instance dans MDE.
Une clé naturelle qui identifie l'entité en dehors de MDE (par exemple, le numéro de série d'un capteur).

Les instances de métadonnées sont versionnées sur la clé naturelle. Cela signifie que MDE suit l'évolution des attributs pour une clé naturelle donnée. Par exemple, un tag avec une clé naturelle "tag-123" peut commencer dans la cellule "X", mais être déplacé ultérieurement vers la cellule "Y". MDE stocke et horodate chaque instance, et lui attribue un UUID unique. Cet UUID unique vous permet de récupérer l'historique des instances pour une clé naturelle, de contextualiser les enregistrements avec la bonne instance lors de l'ingestion, et d'appliquer rétroactivement une instance aux enregistrements passés au moment de la requête.

À partir de la version 1.5.0, les instances de métadonnées sont versionnées et traitées en fonction de event-time et non de processing time. Lorsque vous envoyez des instances de métadonnées avec des enregistrements historiques, MDE les versionne en fonction du eventTimestamp du message. Cela permet aux métadonnées historiques et récentes de coexister sans modifier les dernières instances. Pour en savoir plus, consultez Gestion des versions des buckets de métadonnées.

MDE n'autorise l'ajout d'instances à un bucket que si elles respectent le schéma d'une version spécifique de ce bucket.

Schéma de bucket de métadonnées

Chaque version de bucket de métadonnées contient un schéma. Les instances de métadonnées ne peuvent être ajoutées qu'à une version spécifique d'un bucket. Les schémas limitent davantage la structure des instances de métadonnées qui peuvent être ajoutées à une version de bucket.

Les schémas de buckets de métadonnées sont exprimés sous forme d'objets de schéma JSON conformément à la version 2019-09 de la spécification du schéma JSON.

Par exemple, si le schéma a été ajouté ultérieurement à une version de bucket, il indiquerait que chaque objet d'instance doit comporter une propriété appelée deviceName avec la valeur string, et que cette propriété est obligatoire. Consultez l'exemple ci-dessous :

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

Validation des instances de métadonnées

Pour pouvoir être insérées, les instances de métadonnées doivent respecter le schéma défini pour une version spécifique du bucket de métadonnées.

Types de buckets

MDE définit trois types de buckets :

Taguer des buckets
Buckets Record
Buckets Lookup

Le type d'un bucket est défini lors de sa création et ne peut pas être modifié par la suite.

Ajouter des tags aux buckets

Les buckets de tags représentent des buckets qui contextualisent les tags. Cela signifie que la clé naturelle des instances contenues dans le bucket doit être le nom du tag.

Buckets d'enregistrements

Les buckets d'enregistrements représentent des buckets qui peuvent contextualiser n'importe quel groupe d'enregistrements partageant une clé naturelle commune. La clé naturelle des instances de bucket d'enregistrement peut être n'importe quelle valeur.

Buckets de recherche

Les buckets de recherche représentent des buckets qui ne contextualisent pas directement les enregistrements, mais fournissent plutôt des données de référence pouvant être utilisées dans l'analyseur. La clé naturelle des instances de bucket de recherche peut être n'importe quelle valeur.

Les instances de bucket d'enregistrements ne sont jamais associées à des enregistrements. Au lieu de cela, les instances peuvent être récupérées à partir d'un bucket de recherche en appelant la fonction mde::lookupByKey dans un script Whistle. La fonction prend les bucketName, bucketVersion et naturalKey de recherche comme arguments, et renvoie la dernière instance de métadonnées pour la clé naturelle fournie. Vous pouvez utiliser l'instance pour remplir les champs d'un enregistrement proto dans l'analyseur.

Gestion des versions des buckets de métadonnées

Le schéma des buckets de métadonnées peut évoluer. Toutefois, vous devez créer une version d'un bucket pour modifier le schéma. Les versions de bucket existantes et les entités de configuration existantes qui font référence à des versions antérieures d'un bucket ne sont pas affectées par cette opération. Pour garantir la cohérence des données tout au long de la durée de vie d'un bucket de métadonnées, les nouvelles versions des schémas de buckets de métadonnées sont soumises aux restrictions suivantes :

Les nouvelles versions peuvent :

Ajoutez de nouveaux champs facultatifs.
Marquer un champ obligatoire comme facultatif.

Les nouvelles versions ne doivent pas :

Supprimez les champs.
Modifier le type de données des champs existants
Marquez un attribut facultatif comme obligatoire.

À partir de la version 1.5.0, la résolution des instances de métadonnées est également basée sur le code temporel de l'événement. Cela signifie que MDE résout l'instance de métadonnées la plus récente par rapport à l'heure de l'événement de l'enregistrement. Cela généralise le concept de métadonnées de mise en correspondance MDE pour fonctionner à différentes époques, qui sont contrôlées par le message source. Pour améliorer la lisibilité des requêtes des instances de métadonnées, MDE v1.5.0 introduit un nouveau champ appelé validFrom, qui indique l'heure à laquelle une instance de métadonnées spécifique est effective. Ce champ est utilisé par MDE pour vérifier quelle instance de métadonnées choisir en fonction de l'heure de l'événement du message source.

Par exemple, pour une clé naturelle sensor-a, supposons que vous envoyiez aujourd'hui à MDE une instance de métadonnées avec la valeur suivante :


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

MDE attribue une version à cette instance en fonction de la valeur eventTimestamp du message entrant, de l'emplacement où cette instance de métadonnées a été envoyée et du fait que le code temporel a été défini sur la date du jour. MDE traitera donc cette instance comme la toute dernière reçue jusqu'à présent pour cette clé naturelle. La valeur de validFrom pour cette instance de métadonnées nouvellement versionnée sera la valeur de eventTimestamp du message entrant.

Supposons maintenant que vous envoyiez une instance de métadonnées historiques (par exemple, l'année dernière) pour la même clé naturelle sensor-a avec la valeur suivante :


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

Dans cet exemple, MDE versionne cette instance en la comparant aux dernières instances de métadonnées disponibles à la date de réception eventTimestamp ou avant (par exemple, l'année dernière). Il l'insère ensuite au bon endroit dans les chronologies, ce qui constitue la différence fondamentale entre les versions 1.4.x et 1.5.0. Lorsque MDE reçoit des événements d'historique des enregistrements, il résout l'entrée de métadonnées historiques la plus récente au moment de l'événement. Le schéma suivant illustre le fonctionnement de la logique de traitement et d'association :

Logique de gestion des versions des métadonnées

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

Ajouter du contexte à un enregistrement consiste à associer un enregistrement à une instance de métadonnées. Pour ce faire, une référence à l'UUID de l'instance de métadonnées est stockée dans l'enregistrement. MDE propose deux façons de créer ce lien dans l'analyseur :

en fournissant la clé naturelle d'une instance.
En fournissant une instance de métadonnées proto.

Par exemple, le récepteur de données BigQuery stocke les références aux instances de métadonnées par bucket dans un champ appelé cloud_metadata_ref. Voici un exemple de référence d'instance de métadonnées dans un enregistrement 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"
}

Associer un enregistrement à une instance de métadonnées cloud à l'aide d'une clé naturelle

Vous pouvez associer un enregistrement à une instance de métadonnées en fournissant, dans l'analyseur, une référence à une version de bucket de métadonnées cloud et à la clé naturelle de l'instance dans l'enregistrement proto. MDE échange automatiquement la clé naturelle contre l'UUID de l'instance, le cas échéant, et stocke le lien dans l'enregistrement. S'il existe plusieurs instances pour la clé naturelle fournie, MDE sélectionne l'instance la plus récente (celle avec le created_timestamp le plus récent).

Si le bucket référencé est un bucket TAG, il n'est pas obligatoire de fournir une clé naturelle. Si la clé naturelle est omise, MDE utilise par défaut la valeur du champ tagName.

Pour savoir comment associer des enregistrements à des instances de métadonnées à l'aide d'une clé naturelle, consultez Résoudre un instance_id de métadonnées par clé naturelle.

Associer un enregistrement à une instance de métadonnées cloud à l'aide d'une instance de métadonnées proto

Vous pouvez associer un enregistrement à une instance de métadonnées en fournissant une référence à une version de bucket de métadonnées cloud, ainsi qu'une instance de métadonnées proto et, éventuellement, une clé naturelle dans l'enregistrement proto du parser. Cette méthode d'association d'instances de métadonnées est particulièrement utile si les messages sources contiennent déjà des informations contextuelles permettant de construire une instance proto valide.

Tenez compte des points suivants lorsque vous associez un enregistrement à une instance de métadonnées cloud à l'aide d'une instance de métadonnées proto :

Si vous omettez la clé naturelle, MDE en choisit automatiquement une pour vous en fonction du type de bucket.
Si vous omettez la clé naturelle dans une instance proto dans le contexte d'un bucket TAG, MDE choisit automatiquement tagName comme clé naturelle.
Si vous omettez la clé naturelle dans une instance proto dans le contexte d'un bucket RECORD, MDE génère automatiquement une valeur de hachage de l'objet de message et l'utilise comme clé naturelle.
Si l'instance proto fournie correspond à l'instance de métadonnées la plus récente pour la clé naturelle fournie, MDE échange l'instance proto fournie contre l'UUID de l'instance correspondante et stocke l'UUID dans l'enregistrement.
Si l'instance proto fournie ne correspond pas à l'instance de métadonnées la plus récente pour la clé naturelle fournie, MDE crée une instance de métadonnées pour la clé naturelle fournie et stocke l'UUID de l'instance nouvellement créée dans l'enregistrement. Ce comportement du système vous permet de remplir dynamiquement les buckets de métadonnées avec des instances générées à partir de messages sources.

Pour savoir comment associer des enregistrements à des instances de métadonnées à l'aide d'une instance de métadonnées proto, consultez Résoudre un ID d'instance de métadonnées par valeur d'instance.

Matérialisation des instances

Au lieu de simplement stocker l'UUID d'une instance de métadonnées, les enregistrements peuvent éventuellement inclure l'instance entière. C'est ce qu'on appelle la matérialisation. Ce comportement peut être configuré pour chaque récepteur au niveau du type, en définissant la valeur du champ materializeCloudMetadata d'un récepteur sur true.

Par exemple, l'activation de la matérialisation des métadonnées pour le récepteur BigQuery générera une ligne semblable à la suivante pour un enregistrement contenant une référence d'instance de métadonnées :

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

Métadonnées intégrées

Les métadonnées qui changent rapidement représentent des données contextuelles qui évoluent rapidement. Les compteurs et les ID qui sont incrémentés automatiquement (par exemple, les numéros de série ou les ID de transaction) sont des exemples typiques de métadonnées qui changent rapidement.

MDE vous permet de structurer, d'harmoniser et de transformer des métadonnées en constante évolution à l'aide de Whistle, et de les intégrer directement dans l'enregistrement en remplissant un champ appelé embeddedMetadata dans l'enregistrement proto du parseur.

Tous les récepteurs de données MDE compatibles rendent les métadonnées intégrées disponibles. Par exemple, si vous renseignez le champ embeddedMetadata dans l'enregistrement proto du parseur, une ligne semblable à celle-ci sera générée pour l'enregistrement résultant dans 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"
}

Suppression automatique des métadonnées

Pour les métadonnées d'enregistrement et de tag, MDE suit les modifications apportées à chaque clé naturelle en comparant chaque nouvelle instance à l'ancienne. Lorsqu'un attribut d'instance est modifié, MDE crée une version et la marque comme dernière instance effective. Par conception, les métadonnées de balise et d'enregistrement sont censées être de l'ordre de milliers et inférieures à cent mille. Ces restrictions permettent à MDE d'indexer les instances de métadonnées telles qu'elles proviennent du périphérique Edge ou de l'API, sans affecter le débit de traitement.

Parfois, en raison d'erreurs de configuration, le parseur injecte un champ à cardinalité élevée (comme un code temporel) dans l'instance de métadonnées, ce qui entraîne une prolifération rapide des versions pour chaque clé naturelle. Au-delà d'un certain seuil, cela a un impact négatif sur les performances de l'ingestion. Dans certains cas, cela peut entraîner l'arrêt complet du traitement jusqu'à ce que l'administrateur de la solution mette à l'échelle les services d'infrastructure cloud sous-jacents.

À partir de la version 1.4.0, MDE applique un nombre maximal d'instances par clé naturelle pour garantir des performances cohérentes. Lorsque le nombre de clés naturelles approche de ce seuil (200 par défaut), MDE envoie un avertissement à la nouvelle API de notifications pour informer l'utilisateur des clés naturelles qui comportent un nombre élevé de versions d'instance de métadonnées. Lorsque la taille de l'instance de clés naturelles dépasse le seuil, MDE supprime automatiquement les anciennes instances du magasin interne. Il enverra également une autre notification à l'API Notifications pour informer l'utilisateur des clés naturelles qui ont été supprimées.

L'avertissement et les activités de suppression sont également signalés dans le journal, qui peut être utilisé pour créer une règle d'alerte dans Cloud Monitoring du projet.

Restrictions de dénomination pour les buckets de métadonnées

Un nom de bucket de métadonnées peut contenir les éléments suivants :

Lettres (majuscules et minuscules), chiffres et caractères spéciaux - et _.
Il peut comporter jusqu'à 255 caractères.

Vous pouvez utiliser l'expression régulière suivante pour la validation : ^[a-z][a-z0-9\\-_]{1,255}$.

Si vous essayez de créer une entité qui ne respecte pas les restrictions d'attribution de noms, vous recevrez un message 400 error.