Pub - IoT Platform - Centro de documentación de Alibaba Cloud

Publica un mensaje en un dispositivo mediante un tema personalizado. Puede llamar a esta operación para difundir mensajes a los dispositivos en línea de un producto específico. Los dispositivos en línea se suscriben a un tema personalizado determinado.

Notas de uso

Al llamar a esta operación para difundir mensajes, tenga en cuenta lo siguiente:

Al configurar un dispositivo, debe escribir código para definir un tema. No es necesario crear el tema en la consola de IoT Platform.
De forma predeterminada, puede suscribirse a un tema con un máximo de 1,000 dispositivos. Si desea suscribirse a los mensajes de difusión de un tema personalizado para más de 1,000 dispositivos, utilice Message Queuing Telemetry Transport (MQTT) 5.0 para la comunicación, habilite la función de difusión para el tema personalizado y luego especifique los mensajes del tema personalizado como mensajes retenidos. Para obtener más información, consulte UpdateTopicConfig.

Límites

No puede llamar a esta operación para enviar comandos que configuren propiedades del dispositivo o invoquen servicios del dispositivo.

Para configurar propiedades del dispositivo, llame a la operación SetDeviceProperty o SetDevicesProperty.
Para invocar servicios del dispositivo, llame a la operación InvokeThingService o InvokeThingsService.

Límites de QPS

Puede llamar a esta operación de API hasta 1,600 veces por segundo por cuenta.

Nota

Los usuarios de Resource Access Management (RAM) de una cuenta de Alibaba Cloud comparten la cuota de dicha cuenta.

Depuración

OpenAPI Explorer calcula automáticamente el valor de la firma. Para su comodidad, le recomendamos que llame a esta operación en OpenAPI Explorer. OpenAPI Explorer genera dinámicamente el código de ejemplo de la operación para diferentes SDK.

Parámetros de solicitud

Parámetro	Tipo	Obligatorio	Ejemplo	Descripción
Action	String	Sí	Pub	La operación que desea ejecutar. Establezca el valor en Pub.
ProductKey	String	Sí	a1Q5XoY****	La ProductKey del producto al que pertenece el dispositivo que recibe el mensaje.
MessageContent	String	Sí	eyJ0ZXN0IjoidGFzayBwdWIgYnJvYWRjYXN0In0=	El cuerpo del mensaje que desea publicar. Para generar un cuerpo de mensaje, convierta el mensaje sin procesar en datos binarios y aplique la codificación Base64. Nota IoT Platform decodifica los datos mediante el algoritmo Base64 y luego envía el mensaje decodificado al dispositivo. De este modo, el dispositivo no necesita decodificar los datos codificados en Base64.
TopicFullName	String	Sí	/a1Q5XoY****/device1/user/get	El tema personalizado para el dispositivo que recibe el mensaje. Si utiliza un dispositivo de puerta de enlace MQTT, el tema personalizado original del dispositivo se utiliza como tema personalizado. Para obtener más información, consulte Temas. Si utiliza un dispositivo de puerta de enlace no MQTT, el tema personalizado tiene uno de los siguientes formatos: `/${productKey}/${deviceName}/user/${TopicShortName}`: El sistema envía un mensaje a un dispositivo específico que pertenece a un producto cuya ProductKey se especifica mediante la variable ${productKey}. `/broadcast/${productKey}/${Custom field}`: El sistema envía un mensaje a los dispositivos en línea de un producto cuya ProductKey se especifica mediante la variable ${productKey}. Los dispositivos en línea se suscriben al tema personalizado. Reemplace `${productKey}` con la ProductKey del producto cuyos dispositivos reciben el mensaje. La variable `${Custom field}` especifica un campo personalizado. Importante El tema debe tener el permiso Subscribe o Publish and Subscribe. Antes de llamar a la operación Pub, asegúrese de que el dispositivo esté suscrito al tema. De lo contrario, el dispositivo no podrá recibir el mensaje. Para consultar temas personalizados, utilice uno de los siguientes métodos: Llame a la operación QueryProductTopic para consultar los temas personalizados de un producto. En la pestaña Topic Categories de la página de detalles de un producto, consulte los temas personalizados del producto. En la pestaña Topic List de la página de detalles de un dispositivo, consulte los temas personalizados a los que está suscrito el dispositivo.
IotInstanceId	String	No	iot-cn-0pp1n8t****	El ID de la instancia. Puede consultar el ID de la instancia en la página Overview de la consola de IoT Platform. Importante Si su instancia tiene un ID, debe especificar el ID para este parámetro. De lo contrario, la llamada fallará. Si no se muestra la página Overview o si su instancia no tiene un ID, no es necesario que especifique este parámetro. Para obtener más información, consulte el tema Descripción general de instancias de IoT.
Qos	Integer	No	0	El nivel de calidad de servicio (QoS) del mensaje. Valores válidos: 0: El sistema envía el mensaje como máximo una vez. 1: El sistema envía el mensaje como mínimo una vez. Si no se devuelve una respuesta PUBACK después de publicar un mensaje QoS 1, el mensaje se envía nuevamente al dispositivo cuando este se reconecta a IoT Platform. Valor predeterminado: 0. Para obtener más información sobre mensajería, consulte la sección "Conexión de dispositivos" en el tema Límites.
ResponseTopic	String	No	/a1Q5XoY****/device1/user/update	El tema de respuesta en el modo de comunicación solicitud/respuesta cuando utiliza MQTT 5.0 para la comunicación. Para obtener más información, consulte MQTT 5.0.
CorrelationData	String	No	aGVsbG8****	Los datos relacionados en el modo de comunicación solicitud/respuesta cuando utiliza MQTT 5.0. Puede configurar este parámetro según sus requisitos empresariales. Un destinatario del mensaje puede procesar la solicitud basándose en los datos. Nota Debe convertir los datos relacionados en datos binarios y aplicar la codificación Base64 para generar un valor de tipo cadena.
UserProp.N.Key	String	No	key1	La clave de propiedad personalizada que se especifica cuando utiliza MQTT 5.0 para la comunicación. Debe usar este parámetro junto con el parámetro UserProp.N.Value.
UserProp.N.Value	String	No	value1	El valor de propiedad personalizada que se especifica cuando utiliza MQTT 5.0 para la comunicación. Debe usar este parámetro junto con UserProp.N.Key.
DeviceName	String	No	device1	El nombre de la puerta de enlace en la nube MQTT. Importante Este parámetro es obligatorio solo si desea enviar un mensaje a una puerta de enlace en la nube MQTT.
ContentType	String	No	text	El tipo de contenido del mensaje cuando utiliza MQTT 5.0 para la comunicación. Este parámetro especifica el tipo de archivo MIME, como text o plain.
PayloadFormatIndicator	Integer	No	1	El identificador de carga útil del mensaje cuando utiliza MQTT 5.0 para la comunicación. Valores válidos: 0: El mensaje consiste en datos de bytes desconocidos. 1: La carga útil del mensaje son datos de caracteres codificados en UTF-8.
Retained	Boolean	No	true	Especifica si se debe etiquetar el mensaje como mensaje retenido cuando utiliza MQTT 5.0 para la comunicación. true false
MessageExpiryInterval	Long	No	2	El periodo de validez del mensaje cuando utiliza MQTT 5.0 para la comunicación. Unidad: segundos. El periodo de validez de los mensajes QoS 0 oscila entre 0 y 86,400 segundos. El periodo de validez de los mensajes QoS 1 oscila entre 0 y 604,800 segundos.
TopicAlias	Integer	No	123	El alias de tema que puede especificar cuando utiliza MQTT 5.0 para la comunicación. El alias de tema ayuda a reducir el tráfico de comunicación entre los dispositivos e IoT Platform. Importante Los alias de tema funcionan basándose en asignaciones entre nombres de tema y alias. Los dispositivos e IoT Platform deben mantener las asignaciones correspondientes. Se crea una asignación la primera vez que un dispositivo usa un alias para enviar mensajes y se elimina cuando el dispositivo se desconecta. Se crea una asignación entre un nombre de tema y un alias cada vez que un dispositivo se reconecta a IoT Platform y usa el tema correspondiente para enviar mensajes. Cada alias debe ser único. Un alias corresponde a un solo nombre de tema. Si utiliza un alias de tema, no publique mensajes simultáneamente. De lo contrario, los mensajes publicados de forma concurrente podrían perderse debido a la arquitectura distribuida de IoT Platform. Si utiliza un alias de tema, debe especificar TopicAlias cada vez que llame a la operación Pub. IoT Platform admite hasta 20 alias de tema. Esto indica que los mensajes descendentes de un dispositivo pueden usar hasta 20 alias de tema. Para obtener más información sobre los alias de tema, consulte Alias de tema en funciones de MQTT 5.0.

