Correlación de sucesos de tipo de matriz para la inserción del lago de datos utilizando la API REST

El tipo JSON de matriz de interfaz lógica IoT no es compatible con los eventos entrantes para uso de. Para utilizar los datos de la matriz con la herramienta, debe asignar la matriz completa o los elementos individuales de la matriz a las propiedades lógicas de la interfaz convirtiéndolos en cadenas.

Visión general

La herramienta se utiliza para crear interfaces físicas y lógicas para la ingestión de datos en el lago de datos. Puede utilizar la memoria caché del último suceso o las cargas de archivos para definir los sucesos que se incluirán en la interfaz física y, a continuación, utilizar la correlación de tipos base simple entre las interfaces físicas y lógicas.

Sin embargo, la herramienta de mapeo no soporta actualmente el tipo array JSON. Para asignar propiedades de tipo array debe utilizar la API REST de la herramienta.

  • En este ejemplo, estamos utilizando el tipo de dispositivo SimDevType con un dispositivo registrado: simdev01
  • Los sucesos de SimDevType incluyen propiedades de tipo JSON de matriz.
    A continuación se muestra el contenido del evento denominado "ejemplo", que incluye tres propiedades de tipo array JSON: arr01, arr02, y arr03. No pueden ser consumidos directamente por.
    {
"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 ]
 } } }
  • El objetivo de esta tarea consiste en correlacionar las propiedades de matriz en tres propiedades de tipo de serie correspondientes: compobj1, compobj2 y compobj3.
    Cada una de estas propiedades es una serie que concatena los elementos de la primera, segunda y tercera matriz correspondientes. Ejemplo:
    "compobj1": "$string({'x': $event.d.arr01[0], 'y': $event.d.arr02[0], 'z':
          $event.d.arr03[0]})",

    Del suceso de ejemplo: compobj1 = 'x':1.1, 'y':"Abc", 'z':123

Actualización de la correlación de interfaz lógica utilizando la API REST

Los siguientes pasos de correlación de matrices deben realizarse después de haber creado las interfaces con la interfaz de usuario, pero antes de activarlas.

Para completar la correlación de tipos de sucesos de matriz, complete los pasos siguientes:

  • Paso 1: Obtenga el ID de esquema y el ID de interfaz lógica.
  • Paso 2: Obtenga el contenido del esquema de interfaz lógica de borrador.
  • Paso 3: Actualice el esquema de interfaz lógica borrador.

    Añada, suprima o modifique las propiedades del esquema y, a continuación, utilice el archivo de contenido de esquema modificado para actualizar el esquema de interfaz lógica.

  • Paso 4: Obtenga las correlaciones de borrador que están asociadas con un tipo de dispositivo especificado.
  • Paso 5: Actualice las correlaciones de borrador.

    Añada, suprima o modifique la interfaz física a las correlaciones de interfaz lógica. Utilice el archivo de correlaciones modificado para actualizar las correlaciones de tipo de dispositivo.

  • Paso 6: Valide la configuración de interfaz lógica de borrador.
  • Paso 7: Active la configuración.

Todas las llamadas de API se proporcionan como ejemplos de cURL.

Para obtener más información sobre las llamadas de API REST de gestión de estado IoT que se utilizan en este ejemplo, consulte las API REST HTTP en la documentación de la API local. Para obtener más información, consulte API.

Paso 1: obtener el ID de esquema y el ID de interfaz lógica

  1. Utilice la llamada GET /draft/device/types/{deviceType}/logicalinterfaces para obtener las interfaces lógicas de borrador asociadas con el tipo de dispositivo SimDevType .
    Ejemplo:
    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>"

    Donde <orgId> es el identificador único de seis caracteres de su cuenta y <Base64-encoded-credentials> son las credenciales API codificadas en base 64 para esa cuenta. Para obtener información sobre las credenciales de API, consulte API.

  2. Identifique la interfaz lógica correcta para el tipo de dispositivo.

    El punto final logicalinterfaces devuelve una matriz que incluye información para todas las interfaces lógicas para un único tipo de dispositivo.

    id y schemaId en el ejemplo siguiente se utilizan en toda esta tarea.

    Devolución de llamada de API de ejemplo:
    
[
{
 "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"
}
]

