Guía de referencia de MQTT

MQTT se utiliza comúnmente como medio para intercambiar datos de transmisión. Vantiq incluye soporte directo para leer flujos de datos MQTT. La esencia de la integración es la siguiente:

• Un administrador define una fuente MQTT identificando el punto final MQTT, las credenciales asociadas con el punto final y los temas a los que suscribirse. Esto se logra a través de la solicitud updateStream que se detalla a continuación o en el IDE de Vantiq mediante el uso de la Añadir botón para seleccionar Fuente….
• Una vez que se ha definido la fuente MQTT, el servidor construye un hilo separado para aceptar mensajes entrantes de la fuente MQTT.
• Cuando llega un mensaje al punto final de origen, se genera un evento que desencadenará la ejecución de cualquier regla suscrita. El evento también se puede entregar a cualquier cliente con suscripciones transitorias en la identificación del evento.
• Se recomiendan reglas de procesamiento de origen para almacenar cualquier estado persistente en el modelo de automatización de Vantiq. Esto permite que la regla en sí sea sin estado, lo que facilita la compatibilidad con varios enfoques de equilibrio de carga, como la ejecución de la regla en un clúster o la partición del trabajo entre varios servidores Vantiq.

Representación de origen MQTT

A fuente El recurso define la integración con una secuencia MQTT específica y contiene las siguientes propiedades:

• nombre  el nombre dado a la transmisión por el usuario
• tipo debe ser la cuerda MQTT indicando que esta es una fuente MQTT
• config un objeto JSON que contiene parámetros de configuración MQTT adicionales:
  • URI del servidor el punto final del servidor que aloja la transmisión. Opcionalmente, una lista de URI.
  • temas la lista de temas a los que está suscrito la transmisión. Se pueden definir múltiples transmisiones en un único URI de servidor que se suscriben a temas separados o temas superpuestos. Vantiq no impone restricciones a las suscripciones.
  • nombre de usuario credenciales para acceder al servidor MQTT
  • la contraseña credenciales para acceder al servidor MQTT
  • tipo de contenido el tipo de contenido MIME de los mensajes MQTT
  • mantener vivointervalo el intervalo de mantenimiento de la conexión TCP
  • el tiempo de conexión expiro el intervalo de tiempo de espera para la conexión
  • maxInflight el número máximo de mensajes que se enviarán sin recibir un acuse de recibo del servidor (predeterminado 10)
  • sesión limpia Es verdadero si el estado no se conserva tras errores de conexión; falso en caso contrario
  • automáticoReconectar Es verdadero si el cliente debe intentar volver a conectarse si falla la conexión.
  • qos Nivel de calidad de servicio para los temas a los que se suscribe la transmisión. QoS se define como una cadena con uno de los siguientes valores: AT_MOST_ONCE, AT_LEAST_ONCE or EXACTLY_ONCE. Si no se especifica, el valor predeterminado es AT_LEAST_ONCE. Tenga en cuenta que la QoS para PUBLICAR se debe especificar en la línea de comandos de publicación de VAIL y el valor predeterminado es AT_MOST_ONCE.

Si bien las propiedades de configuración enumeradas anteriormente son las más utilizadas, el objeto JSON de configuración se asigna a la Opciones del cliente Vert.x MQTT configuración. Por lo tanto, cualquier propiedad compatible con MqttClientOptions se puede agregar al objeto de configuración, incluso si no se lista explícitamente aquí. Un ejemplo sería especificar un tamaño máximo de mensaje usando el maxMessageSize propiedad o configurar el cliente utilizar SSL.

Crear una fuente MQTT

El siguiente ejemplo ilustra cómo crear una fuente MQTT utilizando la API REST. Las fuentes MQTT también se pueden definir en el IDE de Vantiq mediante el uso de la Añadir botón para seleccionar Fuente….

POST https://dev.vantiq.com/api/v1/resources/sources
{ 
    "name": "myMqttSource",
    "type": "MQTT",
    "config": {
        "serverURIs": ["tcp://me.vantiq.com:1883"],
        "topics": ["com/accessg2/stream/mqtt/example"],
        "keepAliveInterval": 30,
        "connectionTimeout": 30,
        "username": "user",
        "password": "password",
        "cleanSession": true
    }
}

Alternativamente, para usar una contraseña secreta llamada "MySecret", cambie la propiedad de la contraseña a una referencia y especifique 'secret' como tipo de contraseña de esta manera:

