Mappage d'événements de type tableau pour l'insertion de lac de données via l'API REST

Le type JSON du tableau d'interface logique IoT n'est pas pris en charge pour les événements entrants destinés à être utilisés par. Pour utiliser les données d'un tableau avec l'outil, vous devez mapper soit le tableau entier, soit les éléments individuels du tableau aux propriétés de l'interface logique en les convertissant en chaînes de caractères.

Vue d'ensemble

L'outil est utilisé pour créer des interfaces physiques et logiques pour l'ingestion de données dans le lac de données. Vous pouvez recourir soit au cache des derniers événements, soit au téléchargement de fichiers, pour spécifier les fichiers à inclure dans l'interface physique, puis procéder à un mappage simple entre les interfaces physiques et logiques.

Toutefois, le mappage de l'outil ne prend pas actuellement en charge le type JSON "array". Pour mapper les propriétés des types de tableaux, vous devez utiliser l'API REST de l'outil.

  • Dans cet exemple, nous utilisons le type de terminal SimDevType avec un terminal enregistré: simdev01
  • Les événements SimDevType incluent des propriétés de type tableau JSON.
    La figure suivante montre le contenu de l'événement nommé "exemple" qui comprend trois propriétés de type JSON de type tableau : arr01, arr02, et arr03. Ceux-ci ne peuvent pas être consommés directement par les.
    {
"EventName" : "anExampleEvent",
"EventDescription" : "defines the format of an example IoT event with arrays",
"EventID": "example",
"Payload" : {"d": {
"ver" : "1.3",
"powerCons" : 12.64,
"currTemp" : 51,
"arr01" : [ 1.1, 2.22, 3.333, 4.4444, 5.55, 6.666],
"arr02" : [ "Abc", "Def", "Ghi" ],
"arr03":[ 123, 456, 789, 1010 ]
 } } }
  • L'objectif de cette tâche consiste à mapper les propriétés de tableau dans trois propriétés de type chaîne correspondantes : compobj1, compobj2 et compobj3.
    Chacune de ces propriétés est une chaîne qui concatène le premier, le deuxième et le troisième élément de tableau en conséquence. Exemple :
    "compobj1": "$string({'x': $event.d.arr01[0], 'y': $event.d.arr02[0], 'z':
          $event.d.arr03[0]})",

    Dans l'exemple d'événement : compobj1 = 'x':1.1, 'y':"Abc", 'z':123

Mise à jour du mappage de l'interface logique à l'aide de l'API REST

Les étapes de mappage de tableau suivantes doivent être effectuées une fois que vous avez créé les interfaces avec l'interface utilisateur, mais avant de les activer.

Pour effectuer le mappage de type d'événement tableau, procédez comme suit :

  • Etape 1: Obtenez l'ID de schéma et l'ID d'interface logique.
  • Etape 2: Obtenez le contenu du schéma d'interface logique provisoire.
  • Etape 3: Mettez à jour le schéma d'interface logique provisoire.

    Ajouter, supprimer ou modifier des propriétés de schéma, puis utiliser le fichier de schéma modifié pour mettre à jour le schéma de l'interface logique

  • Etape 4: Obtenez les brouillons de mappage associés à un type de terminal spécifié.
  • Etape 5: Mettez à jour les mappages de brouillon.

    Ajouter, supprimer ou modifier les mappages de l'interface physique à l'interface logique. Utiliser le fichier des mappages modifié pour mettre à jour les mappages du type de terminal.

  • Etape 6: Validez la configuration de l'interface logique brouillon.
  • Etape 7: Activez la configuration.

Tous les appels d'API sont fournis comme exemples cURL.

Pour plus d'informations sur les appels d'API REST de gestion d'état IoT qui sont utilisés dans cet exemple, voir les API REST HTTP dans votre documentation d'API locale. Pour plus d'informations, voir API.

Etape 1 : Se procurer l'ID schéma et l'ID d'interface logique

  1. Utilisez l'appel GET /draft/device/types/{deviceType}/logicalinterfaces pour obtenir les interfaces logiques provisoires associées au type de terminal SimDevType .
    Exemple :
    curl -X GET
          "https://<orgId>.iot.masdomain.com/api/v0002/draft/device/types/SimDevType/logicalinterfaces"
          -H "accept: application/json" -H "authorization: Basic
         <Base64-encoded-credentials>"

    Où <orgId> est l'identifiant unique à six caractères de votre compte et <Base64-encoded-credentials> correspond aux identifiants API encodés en base 64 pour ce compte. Pour plus d'informations sur les données d'identification de l'API, voir API.

  2. Identifiez l'interface logique appropriée pour le type de terminal.

    Le noeud final logicalinterfaces renvoie un tableau qui inclut des informations pour toutes les interfaces logiques d'un type de terminal unique.

    Les éléments id et schemaId de l'exemple suivant sont utilisés tout au long de cette tâche.

    Exemple de sortie de l'appel API :
    
