InvokeThingService - IoT Platform - Centre de documentation Alibaba Cloud

Appelle un service d'un appareil.

Notes d'utilisation

Lorsque vous définissez un service dans un modèle de langage de spécification des objets (TSL), le mode d'appel du service est spécifié. Lorsque vous appelez un service à l'aide de cette opération, IoT Platform utilise un mode d'appel basé sur la valeur du paramètre Identifier.

Mode synchrone : IoT Platform envoie une demande d'appel de procédure distante réversible (RRPC) à un appareil. L'appareil renvoie ensuite une réponse RRPC de manière synchrone. Pour plus d'informations sur l'utilisation d'une RRPC, consultez Qu'est-ce que RRPC ?
Mode asynchrone : IoT Platform envoie une demande RRPC à un appareil. L'appareil renvoie ensuite une réponse RRPC de manière asynchrone. Pour plus d'informations, consultez Propriétés, événements et services des appareils.

Important

Si vous définissez le paramètre Checksum Type sur

Verification-free

lors de la création d'un produit, le mode asynchrone est utilisé.

Lorsque l'appareil reçoit l'appel de service, il renvoie une réponse à l'appelant du service. Lors de la configuration de l'appareil, vous devez spécifier la logique de réponse et les paramètres de réponse. Les formats de données des paramètres de réponse doivent être conformes au protocole Alink. Exemple :


{
    "id": "58***89",
    "code": 200,
    "data": {},
    "message": "success",
    "localizedMsg": "localizedMsg"
}

Remarque

Le paramètre id spécifie l'identifiant unique de la demande. L'ID est généré par IoT Platform. L'appareil peut obtenir l'ID à partir des paramètres de la demande, puis le renvoyer.
Le paramètre code spécifie le résultat de l'appel de service. La valeur du paramètre est un entier.
Le paramètre data spécifie le résultat de l'appel de service. Ce paramètre est renvoyé à l'appelant du service. Vous pouvez spécifier les paramètres que vous souhaitez inclure dans le résultat renvoyé. Les données doivent être au format JSON.
Les paramètres message et localizedMsg sont facultatifs.

Link SDK for C d'IoT Platform fournit un exemple sur l'utilisation d'un modèle TSL. Pour plus d'informations, consultez Appeler des services d'appareil.

Limites

Si vous appelez un service de manière synchrone, le délai d'expiration est de 8 secondes. Si un serveur ne reçoit pas de réponse dans un délai de 8 secondes, une erreur de délai d'expiration se produit. Aucune limite n'est imposée au délai d'expiration des appels asynchrones.

Limite de QPS

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

Remarque

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

Débogage

OpenAPI Explorer calcule automatiquement la valeur de signature. Pour votre 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 la demande

