Documentación de Oracle Cloud Infrastructure

Creación de un adaptador gemelo digital

Cree un adaptador de gemelos digitales para convertir las cargas útiles de datos sin procesar procedentes de un dispositivo físico o un sistema externo a datos de telemetría normalizados basados en el modelo de gemelos digitales.

Los datos se transfieren al adaptador de gemelos digitales como un objeto JSON que contiene los datos y la asignación.

Conceptos

Se necesita un adaptador gemelo digital al trabajar con datos estructurados.

Hay dos formas de utilizar un adaptador gemelo digital, dependiendo de si el dispositivo con el que está trabajando se puede programar para enviar datos:

  • Formato de adaptador predeterminado: si el dispositivo se puede programar para enviar datos en el formato con el que desea trabajar, cree un adaptador gemelo digital sin especificar inbound-envelope ni inbound-routes. La respuesta contendrá datos en el formato predeterminado del dispositivo. Si se especifica la asignación de sobre y contiene un valor timeObserved, receivedTime se utiliza como valor timeObserved. Para ver un ejemplo específico, consulte Escenario: Envío de datos estructurados en un formato predeterminado mediante HTTP.
  • Formato de adaptador personalizado: para los dispositivos que no se pueden programar para enviar datos, puede crear un adaptador gemelo digital personalizado definiendo un inbound-envelope y un envelope-mapping personalizados que transformen la carga útil y los metadatos para obtener la salida con la que desea trabajar. Para ver un ejemplo específico, consulte Escenario: Envío de datos estructurados en un formato personalizado mediante HTTP.
  • ID de autenticación: al crear un adaptador de gemelo digital si conecta un dispositivo, la instancia de gemelo digital asociada debe utilizar un parámetro de ID de autenticación, con un certificado o un secreto para autenticar el dispositivo.
  • Clave externa: después de crear un adaptador de gemelo digital, puede actualizar el adaptador de gemelo digital para cambiar la clave externa de un dispositivo. Cuando envíe datos, utilice la clave externa como nombre de usuario para el dispositivo.
  • Límite: el número máximo de rutas de entrada para un adaptador de gemelos digitales es 128.
Ejemplo de entrada de carga útil de dispositivo, asignación de JSON y resultado transformado

Puede probar la asignación de adaptadores en JQ Playground pegando la carga útil como entrada de consulta, agregando la asignación de JSON en la sección JSON y, a continuación, ver el resultado de salida.

Ejemplo de JSON de carga útil de dispositivo:

{ "time": "<timestamp>", "temp": 65, "hum": 55 }

Utilice una expresión JQ o la notación JsonPath para crear una salida de asignación de JSON de carga útil de adaptador.

En este ejemplo se utiliza una expresión JQ: 
{ "temperature": ".temp", "humidity": ".hum", "timeObserved": ".time" }
En este ejemplo se utiliza la notación JsonPath para crear una salida de asignación de JSON de carga útil de adaptador:
{ "temperature": "$.temp", "humidity": "$.hum", "timeObserved": "$.time" }
Resultado de salida transformado:
{ "temperature": 65, "humidity": 55, "timeObserved": "<timestamp>" }

