Pub - IoT Platform - Centre de documentation Alibaba Cloud

Publiez un message vers un appareil en utilisant un topic personnalisé. Vous pouvez appeler cette opération pour diffuser des messages aux appareils en ligne d'un produit spécifique. Les appareils en ligne s'abonnent à un topic personnalisé spécifique.

Notes d'utilisation

Lorsque vous appelez cette opération pour diffuser des messages, tenez compte des points suivants :

Lors de la configuration d'un appareil, vous devez écrire du code pour définir un topic. Il n'est pas nécessaire de créer un topic dans la console IoT Platform.
Par défaut, vous pouvez vous abonner à un topic pour un maximum de 1 000 appareils. Si vous souhaitez vous abonner aux messages de diffusion d'un topic personnalisé pour plus de 1 000 appareils, utilisez le protocole MQTT (Message Queuing Telemetry Transport) 5.0 pour la communication, activez la fonctionnalité de diffusion pour le topic personnalisé, puis spécifiez les messages du topic personnalisé comme messages conservés (retained messages). Pour plus d'informations, consultez UpdateTopicConfig.

Limites

Vous ne pouvez pas utiliser cette opération pour envoyer des commandes afin de configurer les propriétés des appareils ou d'appeler les services des appareils.

Pour configurer les propriétés des appareils, appelez l'opération SetDeviceProperty ou SetDevicesProperty.
Pour appeler les services des appareils, appelez l'opération InvokeThingService ou InvokeThingsService.

Limites QPS

Vous pouvez appeler cette API jusqu'à 1 600 fois par seconde par compte.

Remarque

Les utilisateurs RAM (Resource Access Management) d'un compte Alibaba Cloud partagent le quota du compte.

Débogage

OpenAPI Explorer calcule automatiquement la valeur de signature. Par souci de simplicité, nous vous recommandons d'appeler cette opération dans OpenAPI Explorer. OpenAPI Explorer génère dynamiquement l'exemple de code de l'opération pour différents SDK.

Paramètres de requête