Parameter	Type	Required	Example	Description
Action	String	Yes	InvokeThingService	L'opération que vous souhaitez effectuer. Définissez la valeur sur InvokeThingService.
Args	String	Yes	{"param1":1}	Le paramètre d'entrée du service. La valeur est une chaîne JSON. Exemple : Args={"param1": 1}. Si vous ne souhaitez pas configurer de paramètre d'entrée pour le service, définissez la valeur sur Args={}. Important Si les données TSL sont de type float ou double, les valeurs de paramètre correspondant aux données TSL contiennent au moins une décimale. Exemples : 10,0 et 11,1.
Identifier	String	Yes	Set	L'identifiant du service. Pour afficher l'identifier du service, vous pouvez utiliser l'une des méthodes suivantes : Connectez-vous à la console IoT Platform. Dans l'onglet Define Feature du produit auquel appartient l'appareil, affichez l'identifiant. Appelez l'opération QueryThingModel et affichez l'identifiant dans les informations TSL renvoyées. Remarque Si un service nommé testService appartient à un module personnalisé nommé testFb, vous pouvez définir ce paramètre sur testFb:testService. Le module personnalisé n'est pas le module par défaut.
IotInstanceId	String	No	iot_instc_pu***_c-v64********	L'ID de l'instance IoT. Sur la page Overview de la console IoT Platform, vous pouvez afficher l'ID de l'instance. Important Si votre instance possède un ID, vous devez spécifier l'ID pour le paramètre. Sinon, l'appel échoue. Si aucune page Overview ou aucun ID n'est généré pour votre instance, vous n'avez pas besoin de configurer ce paramètre. Pour plus d'informations, consultez Aperçu des instances.
ProductKey	String	No	a1BwAGV****	La ProductKey du produit auquel appartient l'appareil. Important Si vous spécifiez une valeur pour ce paramètre, vous devez configurer le paramètre DeviceName.
DeviceName	String	No	light	Le DeviceName de l'appareil auquel appartient le service requis. Important Si vous spécifiez une valeur pour ce paramètre, vous devez configurer le paramètre ProductKey.
IotId	String	No	Q7uOhVRdZRRlDnTLv****00100	L'ID de l'appareil. L'ID est un identifiant unique émis par IoT Platform pour l'appareil. Important Le paramètre IotId spécifie un GUID pour l'appareil. La valeur du paramètre IotId équivaut à une combinaison des valeurs des paramètres ProductKey et DeviceName. Si vous spécifiez une valeur pour le paramètre IotId, vous n'avez pas besoin de spécifier de valeurs pour les paramètres ProductKey et DeviceName. Si vous spécifiez des valeurs pour les paramètres IotId,ProductKey et DeviceName, la valeur du paramètre IotId est prioritaire.
Qos	Integer	No	1	Le niveau de qualité de service (QoS) du message. Valeurs valides : 0 (par défaut) : Le système envoie le message au maximum une fois. 1 : Le système envoie le message au moins une fois. Si une réponse PUBACK n'est pas renvoyée après la publication d'un message QoS 1, le message est renvoyé à l'appareil lorsque celui-ci se reconnecte à IoT Platform.

En plus des paramètres de demande spécifiques à l'opération précédents, vous devez configurer des paramètres de demande communs lors de l'appel de cette opération. Pour plus d'informations sur les paramètres de demande communs, consultez Paramètres communs.

Paramètres de réponse

Parameter	Type	Example	Description
Code	String	iot.system.SystemException	Le code d'erreur renvoyé en cas d'échec de l'appel. Pour plus d'informations, consultez Codes d'erreur.
Data	Struct		Les données renvoyées en cas de succès de l'appel.
MessageId	String	abcabcabc1234****	L'ID du message. IoT Platform envoie le message à l'appareil pour appeler le service.
Result	String	{"param1":1}	Le résultat de l'appel synchrone. Si vous appelez le service de manière asynchrone, ce paramètre n'est pas renvoyé.
ErrorMessage	String	A system exception occurred.	Le message d'erreur renvoyé en cas d'échec de l'appel.
RequestId	String	E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565	L'ID de la demande.
Success	Boolean	true	Indique si l'appel a réussi. Valeurs valides true : L'appel a réussi. Toutefois, cette valeur n'indique pas que le service est exécuté. Pour obtenir le résultat d'exécution, consultez les journaux de l'appareil. false : L'appel a échoué.

Exemples

Exemples de demandes

https://iot.cn-shanghai.aliyuncs.com/?Action=InvokeThingService
&ProductKey=a1BwAGV****
&DeviceName=device1
&Identifier=service1
&Args=%7B%22param1%22%3A1%7D
&<Common request parameters>

Exemples de réponses réussies

Format XML

<InvokeThingServiceResponse>
  <Data>
        <Result>{"code":200,"data":{},"id":"100686","message":"success","version":"1.0"}</Result>
        <MessageId>abcabc123</MessageId>
  </Data>
  <RequestId>A44C818E-FA7F-4765-B1E7-01D14AE01C6A</RequestId>
  <Success>true</Success>
</InvokeThingServiceResponse>

Format JSON

{
  "Data": {
    "Result": "{\"code\":200,\"data\":{},\"id\":\"100686\",\"message\":\"success\",\"version\":\"1.0\"}", 
    "MessageId": "abcabc123"
  }, 
  "RequestId": "A44C818E-FA7F-4765-B1E7-01D14AE01C6A", 
  "Success": true
}

Codes d'erreur

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