POST https://dev.vantiq.com/api/v1/resources/sources
{ 
    "name": "myMqttSource",
    "type": "MQTT",
    "config": {
        "serverURIs": ["tcps://me.vantiq.com:1883"],
        "topics": ["com/accessg2/stream/mqtt/example"],
        "keepAliveInterval": 30,
        "connectionTimeout": 30,
        "username": "user",
        "password": "/system.secrets/MySecret",
        "passwordType": "secret",
        "cleanSession": true
    }
}

Si el servidor MQTT está configurado para requerir una conexión segura, asegúrese de que los URI del servidor configurados tengan como prefijo un protocolo seguro, como tcps en lugar de tcp o mqtts en lugar de mqtt.

Si la fuente está destinada a publicar únicamente mensajes, no especifique el topics propiedad.

Eliminar una fuente MQTT

La fuente MQTT de ejemplo denominada myMqttFuente se puede eliminar utilizando la API REST emitiendo la siguiente solicitud:

DELETE https://dev.vantiq.com/api/v1/resources/sources/myMqttSource

Publicar notificaciones a través de MQTT

Las notificaciones son producidas por el sistema de reglas cuando PUBLICAR se llama por regla general acción. El PUBLICAR La solicitud de fuentes MQTT toma tres parámetros: el objeto del mensaje a enviar y la fuente y el tema al que se envía la publicación.

Por ejemplo,

PUBLISH { message: { data: "somedata" }} TO SOURCE someMQTTSource 
  USING { topic: "the/mqtt/topic" }

QoS

La QoS predeterminada para un mensaje publicado es AT_MOST_ONCE. Para especificar un valor de QoS específico, utilice el qos propiedad.

Por ejemplo,

PUBLISH { message: { data: "somedata" }} TO SOURCE someMQTTSource 
  USING { topic: "the/mqtt/topic", qos: "AT_LEAST_ONCE" }

La QoS predeterminada para los temas a los que se suscribe la transmisión es AT_LEAST_ONCE. Esta configuración predeterminada se puede cambiar en la fuente configuración especificando el qos parámetro de configuración. Tenga en cuenta que el valor de QoS efectivo del suscriptor es el valor de QoS más bajo establecido entre el editor y el suscriptor. Por ejemplo, si la QoS del editor es AT_MOST_ONCE, la QoS efectiva del suscriptor también es AT_MOST_ONCE aunque el suscriptor pueda estar configurado con AT_LEAST_ONCE.

Para habilitar mensajes confiables desde el broker MQTT a través de reinicios de origen, los parámetros de configuración clientId y cleanSession debe especificarse. clientId debe establecerse en un valor único fijo y cleanSession debe establecerse en falso. El clientId El valor permite al intermediario identificar la sesión del cliente para que se pueda entregar cualquier mensaje que el intermediario haya retenido mientras la fuente estaba fuera de línea. Si clientId no se proporciona en la configuración de origen o si cleanSession se establece en verdadero, la sesión entre el cliente y el corredor dura el tiempo de la conexión de red.

Configuración SSL

Una fuente MQTT se puede configurar para comunicación SSL unidireccional o bidireccional especificando datos adicionales. Opciones del cliente Vert.x MQTT propiedades de configuración expresadas como su representación JSON. A continuación se muestran algunos ejemplos de uso. Tenga en cuenta que las propiedades de configuración SSL para AMQP, MQTT y fuentes remotas son idénticas en su uso. Puede consultar la documentación de configuración de SSL de esas fuentes para obtener ejemplos adicionales.

SSL unidireccional

Los ejemplos de esta sección suponen que el corredor MQTT está configurado para comunicarse a través de SSL con un certificado firmado por una CA. El certificado de CA está disponible en un almacén de confianza llamado sourceTrustStore.jks. Se configura una fuente MQTT para acceder al intermediario a través de SSL y el usuario que configura la fuente tiene acceso al almacén de confianza.

Si se puede acceder al almacén de confianza en un sistema de archivos legible por el servidor Vantiq (por ejemplo, una instalación perimetral), el almacén de confianza podría especificarse como:

{
    "serverURIs": ["tcps://me.vantiq.com:1883"],
    "topics": ["com/accessg2/stream/mqtt/example"],
    "username": "user",
    "password": "password",
    "trustStoreOptions": {
        "path": "/path/to/sourceTrustStore.jks",
        "password": "my_store_password"
    }
}

Si el servidor en el que se define la fuente remota no puede acceder al almacén de confianza, el contenido del almacén de confianza se puede especificar como un valor codificado en base64,

# Copy/paste the following output to the value property below
$ cat /path/to/sourceTrustStore.jks | base64