Paramètre	Type	Obligatoire	Exemple	Description
Action	String	Oui	Pub	L'opération que vous souhaitez effectuer. Définissez la valeur sur Pub.
ProductKey	String	Oui	a1Q5XoY****	La ProductKey du produit auquel appartient l'appareil qui reçoit le message.
MessageContent	String	Oui	eyJ0ZXN0IjoidGFzayBwdWIgYnJvYWRjYXN0In0=	Le corps du message que vous souhaitez publier. Pour générer un corps de message, convertissez le message brut en données binaires et effectuez un encodage Base64. Remarque IoT Platform décode les données à l'aide de l'algorithme Base64, puis envoie le message décodé à l'appareil. Ainsi, l'appareil n'a pas besoin de décoder les données encodées en Base64.
TopicFullName	String	Oui	/a1Q5XoY****/device1/user/get	Le topic personnalisé de l'appareil qui reçoit le message. Si vous utilisez un appareil passerelle MQTT, le topic personnalisé d'origine de l'appareil est utilisé comme topic personnalisé. Pour plus d'informations, consultez Topics. Si vous utilisez un appareil non passerelle MQTT, le topic personnalisé respecte l'un des formats suivants : `/${productKey}/${deviceName}/user/${TopicShortName}` : Le système envoie un message à un appareil spécifique appartenant à un produit dont la variable ProductKey est spécifiée par ${productKey}. `/broadcast/${productKey}/${Custom field}` : Le système envoie un message aux appareils en ligne d'un produit dont la variable ProductKey est spécifiée par ${productKey}. Les appareils en ligne s'abonnent au topic personnalisé. Remplacez `${productKey}` par la ProductKey du produit dont les appareils reçoivent le message. La variable `${Custom field}` spécifie un champ personnalisé. Important Le topic doit disposer de l'autorisation Subscribe ou Publish and Subscribe. Avant d'appeler l'opération Pub, assurez-vous que l'appareil est abonné au topic. Sinon, l'appareil ne pourra pas recevoir le message. Pour interroger les topics personnalisés, utilisez l'une des méthodes suivantes : Appelez l'opération QueryProductTopic pour interroger les topics personnalisés d'un produit. Dans l'onglet Topic Categories de la page de détails d'un produit, consultez les topics personnalisés du produit. Dans l'onglet Topic List de la page de détails d'un appareil, consultez les topics personnalisés auxquels l'appareil est abonné.
IotInstanceId	String	Non	iot-cn-0pp1n8t****	L'ID de l'instance. Vous pouvez consulter l'ID de l'instance sur la page Overview de la console IoT Platform. Important Si votre instance possède un ID, vous devez spécifier l'ID pour ce paramètre. Sinon, l'appel échoue. Si la page Overview n'est pas affichée ou si votre instance ne possède pas d'ID, vous n'avez pas besoin de spécifier ce paramètre. Pour plus d'informations, consultez la rubrique Overview des instances IoT.
Qos	Integer	Non	0	Le niveau de qualité de service (QoS) du message. Valeurs valides : 0 : Le système envoie le message au plus une fois. 1 : Le système envoie le message au moins une fois. Si aucune réponse PUBACK n'est renvoyée après la publication d'un message QoS 1, le message est de nouveau poussé vers l'appareil lorsque celui-ci se reconnecte à IoT Platform. Valeur par défaut : 0. Pour plus d'informations sur la messagerie, consultez la section « Device connection » de la rubrique Limits.
ResponseTopic	String	Non	/a1Q5XoY****/device1/user/update	Le topic de réponse en mode de communication requête/réponse lorsque vous utilisez MQTT 5.0 pour la communication. Pour plus d'informations, consultez MQTT 5.0.
CorrelationData	String	Non	aGVsbG8****	Les données associées en mode de communication requête/réponse lorsque vous utilisez MQTT 5.0. Vous pouvez configurer ce paramètre en fonction de vos besoins métier. Un destinataire de message peut traiter la requête sur la base des données. Remarque Vous devez convertir les données associées en données binaires et effectuer un encodage Base64 pour générer une valeur de type chaîne.
UserProp.N.Key	String	Non	key1	La clé de propriété personnalisée spécifiée lorsque vous utilisez MQTT 5.0 pour la communication. Vous devez utiliser ce paramètre conjointement avec le paramètre UserProp.N.Value.
UserProp.N.Value	String	Non	value1	La valeur de propriété personnalisée spécifiée lorsque vous utilisez MQTT 5.0 pour la communication. Vous devez utiliser ce paramètre conjointement avec UserProp.N.Key.
DeviceName	String	Non	device1	Le nom de la passerelle cloud MQTT. Important Ce paramètre est requis uniquement si vous souhaitez envoyer un message à une passerelle cloud MQTT.
ContentType	String	Non	text	Le type de contenu du message lorsque vous utilisez MQTT 5.0 pour la communication. Ce paramètre spécifie le type d'un fichier MIME, tel que text ou plain.
PayloadFormatIndicator	Integer	Non	1	L'identifiant de charge utile du message lorsque vous utilisez MQTT 5.0 pour la communication. Valeurs valides : 0 : Le message correspond à des données octet inconnues. 1 : La charge utile du message correspond à des données de caractère encodées en UTF-8.
Retained	Boolean	Non	true	Indique s'il faut étiqueter le message comme un message conservé (retained message) lorsque vous utilisez MQTT 5.0 pour la communication. true false
MessageExpiryInterval	Long	Non	2	La période de validité du message lorsque vous utilisez MQTT 5.0 pour la communication. Unité : secondes. La période de validité des messages QoS 0 varie de 0 à 86 400 secondes. La période de validité des messages QoS 1 varie de 0 à 604 800 secondes.
TopicAlias	Integer	Non	123	L'alias de topic que vous pouvez spécifier lorsque vous utilisez MQTT 5.0 pour la communication. L'alias de topic permet de réduire le trafic de communication entre les appareils et IoT Platform. Important Les alias de topic fonctionnent sur la base de mappages entre les noms de topic et les alias. Les appareils et IoT Platform doivent maintenir les mappages correspondants. Un mappage est créé la première fois qu'un appareil utilise un alias pour envoyer des messages et est supprimé lorsque l'appareil est déconnecté. Un mappage est créé entre un nom de topic et un alias chaque fois qu'un appareil se reconnecte à IoT Platform et utilise le topic correspondant pour envoyer des messages. Chaque alias doit être unique. Un alias correspond à un seul nom de topic. Si vous utilisez un alias de topic, ne publiez pas de messages de manière concurrente. Sinon, les messages publiés de manière concurrente peuvent être perdus en raison de l'architecture distribuée d'IoT Platform. Si vous utilisez un alias de topic, vous devez spécifier TopicAlias à chaque appel de l'opération Pub. IoT Platform prend en charge jusqu'à 20 alias de topic. Cela signifie que les messages descendants d'un appareil peuvent utiliser jusqu'à 20 alias de topic. Pour plus d'informations sur les alias de topic, consultez Topic aliases in MQTT 5.0 features.

En plus des paramètres de requête spécifiques à l'opération mentionnés ci-dessus, vous devez configurer les paramètres de requête communs lors de l'appel de cette opération. Pour plus d'informations sur les paramètres de requête communs, consultez Common parameters.

Paramètres de réponse

Paramètre	Type	Exemple	Description
Code	String	iot.system.SystemException	Le code d'erreur renvoyé en cas d'échec de l'appel. Pour plus d'informations sur les codes d'erreur, consultez Error codes.
ErrorMessage	String	A system exception occurred.	Le message d'erreur renvoyé en cas d'échec de l'appel.
MessageId	String	889455942124347329	L'ID de message généré par IoT Platform lors de l'envoi du message.
RequestId	String	BB71E443-4447-4024-A000-EDE09922891E	L'ID de requête.
Success	Boolean	true	Indique si l'appel a réussi. Valeurs valides : true false

Exemples

Exemples de requêtes

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>

Exemples de réponses réussies

XML format

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

JSON format

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

Codes d'erreur

Pour obtenir la liste des codes d'erreur, consultez Codes d'erreur de service.