Además de los parámetros de solicitud específicos de la operación anteriores, debe configurar parámetros de solicitud comunes al llamar a esta operación. Para obtener más información sobre los parámetros de solicitud comunes, consulte Parámetros comunes.

Parámetros de respuesta

Parámetro	Tipo	Ejemplo	Descripción
Code	String	iot.system.SystemException	El código de error que se devuelve si la llamada falla. Para obtener más información sobre los códigos de error, consulte Códigos de error.
ErrorMessage	String	A system exception occurred.	El mensaje de error que se devuelve si la llamada falla.
MessageId	String	889455942124347329	El ID de mensaje generado por IoT Platform cuando se envía el mensaje.
RequestId	String	BB71E443-4447-4024-A000-EDE09922891E	El ID de la solicitud.
Success	Boolean	true	Indica si la llamada fue exitosa. Valores válidos: true false

Ejemplos

Solicitudes de ejemplo

https://iot.cn-shanghai.aliyuncs.com/?Action=Pub
&ProductKey=a1Q5XoY****
&TopicFullName=/a1Q5XoY****/device1/user/get
&MessageContent=eyJ0ZXN0IjoidGFzayBwdWIgYnJvYWRjYXN0In0=
&Qos=0
&ResponseTopic=/a1Q5XoY****/device1/user/update
&CorrelationData=aGVsbG8%3D****
&UserProp.1.Key=k1&UserProp.1.Value=v1
&<Common request parameters>

Respuestas exitosas de ejemplo

XML formato

<PubResponse>
    <RequestId>BB71E443-4447-4024-A000-EDE09922891E</RequestId>
    <Success>true</Success>
    <MessageId>889455942124347329</MessageId>
</PubResponse>

JSON formato

{
      "RequestId":"BB71E443-4447-4024-A000-EDE09922891E",
      "Success":true,
      "MessageId":889455942124347329
  }

Códigos de error

Para obtener una lista de códigos de error, consulte Códigos de error del servicio.