Paso 2: obtener el contenido del esquema de la interfaz lógica de borrador

  1. Utilice la llamada de API GET /draft/schemas/{schemaId}/content para recuperar el contenido del archivo de definición de esquema de borrador con el ID especificado.
    Ejemplo:
    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. Guarde el contenido del esquema de la interfaz lógica de prueba en un archivo. Las propiedades de tipo de matriz se incluyen de forma predeterminada como propiedades ...Item_01 y ...ItemLast .
    Archivo de esquema de interfaz física de ejemplo:
    {
"$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"
 }
}
}

Paso 3: actualizar los contenidos del esquema lógico

Añada las propiedades de esquema de interfaz lógica de combobj que serán los destinos de la correlación de matriz y luego utilice el archivo de contenido de esquema modificado para actualizar el esquema de interfaz lógica.

  1. Actualice las entradas de matriz para que coincidan con las propiedades de la matriz
    Añada las propiedades compobj con las que correlacionará los componentes de matriz individuales:
    
"compobj1": {
   "type": "string"
 },
 "compobj2": {
   "type": "string"
 },
 "compobj3": {
   "type": "string"
 }
  2. Utilice la llamada PUT /draft/schemas/{schemaId}/content para actualizar el contenido de un archivo de definición de esquema de borrador.

    Ejemplo:

    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. Verifique que el código de retorno es 204 para una actualización satisfactoria.
    Contenido de esquema de ejemplo después de la actualización de contenido. Los elementos modificados se resaltan.
    {
"$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
 }
}
}

Paso 4: Obtener las correlaciones de borrador que están asociadas con un tipo de dispositivo especificado

  1. Utilice la llamada GET /draft/device/types/{deviceType}/mappingsGet a las correlaciones de borrador asociadas con un tipo de dispositivo.
    Ejemplo:
    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. Identifique la interfaz lógica correcta para el tipo de dispositivo.

    El punto final de mappingsGet devuelve una matriz que incluye información para todas las correlaciones para un único tipo de dispositivo.

    Devolución de llamada de API de ejemplo:
    [
{
 "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. Guarde las correlaciones de prueba en un archivo.

Paso 5: Modificar las correlaciones

Añada las correlaciones de compobj a las correlaciones de interfaz lógica y luego utilice el archivo de correlaciones modificado para actualizar las correlaciones de tipos de dispositivo.

  1. Añada las entradas de matriz para que coincidan con las propiedades de la matriz
    Por ejemplo, añada:
    "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]})"

    Cada una de estas correlaciones concatena los elementos de matriz primera, segunda y tercera correspondientemente.

    También puede convertir una matriz JSON completa en una serie. Un ejemplo de ello, sería: "entire_arr01" : "$string($event.d.arr01)"

  2. Utilice la llamada de la API REST PUT /draft/device/types/SimDevType/mappings/{logicalInterfaceId} para actualizar la correlación.

    Ejemplo:

    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\" }"
    Devolución de llamada de API de ejemplo. Los elementos modificados se resaltan:
    {
"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"
}

Paso 6: validar la configuración de la interfaz lógica de prueba.

Utilice la llamada de API PATCH /draft/logicalinterfaces/{logicalInterfaceId} con la operación validate-configuration para validar el borrador de interfaz lógica.

Ejemplo:

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\"}"
Devolución de llamada de API de ejemplo
{
  "message": "CUDIM0302I: State update configuration for Logical Interface '{logicalInterfaceName}' is valid.",
  "details": {
    "id": "CUDIM0302I",
    "properties": [
      "Logical Interface",
      "{logicalInterfaceName}"
    ]
  },
  "failures": []
}

Paso 7: Activar la configuración

Utilice la llamada de API PATCH /draft/logicalinterfaces/{logicalInterfaceId} con la operación activate-configuration para activar el borrador de interfaz lógica.

Ejemplo:
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\"}"
Devolución de llamada de API de ejemplo:

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

También puedes activar la interfaz lógica desde la herramienta.

  1. En la herramienta, vaya a Dispositivos y seleccione la pestaña Tipo de dispositivo.
  2. Seleccione el tipo de dispositivo y, a continuación, seleccione la pestaña Interfaces.
  3. Pulse el botón Activar para activar la interfaz lógica de borrador.

Una vez activado el esquema de interfaz lógica, los nuevos elementos de matriz del suceso IoT recibido se combinan en propiedades de interfaz lógica compobj1, compobj2 y compobj3 y se convierten en series.

Ejemplo de esquema de interfaz física de prueba

Este es el esquema de evento de ejemplo para 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>"
Devuelve:
{
  "$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"
          }
        }
      }
    }
  }
}