BatchAddThingTopo - IoT Platform - Centre de documentation Alibaba Cloud

Établit plusieurs relations topologiques en un seul appel.

Notes d'utilisation

Associez jusqu'à 10 sous-périphériques à une passerelle en un seul appel.
L'appelant de l'opération API doit être le propriétaire de la passerelle.
Si vous spécifiez un sous-périphérique déjà associé à une passerelle, la passerelle d'origine est remplacée par celle indiquée.
Si l'établissement d'une relation topologique entre la passerelle et l'un des sous-périphériques spécifiés échoue, le système annule l'opération (rollback) : aucune relation topologique n'est établie pour les sous-périphériques spécifiés.
Après avoir appelé cette opération pour établir des relations topologiques entre les sous-périphériques et la passerelle, IoT Platform utilise la rubrique /sys/${productKey}/${deviceName}/thing/topo/change pour envoyer à la passerelle des informations incluant le résultat de cette opération. Pour plus d'informations, consultez la section Notifier les passerelles des modifications des relations topologiques.

Limites QPS

Vous pouvez appeler cette opération API jusqu'à 10 fois par seconde par compte Alibaba Cloud.

Remarque

Les utilisateurs RAM d'un compte Alibaba Cloud partagent le quota du compte.

Débogage

OpenAPI Explorer calcule automatiquement la valeur de signature. Par commodité, 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	BatchAddThingTopo	Opération à effectuer. Définissez la valeur sur BatchAddThingTopo.
GwDeviceName	String	Oui	gateway	Nom de la passerelle.
GwProductKey	String	Oui	a1vL7cp****	Clé du produit auquel appartient la passerelle.
TopoAddItem.N.DeviceName	String	Oui	light	Nom de chaque sous-périphérique.
TopoAddItem.N.ProductKey	String	Oui	a1BwAGV****	Clé du produit auquel appartient le sous-périphérique.
TopoAddItem.N.Sign	String	Oui	C1C1606D61884C5F16C9EA6622E5****	Signature du sous-périphérique. Définissez le paramètre Sign sur le résultat de la fonction SignMethod(deviceSecret,content). Pour obtenir le paramètre content, triez par ordre alphabétique tous les paramètres du sous-périphérique soumis au serveur, à l'exception des paramètres Sign et SignMethod. Concaténez ensuite les paramètres et leurs valeurs séquentiellement, sans séparateur. Par exemple, si vous souhaitez spécifier les paramètres suivants pour un sous-périphérique : ClientId=868575026974305, DeviceName=868575026974305, ProductKey=a1PB5fp1234, SignMethod=hmacmd5, timestamp=1646277090411 et deviceSecret=1234. Dans ce cas, la fonction de signature est `hmacmd5(1234, clientId868575026974305deviceName868575026974305productKeya1PB5fp1234timestamp1646277090411)`, et le résultat du calcul est `3BA0DFA4C477B40C007D84D30D6466CC`. Remarque Dans l'exemple ci-dessus, ClientId indique l'ID client du sous-périphérique. Vous pouvez spécifier un ID client personnalisé. Pour plus d'informations sur le calcul de la valeur de signature, consultez la section Comment obtenir les paramètres MQTT pour l'authentification ?. La valeur de signature correspond à la valeur calculée du paramètre passwd.
TopoAddItem.N.SignMethod	String	Oui	hmacMd5	Algorithme de signature. Valeurs valides : hmacSha1, hmacSha256, hmacMd5 et Sha256. La valeur ne respecte pas la casse.
IotInstanceId	String	Non	iot_instc_pu***_c-v64********	ID de l'instance. Sur la page Overview de la console IoT Platform, vous pouvez consulter l'ID de l'instance. Important Si votre instance possède un ID, vous devez spécifier ce paramètre. Sinon, l'appel échouera. Si aucune page Overview ou aucun ID d'instance n'apparaît dans la console IoT Platform, ignorez ce paramètre. Pour plus d'informations, consultez la section Vue d'ensemble.
TopoAddItem.N.Timestamp	String	Non	1579335899000	Horodatage UTC. Ce paramètre est facultatif. Important Si ce paramètre est inclus dans la valeur du paramètre TopoAddItem.N.Sign, vous devez le spécifier.
TopoAddItem.N.ClientId	String	Non	a1BwAGV****device1	ID client du sous-périphérique. L'ID peut correspondre au numéro de série (SN) ou à l'adresse MAC (Media Access Control) de l'appareil. Ce paramètre est facultatif. Important Si ce paramètre est inclus dans la valeur du paramètre TopoAddItem.N.Sign, vous devez le spécifier.

En plus des paramètres de requête spécifiques à l'opération mentionnés précédemment, vous devez spécifier les paramètres de requête communs lors de l'appel à cette opération. Pour plus d'informations, consultez la section Paramètres communs.

Paramètres de réponse

Paramètre	Type	Exemple	Description
Code	String	iot.system.SystemException	Code d'erreur renvoyé en cas d'échec de l'appel. Pour plus d'informations, consultez la section Codes d'erreur.
ErrorMessage	String	A system exception occurred.	Message d'erreur renvoyé en cas d'échec de l'appel.
RequestId	String	E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565	ID de la requête.
Success	Boolean	true	Indique si l'appel a réussi. true : L'appel a réussi. false : L'appel a échoué.

Exemples

Exemple de requête

https://iot.cn-shanghai.aliyuncs.com/?Action=BatchAddThingTopo
&GwProductKey=a1duisa****
&GwDeviceName=tydhnay16shc6
&TopoAddItem.1.ProductKey=a1rYuVF****
&TopoAddItem.1.DeviceName=SR8FiTu1R9tlUR2V1bmi
&TopoAddItem.1.Sign=dgj1609rD6IUGFCRkJKKdNKAE67h8****
&TopoAddItem.1.SignMethod=hmacMd5
&TopoAddItem.2.ProductKey=a1yrZMH****
&TopoAddItem.2.DeviceName=RkQ8CFtNpDok4BEunymt
&TopoAddItem.2.Sign=C1C1606D61884C5F16C9EA6622E5****
&TopoAddItem.2.SignMethod=hmacMd5
&<Common request parameters>

Exemple de réponse réussie

Format XML

<BatchAddThingTopoResponse>
  <RequestId>2E19BDAF-0FD0-4608-9F41-82D230CFEE38</RequestId>
  <Success>true</Success>
</BatchAddThingTopoResponse>

Format JSON

{
  "RequestId": "2E19BDAF-0FD0-4608-9F41-82D230CFEE38",
  "Success": true
}

Codes d'erreur

Pour obtenir la liste des codes d'erreur, consultez le Centre d'erreurs API.