InvokeThingService - IoT Platform - Alibaba Cloud ドキュメントセンター

デバイスのサービスを呼び出します。

使用方法

Thing Specification Language（TSL）モデルでサービスを定義する場合、サービスが呼び出されるモードが指定されます。このオペレーションを使用してサービスを呼び出す場合、IoT Platform は 識別子 パラメーターの値に基づいて呼び出しモードを使用します。

同期モード: IoT Platform は、デバイスに revert-remote procedure call（RRPC）リクエストを送信します。次に、デバイスは RRPC 応答を同期的に返します。 RRPC の使用方法の詳細については、「RRPC とは」をご参照ください。
非同期モード: IoT Platform は、デバイスに RRPC リクエストを送信します。次に、デバイスは RRPC 応答を非同期的に返します。トピックの詳細については、「デバイスのプロパティ、イベント、およびサービス」をご参照ください。

重要製品の作成時にチェックサムタイプパラメーターを 検証不要 に設定すると、非同期モードが使用されます。

デバイスがサービスコールを受信すると、デバイスはサービス呼び出し元にレスポンスを返します。デバイスを構成する場合は、レスポンスロジックとレスポンスパラメーターを指定する必要があります。レスポンスパラメーターのデータ形式は、Alink プロトコルに準拠している必要があります。例：

{
    "id": "58***89", // リクエストのユニーク ID
    "code": 200, // サービスコールの結果コード
    "data": {}, // サービスコールの結果データ
    "message": "success", // 成功メッセージ
    "localizedMsg": "localizedMsg" // ローカライズされたメッセージ
}

説明

id パラメーターは、リクエストの一意の識別子を指定します。 ID は IoT Platform によって生成されます。デバイスはリクエストパラメーターから ID を取得し、ID を返すことができます。
code パラメーターは、サービスコールの結果を指定します。パラメーターの値は整数です。
data パラメーターは、サービスコールの結果を指定します。このパラメーターは、サービス呼び出し元に返されます。返される結果に含めるパラメーターを指定できます。データは JSON 形式である必要があります。
message パラメーターと localizedMsg パラメーターはオプションです。
IoT Platform の Link SDK for C は、TSL モデルの使用方法の例を提供しています。詳細については、「デバイスサービスの呼び出し」をご参照ください。

制限

サービスを同期的に呼び出す場合、タイムアウト期間は 8 秒です。サーバーが 8 秒以内に応答を受信しない場合、タイムアウトエラーが発生します。非同期呼び出しのタイムアウト期間には制限はありません。

QPS の制限

この API オペレーションは、アカウントごとに 1 秒あたり最大 500 回呼び出すことができます。

説明 Alibaba Cloud アカウントの RAM ユーザーは、アカウントのクォータを共有します。

デバッグ

OpenAPI Explorer は署名の値を自動的に計算します。便宜上、OpenAPI Explorer でこの操作を呼び出すことをお勧めします。 OpenAPI Explorer は、さまざまな SDK の操作のサンプルコードを動的に生成します。

リクエストパラメーター

パラメーター	タイプ	必須	例	説明
Action	String	はい	InvokeThingService	実行する操作。値を InvokeThingService に設定します。
Args	String	はい	{"param1":1}	サービスの入力パラメーター。値は JSON 文字列です。例：Args={"param1": 1}。サービスに入力パラメーターを構成したくない場合は、値を Args={} に設定します。重要 TSL データが float 型または double 型の場合、TSL データに対応するパラメーター値には、少なくとも 1 つの小数点以下の桁数が含まれます。例：10.0 および 11.1。
Identifier	String	はい	Set	サービスの識別子。サービスの識別子を表示するには、次のいずれかの方法を使用できます。 IoT Platform コンソールにログインします。デバイスが属する製品の機能の定義タブで、識別子を表示します。 QueryThingModel オペレーションを呼び出し、返される TSL 情報で識別子を表示します。説明 testFb という名前のカスタムモジュールに testService という名前のサービスが属している場合、このパラメーターを testFb:testService に設定できます。カスタムモジュールはデフォルトモジュールではありません。
IotInstanceId	String	いいえ	iot_instc_pu***_c-v64********	IoT インスタンスの ID。IoT Platform コンソールの概要ページで、インスタンスの ID を表示できます。重要インスタンスに ID がある場合は、パラメーターに ID を指定する必要があります。そうでない場合、呼び出しは失敗します。インスタンスに対して概要ページまたは ID が生成されない場合は、このパラメーターを構成する必要はありません。詳細については、「インスタンスの概要」をご参照ください。
ProductKey	String	いいえ	a1BwAGV****	デバイスが属する製品の ProductKey。重要このパラメーターに値を指定する場合は、DeviceName パラメーターを構成する必要があります。
DeviceName	String	いいえ	light	必要なサービスが属するデバイスの DeviceName。重要このパラメーターに値を指定する場合は、ProductKey パラメーターを構成する必要があります。
IotId	String	いいえ	Q7uOhVRdZRRlDnTLv****00100	デバイスの ID。 ID は、IoT Platform がデバイスに発行する一意の識別子です。重要 IotId パラメーターは、デバイスの GUID を指定します。 IotId パラメーターの値は、ProductKey パラメーターと DeviceName パラメーターの値の組み合わせと同じです。 IotId パラメーターに値を指定する場合は、ProductKey パラメーターと DeviceName パラメーターに値を指定する必要はありません。 IotId パラメーター、ProductKey パラメーター、および DeviceName パラメーターに値を指定する場合、IotId パラメーターの値が優先されます。
Qos	Integer	いいえ	1	メッセージのサービス品質（QoS）レベル。有効な値： 0（デフォルト）：システムはメッセージを最大 1 回送信します。 1：システムはメッセージを少なくとも 1 回送信します。 QoS 1 メッセージをパブリッシュした後に PUBACK 応答が返されない場合、デバイスが IoT Platform に再接続すると、メッセージがデバイスに再送信されます。

上記の操作固有のリクエストパラメーターに加えて、この操作を呼び出すときは、共通のリクエストパラメーターを構成する必要があります。共通のリクエストパラメーターの詳細については、「共通パラメーター」をご参照ください。

レスポンスパラメーター

パラメーター	タイプ	例	説明
Code	String	iot.system.SystemException	呼び出しが失敗した場合に返されるエラーコード。詳細については、「エラーコード」をご参照ください。
Data	Struct		呼び出しが成功した場合に返されるデータ。
MessageId	String	abcabcabc1234****	メッセージの ID。 IoT Platform は、サービスを呼び出すためにデバイスにメッセージを送信します。
Result	String	{"param1":1}	同期呼び出しの結果。サービスを非同期的に呼び出す場合、このパラメーターは返されません。
ErrorMessage	String	システム例外が発生しました。	呼び出しが失敗した場合に返されるエラーメッセージ。
RequestId	String	E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565	リクエストの ID。
Success	Boolean	true	呼び出しが成功したかどうかを示します。有効な値 true：呼び出しは成功しました。ただし、この値はサービスが実行されたことを示すものではありません。実行結果を取得するには、デバイスのログを表示します。 false：呼び出しは失敗しました。

例

リクエストの例

https://iot.cn-shanghai.aliyuncs.com/?Action=InvokeThingService
&ProductKey=a1BwAGV****
&DeviceName=device1
&Identifier=service1
&Args=%7B%22param1%22%3A1%7D
&<共通リクエストパラメーター>

成功レスポンスの例

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>

JSON 形式

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

エラーコード

エラーコードのリストについては、「サービスエラーコード」をご参照ください。