IoT Platform:Conexión de un cliente AMQP a IoT Platform

Límites

Las suscripciones del lado del servidor de IoT Platform admiten únicamente el protocolo AMQP 1.0.

Conexión a IoT Platform

1. Un cliente AMQP establece una conexión TCP con IoT Platform mediante un saludo de tres vías. Posteriormente, se ejecuta un saludo TLS para autenticar al cliente AMQP.

   Nota

   Para garantizar la seguridad, los clientes AMQP deben transmitir datos mediante cifrado TLS. No es posible transmitir datos a través de canales TCP sin cifrar.

2. El cliente solicita establecer una conexión.

   Se utiliza el mecanismo PLAIN SASL para autenticar la conexión. La autenticación se basa en un nombre de usuario y una contraseña. Una vez que IoT Platform valida correctamente las credenciales, se establece la conexión.

   Según el protocolo AMQP, el cliente debe agregar el campo idle-time-out al marco de apertura al establecer la conexión. Este campo especifica el periodo de tiempo de espera del latido. El rango permitido es de 30,000 ms a 300,000 ms. Si no se transmite ningún marco a través de la conexión tras expirar este periodo, IoT Platform cierra la conexión. El método para configurar el campo idle-time-out varía según el lenguaje de programación del SDK. Para más información, consulte el código de ejemplo de los SDK específicos por lenguaje.

3. El cliente envía una solicitud a IoT Platform para establecer un enlace receptor. Este enlace es un canal unidireccional que permite enviar datos desde IoT Platform hacia el cliente.

   El cliente debe establecer el enlace receptor dentro de los 15 segundos posteriores al establecimiento de la conexión AMQP. De lo contrario, IoT Platform cerrará la conexión AMQP.

   Una vez establecido el enlace receptor, el cliente queda conectado a IoT Platform.

   Nota

   • Solo se puede crear un enlace receptor por cada conexión. Los enlaces emisores no son compatibles. IoT Platform puede enviar mensajes al cliente, pero el cliente no puede enviar mensajes a IoT Platform.

   • El nombre de clase del enlace receptor varía según el lenguaje de programación del SDK. Por ejemplo, en algunos SDK el enlace receptor se denomina MessageConsumer.

Configuración de la conexión

Esta sección describe cómo especificar el endpoint y configurar los parámetros de autenticación al conectar un cliente AMQP a IoT Platform.

Endpoint y puerto

Especifique el endpoint de una instancia pública o de una instancia Enterprise Edition a la que desee conectar un cliente AMQP. Para más información sobre los endpoints compatibles, consulte Manage instance endpoints.

• Si utiliza un cliente Java, .NET, Python 2.7, Node.js o Go, el número de puerto es 5671.

• Si utiliza un cliente Python 3 o PHP, el número de puerto es 61614.

Parámetros de autenticación

Los parámetros de autenticación que debe configurar varían según la identidad de Alibaba Cloud que utilice para conectar un cliente AMQP a IoT Platform.

• Si utiliza la cuenta de Alibaba Cloud propietaria de la instancia de IoT Platform o un usuario de Resource Access Management (RAM) con los permisos necesarios otorgados directamente dentro de dicha cuenta, debe configurar los siguientes parámetros de autenticación:

  Nota

  Si utiliza un usuario RAM, debe adjuntarle una política de RAM que contenga la acción iot:sub. Esto permite que el usuario RAM utilice la función de suscripción del lado del servidor de IoT Platform. De lo contrario, la conexión fallará. Para más información, consulte RAM authorization for IoT Platform.

  Para mejorar la seguridad de los datos, se recomienda utilizar un rol de RAM para autorizar al usuario RAM a usar la función de suscripción del lado del servidor. Para más información, consulte la siguiente sección.

  userName = clientId|iotInstanceId=${iotInstanceId},authMode=aksign,signMethod=hmacsha1,consumerGroupId=${consumerGroupId},authId=${accessKey},timestamp=1573489088171|
  password = signMethod(stringToSign, accessSecret)