[
{
 "name": "SimDevType_LI",
 "description": "",
 "id": "{logicalInterfaceId}",
 "schemaId": "{schemaId}",
 "refs": {
   "schema": "/api/v0002/draft/schemas/{schemaId}"
 },
 "version": "draft",
 "created": "2018-06-08T12:29:50Z",
 "createdBy": "user@address.com",
 "updated": "2018-06-08T12:29:50Z",
 "updatedBy": "user@address.com"
}
]

Etape 2 : Accéder au contenu du schéma d'interface logique provisoire

  1. Utilisez l'appel API GET /draft/schemas/{schemaId}/content pour extraire le contenu du fichier de définition de schéma brouillon avec l'ID spécifié.
    Exemple :
    curl -X GET
          "https://<orgId>.iot.masdomain.com/api/v0002/draft/schemas/{schemaId}/content" -H
          "accept: application/json" -H "authorization: Basic
          <Base64-encoded-credentials>"
  2. Sauvegardez le contenu du schéma d'interface logique provisoire dans un fichier. Les propriétés de type tableau sont par défaut incluses en tant que propriétés ...Item_01 et ...ItemLast .
    Exemple de fichier de schéma d'interface physique :
    {
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"title": "schema-title-52395315",
"description": "",
"properties": {
 "version": {
   "type": "string"
 },
 "kWh": {
   "type": "number",
   "default": 1
 },
 "temperature": {
   "type": "number",
   "default": 0
 },
 "arr01_Item01": {
   "type": "number"
 },
 "arr01_ItemLast": {
   "type": "number"
 },
 "arr02_Item01": {
   "type": "string"
 },
 "arr02_ItemLast": {
   "type": "string"
 },
 "arr03_Item01": {
   "type": "number"
 },
 "arr03_ItemLast": {
   "type": "number"
 }
}
}

Etape 3 : Mettre à jour le contenu du schéma logique

Ajoutez les propriétés de schéma de l'interface logique combobj qui seront les cibles de votre mappage de tableau, puis utilisez le fichier de contenu du schéma modifié pour mettre à jour le schéma d'interface logique.

  1. Mettez à jour les entrées de tableau de manière à correspondre aux propriétés de tableau.
    Ajoutez les propriétés compobj auxquelles vous allez mapper les composants de tableau individuels:
    
"compobj1": {
   "type": "string"
 },
 "compobj2": {
   "type": "string"
 },
 "compobj3": {
   "type": "string"
 }
  2. Utilisez l'appel PUT /draft/schemas/{schemaId}/content pour mettre à jour le contenu d'un fichier de définition de schéma brouillon.

    Exemple :

    curl -X PUT
            "https://<orgId>.iot.masdomain.com/api/v0002/draft/schemas/{schemaId}/content" -H
            "accept: application/json" -H "authorization: Basic <Base64-encoded-credentials>"
            -H "content-type: multipart/form-data" -d {"schemaFile":{}}
  3. Vérifiez que le code retour est 204 afin de vous assurer que la mise à jour a réussi.
    Exemple de contenu de schéma après la mise à jour du contenu. Les éléments modifiés sont mis en évidence.
    {
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"title": "schema-title-52395315",
"description": "",
"properties": {
 "version": {
   "type": "string"
 },
 "kWh": {
   "type": "number",
   "default": 1
 },
 "temperature": {
   "type": "number",
   "default": 0
 },
 "arr01_Item01": {
   "type": "number",
   "default": 1, // <- Modified
   "minimum": 0.5 // <- Modified
 },
 "arr01_ItemLast": {
   "type": "number"
 },
 "arr02_Item01": {
   "type": "string"
 },
 "arr02_ItemLast": {
   "type": "string"
 },
 "arr03_Item01": {
   "type": "number",
   "default": 0, // <- Modified
   "minimum": -50 // <- Modified
 },
 "arr03_ItemLast": {
   "type": "number"
 },
 "compobj1": { // <- Modified
   "type": "string" // <- Modified
 },
 "compobj2": { // <- Modified
   "type": "string" // <- Modified
 },
 "compobj3": { // <- Modified
   "type": "string" // <- Modified
 }
}
}