Para obtener más ejemplos, consulte Referencia: Expresiones JQ para adaptadores gemelos digitales y Escenarios.

  • Si el dispositivo envía o recibe datos no estructurados, no es necesario especificar un adaptador gemelo digital.

    1. En la página de lista Dominios de IoT, seleccione el dominio de IoT con el que desea trabajar. Si necesita ayuda para encontrar la página de lista de dominios de IoT, consulte Listado de dominios de IoT.
    2. Seleccione el separador Adaptadores de gemelos digitales y seleccione Crear.
    3. Introduzca un nombre y, opcionalmente, una descripción. Evite introducir información confidencial.
    4. Para encontrar el modelo gemelo digital que desea asociar:
      • Seleccionar modelo: para buscar el modelo gemelo digital por nombre.
      • Seleccionar con URI de especificación de modelo: para buscar el modelo gemelo digital mediante el DTMI. Por ejemplo, dtmi:com:example:iot:demo;1
    5. Depende si el dispositivo con el que está trabajando se puede programar para enviar datos en formatos específicos:
      • Si el dispositivo se puede programar para enviar datos en un formato específico, no es necesario especificar el envolvente y las rutas del adaptador, el adaptador se genera a partir de la carga útil del dispositivo.
      • Si el dispositivo no se puede programar para enviar datos en el formato que desee, especifique un adaptador para traducir la carga útil entrante al formato de datos con el que desea trabajar. Active la opción para Especificar el sobre y las rutas de entrada:
        • Cargar archivo .json de sobre de entrada: cargue un archivo .json que contenga el sobre de entrada para este adaptador.
        • Pegar JSON de sobre de entrada: agregue el JSON de sobre de entrada a este adaptador.
    6. Especificación de rutas de entrada: agregue una lista de definiciones de rutas con condiciones y asignaciones de carga útil opcionales. Las vías se evalúan en orden.
      • Cargar archivo .json de rutas de entrada: cargue las rutas de entrada en un archivo .json.
      • Pegar JSON de rutas de entrada: agregue las rutas de entrada en formato JSON.
    7. Etiquetas: (opcional) agregue una o más etiquetas al adaptador de gemelos digitales. Si tiene permisos para crear un recurso, también los tiene para aplicar etiquetas de formato libre a ese recurso. Para aplicar una etiqueta definida, debe tener permisos para utilizar el espacio de nombres de la etiqueta. Para obtener más información sobre el etiquetado, consulte Etiquetas de recursos. Si no está seguro de si desea aplicar etiquetas, omita esta opción o pregunte a un administrador. Puede aplicar etiquetas más tarde.
    8. Seleccione Crear.

  • Utilice el comando oci iot digital-twin-adapter create y los parámetros necesarios para crear un adaptador gemelo digital.

    Para crear un adaptador de gemelos digitales para datos estructurados en un formato predeterminado: si el dispositivo se puede programar, cree un adaptador de gemelos digitales sin especificar inbound-envelope o envelope-mapping como resultado, los datos predeterminados que provienen del dispositivo se aceptan en la respuesta.

    Dos opciones para asociar el modelo gemelo digital:

    • Uso de DTMI:

      En el siguiente ejemplo, se utiliza el parámetro URI de DTMI para asociar el adaptador al modelo gemelo digital. Sustituya <digital-twin-model-spec-uri> por el URI de DTMI para el modelo gemelo digital asociado. 
      oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-spec-uri '<digital-twin-model-spec-uri>'
    • Uso del OCID del modelo de gemelo digital:
      Como alternativa, en el siguiente ejemplo se utiliza el parámetro --digital-twin-model-id con el <digital-twin-model-OCID> para el modelo de gemelo digital que desea asociar a un adaptador de gemelo digital:
      oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-id <digital-twin-model-OCID>

    Para crear un adaptador gemelo digital para datos estructurados en un formato personalizado:

    Utilice el comando oci iot digital-twin-adapter create y el parámetro --iot-domain-id necesario. Para crear un adaptador gemelo digital personalizado, defina un valor inbound-envelope o inbound-route específico para obtener la salida con la que desea trabajar, para definir la asignación de carga útil personalizada para el gemelo digital mediante un archivo <file://inbound-envelope.json> y un archivo <file://inbound-routes.json> mediante expresiones JQ.

    Sustituya <digital-twin-model-spec-uri> por el URI de DTMI para el modelo gemelo digital asociado y sustituya <iot-domain-OCID> por el OCID de dominio IoT que desea asociar a este adaptador gemelo digital:

    oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-spec-uri '<digital-twin-model-spec-uri>' --inbound-envelope <file://inbound-envelope.json> --inbound-routes <file://inbound-routes.json>

    Para obtener más información sobre la referencia a archivos, consulte Uso de un archivo de JSON para una entrada compleja.

    Para obtener una lista completa de los parámetros y valores de los comandos de la CLI, consulte Referencia de comandos de la CLI.

  • Ejecute la operación CreateDigitalTwinAdapter para crear un adaptador de gemelo digital en el dominio IoT especificado.