• Si utiliza un usuario RAM autorizado mediante un rol de RAM, debe configurar los siguientes parámetros de autenticación:

  Nota

  Además de los usuarios RAM de la cuenta de Alibaba Cloud propietaria de la instancia de IoT Platform, puede utilizar un rol de RAM para autorizar a un usuario RAM de otra cuenta de Alibaba Cloud a usar la función de suscripción del lado del servidor. Para más información sobre cómo usar un rol de RAM para autorizar a un usuario RAM a utilizar esta función en IoT Platform, consulte Authorize a RAM user of the current Alibaba Cloud account to use server-side subscription y Authorize a RAM user of another account to use server-side subscription.

  userName = clientId|iotInstanceId=${iotInstanceId},authMode=ststoken,securityToken=${SecurityToken},signMethod=hmacsha1,consumerGroupId=${consumerGroupId},authId=${accessKey},timestamp=1573489088171|
  password = signMethod(stringToSign, accessSecret)

  Tabla 1. Parámetros en userName

  Parámetro	Obligatorio	Descripción
  clientId	Sí	El ID del cliente. Debe especificar un ID personalizado. La longitud debe ser de 1 a 64 caracteres. Se recomienda utilizar un identificador único como ID del cliente, como el UUID, la dirección MAC o la dirección IP del servidor donde se ejecuta el cliente. Una vez que el cliente AMQP esté conectado e iniciado en IoT Platform, siga estos pasos para consultar los detalles del cliente: Inicie sesión en la consola de IoT Platform y haga clic en la tarjeta de la instancia que desea gestionar. En el panel de navegación izquierdo, elija Message Forwarding > Server-side Subscription. En la pestaña Consumer Groups, busque el grupo de consumidores que desea gestionar y haga clic en View en la columna Actions. El ID de cada cliente se muestra en la pestaña Consumer Group Status. Puede utilizar los ID de cliente para identificar fácilmente a cada cliente.
  iotInstanceId	No	El ID de la instancia de IoT Platform. Puede consultar el ID de la instancia en la pestaña Overview de la consola de IoT Platform. Si se muestra el ID de la instancia, debe establecer este parámetro con dicho ID. Si no se muestra la pestaña Overview o su instancia no tiene un ID, no es necesario especificar este parámetro.
  authMode	Sí	El modo de autenticación. Si utiliza la cuenta de Alibaba Cloud propietaria de la instancia de IoT Platform o un usuario RAM con los permisos necesarios otorgados directamente dentro de dicha cuenta, use el modo aksign. Si utiliza un usuario RAM autorizado mediante un rol de RAM, use el modo ststoken.
  securityToken	No	Importante Este parámetro es obligatorio solo si utiliza un usuario RAM autorizado mediante un rol de RAM para conectar el cliente AMQP a IoT Platform. El token de Security Token Service (STS) asignado al usuario RAM que asume el rol de RAM. Puede llamar a la operación AssumeRole para obtener el token STS. Para más información, consulte AssumeRole.
  signMethod	Sí	El algoritmo de firma. Valores válidos: hmacmd5, hmacsha1 y hmacsha256.
  consumerGroupId	Sí	El ID del grupo de consumidores de la instancia de IoT Platform. Para consultar el ID del grupo de consumidores, siga estos pasos: Inicie sesión en la consola de IoT Platform y haga clic en la tarjeta de la instancia que desea gestionar. En el panel de navegación izquierdo, elija Message Forwarding > Server-side Subscription. El ID del grupo de consumidores se muestra en la pestaña Consumer Groups.
  authId	Sí	La información de autenticación. Si utiliza la cuenta de Alibaba Cloud propietaria de la instancia de IoT Platform o un usuario RAM con los permisos necesarios otorgados directamente dentro de dicha cuenta: Establezca este parámetro con el AccessKey ID de la cuenta de Alibaba Cloud o el AccessKey ID del usuario RAM. Inicie sesión en la consola de IoT Platform, pase el puntero sobre su foto de perfil y luego haga clic en AccessKey Management. En la página que aparece, obtenga el AccessKey ID. Si utiliza un usuario RAM autorizado mediante un rol de RAM: Establezca este parámetro con el AccessKey ID del usuario RAM que asume el rol de RAM.
  timestamp	Sí	La hora actual. La marca de tiempo es un entero LONG. Unidad: milisegundo.

  Tabla 2. Parámetros en password

  Parámetro	Obligatorio	Descripción
  signMethod	Sí	El algoritmo de firma. Utilice el algoritmo de firma especificado en el parámetro userName para calcular el valor de la firma. Luego, convierta el valor en una cadena codificada en Base64.
  stringToSign	Sí	La cadena para firmar. Ordene los parámetros que deben firmarse alfabéticamente. Concatene la clave y el valor de cada parámetro mediante un signo igual (=). Concatene los parámetros mediante un ampersand (&). Si utiliza la cuenta de Alibaba Cloud propietaria de la instancia de IoT Platform o un usuario RAM con los permisos necesarios otorgados directamente dentro de dicha cuenta: Los parámetros que deben firmarse incluyen authId y timestamp. Establezca el valor con el formato stringToSign = authId=${accessKey}&timestamp=1573489088171. Si utiliza un usuario RAM autorizado mediante un rol de RAM: Los parámetros que deben firmarse incluyen securityToken, authId y timestamp. Establezca el valor con el formato stringToSign = authId=${accessKey}&securityToken=${SecurityToken}&timestamp=1573489088171.
  accessSecret	Sí	Si utiliza la cuenta de Alibaba Cloud propietaria de la instancia de IoT Platform o un usuario RAM con los permisos necesarios otorgados directamente dentro de dicha cuenta: Establezca este parámetro con el AccessKey secret de la cuenta de Alibaba Cloud o el AccessKey secret del usuario RAM. Inicie sesión en la consola de IoT Platform, pase el puntero sobre su foto de perfil y luego haga clic en AccessKey Management. En la página que aparece, obtenga el AccessKey secret. Si utiliza un usuario RAM autorizado mediante un rol de RAM: Establezca este parámetro con el AccessKey secret del usuario RAM que asume el rol de RAM.