Etape 4: Obtenir les brouillons de mappage associés à un type de terminal spécifié

  1. Utilisez l'appel GET /draft/device/types/{deviceType}/mappingsGet aux brouillons de mappage associés à un type de terminal.
    Exemple :
    curl -X GET
          "https://<orgId>.iot.masdomain.com/api/v0002/draft/device/types/SimDevType/mappings" -H
          "accept: application/json" -H "authorization: Basic
          <Base64-encoded-credentials>"
  2. Identifiez l'interface logique appropriée pour le type de terminal.

    Le point de terminaison mappingsGet renvoie un tableau contenant des informations pour tous les mappages d'un seul type de dispositif.

    Exemple de sortie de l'appel API :
    [
{
 "logicalInterfaceId": "{logicalInterfaceId}",
 "notificationStrategy": "on-state-change",
 "propertyMappings": {
   "example": {
 "version": "$event.d.ver",
 "kWh": "$event.d.powerCons",
 "temperature": "$event.d.currTemp",
 "arr02_ItemLast": "$event.d.arr02[-1]",
 "arr03_ItemLast": "$event.d.arr03[-1]",
 "arr01_Item01": "$event.d.arr01[0]",
 "arr01_ItemLast": "$event.d.arr01[-1]",
 "arr02_Item01": "$event.d.arr02[0]",
 "arr03_Item01": "$event.d.arr03[0]"
 } }, "version": "draft", "created": "2018-06-08T12:29:50Z", "createdBy": "user@address.com", "updated": "2018-06-08T15:39:20Z", "updatedBy": "a-ju1wwa-ploazvcz5l"
          } ]
  3. Sauvegardez les mappages provisoires dans un fichier.

Etape 5: Modification des mappages

Ajoutez les mappages compobj aux mappages d'interface logique, puis utilisez le fichier de mappages modifié pour mettre à jour les mappages de types de dispositif.

  1. Ajoutez les entrées de tableau afin qu'elles correspondent aux propriétés de tableau.
    Par exemple, ajoutez :
    "compobj1": "$string({'x': $event.d.arr01[0], 'y': $event.d.arr02[0], 'z': $event.d.arr03[0]})",
"compobj2": "$string({'x': $event.d.arr01[1], 'y': $event.d.arr02[1], 'z': $event.d.arr03[1]})",
"compobj3": "$string({'x': $event.d.arr01[2], 'y': $event.d.arr02[2], 'z': $event.d.arr03[2]})"

    Chacun de ces mappages concatène le premier, le deuxième et le troisième élément de tableau en conséquence.

    Vous pouvez également convertir un tableau JSON entier en chaîne. Exemple : "entire_arr01" : "$string($event.d.arr01)"

  2. Utilisez l'appel API REST PUT /draft/device/types/SimDevType/mappings/{logicalInterfaceId} pour mettre à jour le mappage.

    Exemple :

    curl -X PUT
      "https://<orgId>.iot.masdomain.com/api/v0002/draft/device/types/SimDevType/mappings/{logicalInterfaceId}"
      -H "accept: application/json" -H "authorization: Basic <Base64-encoded-credentials>" -H
      "content-type: application/json" -d "{ \"logicalInterfaceId\":
      \"{logicalInterfaceId}\", \"notificationStrategy\": \"on-state-change\",
      \"propertyMappings\": { \"example\": { \"version\": \"$event.d.ver\", \"kWh\":
      \"$event.d.powerCons\", \"arr02_ItemLast\": \"$event.d.arr02[-1]\", \"temperature\":
      \"$event.d.currTemp\", \"arr03_ItemLast\": \"$event.d.arr03[-1]\", \"arr01_Item01\":
      \"$event.d.arr01[0]\", \"arr01_ItemLast\": \"$event.d.arr01[-1]\", \"arr02_Item01\":
      \"$event.d.arr02[0]\", \"arr03_Item01\": \"$event.d.arr03[0]\", \"compobj1\":
      \"$string({'x': $event.d.arr01[0], 'y': $event.d.arr02[0], 'z': $event.d.arr03[0]})\",
      \"compobj2\": \"$string({'x': $event.d.arr01[1], 'y': $event.d.arr02[1], 'z':
      $event.d.arr03[1]})\", \"compobj3\": \"$string({'x': $event.d.arr01[2], 'y':
      $event.d.arr02[2], 'z': $event.d.arr03[2]})\" } }, \"version\": \"draft\", \"created\":
      \"2018-06-08T12:29:50Z\", \"createdBy\": \"user@address.com\", \"updated\":
      \"2018-06-08T15:39:20Z\", \"updatedBy\": \"a-ju1wwa-ploazvcz5l\" }"
    Exemple de retour d'appel d'API. Les éléments modifiés sont mis en évidence:
    {
"logicalInterfaceId": "{logicalInterfaceId}",
"notificationStrategy": "on-state-change",
"propertyMappings": {
 "example": {
   "version": "$event.d.ver",
   "kWh":      "$event.d.powerCons",
   "arr02_ItemLast":  "$event.d.arr02[-1]",
   "temperature":      "$event.d.currTemp",
   "arr03_ItemLast": "$event.d.arr03[-1]",
   "arr01_Item01":   "$event.d.arr01[0]",
   "arr01_ItemLast": "$event.d.arr01[-1]",
   "arr02_Item01":   "$event.d.arr02[0]",
   "arr03_Item01":   "$event.d.arr03[0]",
   "compobj1": "$string({'x': $event.d.arr01[0], 'y':  $event.d.arr02[0], 'z': $event.d.arr03[0]})", // <- Modified
   "compobj2": "$string({'x': $event.d.arr01[1], 'y': $event.d.arr02[1], 'z': $event.d.arr03[1]})", // <- Modified
   "compobj3": "$string({'x': $event.d.arr01[2], 'y': $event.d.arr02[2], 'z': $event.d.arr03[2]})" // <- Modified
 }
},
"version": "draft",
"created": "2018-06-08T12:29:50Z",
"createdBy": "user@address.com",
"updated": "2018-06-08T15:39:20Z",
"updatedBy": "a-ju1wwa-ploazvcz5l"
}