{
    "serverURIs": ["tcps://me.vantiq.com:1883"],
    "topics": ["com/accessg2/stream/mqtt/example"],
    "username": "user",
    "password": "password",
    "trustStoreOptions": {
        "value": "/u3+7QAAAAIAAAABAAAAAgAGY2F........SzpeAUc7WXDK1HOg==",
        "password": "my_store_password"
    }
}

El valor también se puede almacenar como secreto y referenciado en la configuración,

# Copy/paste the following output to a Secret named SourceTrustStore
$ cat /path/to/sourceTrustStore.jks | base64
# Also define a Secret named SourceTrustStorePassword containing the trust store password

{
    "serverURIs": ["tcps://me.vantiq.com:1883"],
    "topics": ["com/accessg2/stream/mqtt/example"],
    "username": "user",
    "password": "password",
    "trustStoreOptions": {
        "value": "@secrets(SourceTrustStore)",
        "password": "@secrets(SourceTrustStorePassword)"
    }
}

Suponiendo que se deben confiar en dos certificados de CA y a los que se puede acceder desde archivos en formato PEM, los archivos denominados ca-cert-1 y ca-cert-2,

{
    "serverURIs": ["tcps://me.vantiq.com:1883"],
    "topics": ["com/accessg2/stream/mqtt/example"],
    "username": "user",
    "password": "password",
    "pemTrustOptions": {
        "certPaths": ["/path/to/ca-cert-1", "/path/to/ca-cert-2"]
    }
}

O con Secretos,

# Copy/paste the following output to a Secret named CertAuthority1
$ cat /path/to/ca-cert-1 | base64
# Copy/paste the following output to a Secret named CertAuthority2
$ cat /path/to/ca-cert-2 | base64

{
    "serverURIs": ["tcps://me.vantiq.com:1883"],
    "topics": ["com/accessg2/stream/mqtt/example"],
    "username": "user",
    "password": "password",
    "pemTrustOptions": {
        "certValues": ["@secrets(CertAuthority1)", "@secrets(CertAuthority2)"]
    }
}

Autenticación de cliente SSL

Además de especificar un almacén de confianza, la configuración de una fuente MQTT también puede especificar un certificado de cliente. Esto es necesario si el bróker está configurado para autenticación mutua y requiere que el cliente se autentique con un certificado.

Los ejemplos siguientes suponen un almacén de claves denominado sourceKeyStore.jks que contiene el certificado de cliente firmado por la CA.

Si se puede acceder al almacén de claves en un sistema de archivos legible por el servidor Vantiq,

{
    "serverURIs": ["tcps://me.vantiq.com:1883"],
    "topics": ["com/accessg2/stream/mqtt/example"],
    "trustStoreOptions": {
        "path": "/path/to/sourceTrustStore.jks",
        "password": "my_store_password"
    },
    "keyStoreOptions": {
        "path": "/path/to/sourceKeyStore.jks",
        "password": "my_keystore_password"
    }
}

De manera similar a los ejemplos del almacén de confianza, cualquier almacén de claves especificado mediante la sintaxis de ruta se puede especificar como un valor codificado en base64.

Por ejemplo, usando definiciones secretas,

# Copy/paste the following output to a Secret named SourceTrustStore
$ cat /path/to/sourceTrustStore.jks | base64
# Copy/paste the following output to a Secret named SourceKeyStore
$ cat /path/to/sourceKeyStore.jks | base64
# Also define the store passwords as Secrets (SourceTrustStorePassword and SourceKeyStorePassword)

{
    "serverURIs": ["tcps://me.vantiq.com:1883"],
    "topics": ["com/accessg2/stream/mqtt/example"],
    "trustStoreOptions": {
        "value": "@secrets(SourceTrustStore)",
        "password": "@secrets(SourceTrustStorePassword)"
    },
    "keyStoreOptions": {
        "value": "@secrets(SourceKeyStore)",
        "password": "@secrets(SourceKeyStorePassword)"
    }
}

Para obtener más detalles sobre cómo diseñar y realizar los esfuerzos de seguimiento y evaluación, refierase a Opciones del cliente Vert.x MQTT documento para obtener una lista completa de opciones de configuración. Nota: en ese documento, una referencia a Buffer significa que se puede especificar un valor codificado en base64 (por ejemplo, trustStoreOptions). Cualquier add El método se traduce en una matriz (por ejemplo, pemTrustOptions) y cualquier set El método se traduce en una configuración de propiedad única (por ejemplo, ruta o valor).