Recepción de mensajes enviados por IoT Platform

Una vez establecido un enlace receptor entre un cliente AMQP e IoT Platform, la plataforma envía mensajes al cliente a través de dicho enlace.

Cada mensaje enviado por IoT Platform al cliente consta de las siguientes partes:

• Cuerpo del mensaje. La carga útil del mensaje está en formato binario.

• Atributos del mensaje, como el tema y el ID del mensaje. Puede obtener los atributos de la sección application-properties definida en AMQP. Los atributos tienen el formato key:value.

  Clave	Descripción
  topic	El tema del mensaje.
  messageId	El ID del mensaje.
  generateTime	La hora en que se generó el mensaje. Nota No es posible determinar el orden de los mensajes basándose en el parámetro generateTime.

Acuse de recibo del mensaje:

El cliente AMQP envía un acuse de recibo a IoT Platform para notificar que se recibió un mensaje. El acuse puede enviarse manual o automáticamente. Se recomienda utilizar el modo automático. Para más información, consulte la guía de usuario del cliente.

Ejemplos

Puede utilizar uno de los siguientes SDK AMQP específicos por lenguaje de programación para conectar un cliente a IoT Platform. Para más información sobre cómo configurar los parámetros, consulte la sección Connection settings de este tema.

• Java SDK connection example

• Connect a client to IoT Platform by using the SDK for .NET

• Node.js SDK connection example

• Connect a client to IoT Platform by using the SDK for Python 2.7

• Example: Python 3 SDK connection

• PHP SDK connection example

• Go SDK connection example

Al conectar un cliente a IoT Platform, podría recibir códigos de error relacionados con mensajes. Para más información, consulte la sección Error codes that are related to messages del tema "Registros de IoT Platform".