Etape 6 : Valider la configuration de l'interface logique provisoire

Utilisez l'appel API PATCH /draft/logicalinterfaces/{logicalInterfaceId} avec l'opération validate-configuration pour valider l'interface logique brouillon.

Exemple :

curl -X PATCH
        "https://{orgId}.iot.masdomain.com/api/v0002/draft/logicalinterfaces/{logicalInterfaceId}"
        -H "accept: application/json" -H "content-type: application/json" -d "{
        \"operation\": \"validate-configuration\"}"
Exemple de retour d'appel d'API
{
  "message": "CUDIM0302I: State update configuration for Logical Interface '{logicalInterfaceName}' is valid.",
  "details": {
    "id": "CUDIM0302I",
    "properties": [
      "Logical Interface",
      "{logicalInterfaceName}"
    ]
  },
  "failures": []
}

Etape 7: Activer la configuration

Utilisez l'appel d'API PATCH /draft/logicalinterfaces/{logicalInterfaceId} avec l'opération activate-configuration pour activer l'interface logique brouillon.

Exemple :
curl -X PATCH
        "https://{orgId}.iot.masdomain.com/api/v0002/draft/logicalinterfaces/{logicalInterfaceId}"
        -H "accept: application/json" -H "content-type: application/json" -d "{
        \"operation\": \"activate-configuration\"}"
Exemple de sortie de l'appel API :

{
    "message": "CUDIM0300I: State update configuration for Logical Interface '{logicalInterfaceName}' has been successfully submitted for activation.",
    "details": {
        "id": "CUDIM0300I",
        "properties": [
            "Logical Interface",
            "{logicalInterfaceName}"
        ]
    },
    "failures": []
}

Vous pouvez également activer l'interface logique à partir de l'outil.

  1. Dans l'outil, allez dans Dispositifs et sélectionnez l'onglet Type de dispositif.
  2. Sélectionnez votre type de dispositif, puis l'onglet Interfaces.
  3. Cliquez sur le bouton Activer pour activer l'interface logique brouillon.

Une fois le schéma d'interface logique activé, tous les nouveaux éléments de tableau provenant de l'événement IoT reçu sont combinés en propriétés d'interface logique compobj1, compobj2 et compobj3 et convertis en chaînes.

Exemple de schéma d'interface physique provisoire

Voici l'exemple de schéma d'événement pour SimDevType_PI:

curl -X GET
        "https://<orgId>.iot.masdomain.com/api/v0002/schemas/5b1a63065908010033644197/content" -H
        "accept: application/json" -H "authorization: Basic
        <Base64-encoded-credentials>"
Sortie :
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "title": "example",            
  "description": "",
  "properties": {
    "d": {
      "type": "object",
      "properties": {
        "ver": {
          "type": "string",
          "default": ""
        },
        "powerCons": {
          "type": "number",
          "format": "float",
          "default": 0
        },
        "currTemp": {
          "type": "number",
          "format": "float",
          "default": 0
        },
        "arr01": {
          "default": [],
          "type": "array",
          "items": {
            "type": "number"
          }
        },
        "arr02": {
          "default": [],
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "arr03": {
          "default": [],
          "type": "array",
          "items": {
            "type": "number"
          }
        }
      }
    }
  }
}