このトピックでは、Advanced Message Queuing Protocol（AMQP）クライアントを IoT Platform に接続する方法について説明します。この操作は、IoT Platform コンソールで AMQP サーバー側サブスクリプションを構成した後に実行できます。 AMQP クライアントを IoT Platform に接続すると、ビジネスサーバー上の AMQP クライアントを使用してデバイスメッセージを受信できます。
制限
AMQP の詳細については、AMQP 公式 Web サイトをご覧ください。
IoT Platform のサーバー側サブスクリプションは、AMQP 1.0 プロトコルのみをサポートしています。
IoT Platform への接続
AMQP クライアントは、3 ウェイハンドシェイクを使用して IoT Platform との TCP 接続を確立します。次に、TLS ハンドシェイクが実行され、AMQP クライアントが認証されます。
説明セキュリティを確保するために、AMQP クライアントは TLS 暗号化を使用してデータを送信する必要があります。暗号化されていない TCP チャネルを介してデータを送信することはできません。
クライアントは接続の確立をリクエストします。
PLAIN SASL メカニズムは、接続を認証するために使用されます。認証は、ユーザー名とパスワードに基づいています。ユーザー名とパスワードに基づく認証が IoT Platform によって渡されると、接続が確立されます。
AMQP に基づいて、クライアントは接続を確立するときに、idle-time-out フィールドを open フレームに追加する必要があります。このフィールドは、ハートビートタイムアウト期間を指定します。ハートビートタイムアウト期間は 30,000 ms から 300,000 ms の範囲です。ハートビートタイムアウト期間が経過した後、接続を介してフレームが送信されない場合、IoT Platform は接続を閉じます。idle-time-out フィールドを構成するために使用されるメソッドは、SDK のプログラミング言語によって異なります。詳細については、言語固有の SDK のサンプルコードをご参照ください。
クライアントは、レシーバーリンクを確立するためのリクエストを IoT Platform に送信します。レシーバーリンクは、IoT Platform からクライアントにデータをプッシュするために使用できる一方向チャネルです。
クライアントは、AMQP 接続が確立されてから 15 秒以内にレシーバーリンクを確立する必要があります。そうでない場合、IoT Platform は AMQP 接続を閉じます。
レシーバーリンクが確立されると、クライアントは IoT Platform に接続されます。
説明接続ごとに 1 つのレシーバーリンクのみを作成できます。センダーリンクはサポートされていません。 IoT Platform はクライアントにメッセージをプッシュできますが、クライアントは IoT Platform にメッセージを送信できません。
レシーバーリンクのクラス名は、SDK のプログラミング言語によって異なります。たとえば、一部の SDK では、レシーバーリンクは MessageConsumer という名前です。
接続設定
このセクションでは、AMQP クライアントを IoT Platform に接続するときにエンドポイントを指定し、認証パラメーターを構成する方法について説明します。
エンドポイントとポート
AMQP クライアントを接続するパブリックインスタンスまたは Enterprise Edition インスタンスのエンドポイントを指定します。サポートされているエンドポイントの詳細については、「インスタンスのエンドポイントを管理する」をご参照ください。
SDK の ${YourHost} 変数は、エンドポイントを指定します。
クライアントを IoT Platform インスタンスに接続する前に、プロダクトとデバイスがインスタンスに作成されていることを確認してください。
Java、.NET、Python 2.7、Node.js、または Go クライアントを使用する場合、ポート番号は 5671 です。
Python 3 または PHP クライアントを使用する場合、ポート番号は 61614 です。
認証パラメーター
構成する必要がある認証パラメーターは、AMQP クライアントを IoT Platform に接続するために使用する Alibaba Cloud ID によって異なります。
IoT Platform インスタンスが属する Alibaba Cloud アカウント、または Alibaba Cloud アカウント内で必要な権限を直接付与されている RAM ユーザーを使用する場合は、次の認証パラメーターを構成する必要があります。
説明RAM ユーザーを使用する場合は、iot:sub 操作を含む RAM ポリシーを RAM ユーザーにアタッチする必要があります。これにより、RAM ユーザーは IoT Platform のサーバー側サブスクリプション機能を使用できます。そうでない場合、接続は失敗します。詳細については、「IoT Platform API 操作と RAM ポリシー間のマッピング」をご参照ください。
データセキュリティを向上させるために、RAM ロールを使用して RAM ユーザーにサーバー側サブスクリプション機能の使用を承認することをお勧めします。詳細については、次のセクションをご参照ください。
userName = clientId|iotInstanceId=${iotInstanceId},authMode=aksign,signMethod=hmacsha1,consumerGroupId=${consumerGroupId},authId=${accessKey},timestamp=1573489088171| password = signMethod(stringToSign, accessSecret)RAM ロールによって承認された RAM ユーザーを使用する場合は、次の認証パラメーターを構成する必要があります。
説明IoT Platform インスタンスが属する Alibaba Cloud アカウントの RAM ユーザーに加えて、RAM ロールを使用して別の Alibaba Cloud アカウントの RAM ユーザーにサーバー側サブスクリプション機能の使用を承認できます。 RAM ロールを使用して RAM ユーザーに IoT Platform のサーバー側サブスクリプション機能の使用を承認する方法の詳細については、「現在の Alibaba Cloud アカウントの RAM ユーザーにサーバー側サブスクリプションの使用を承認する」および「別のアカウントの RAM ユーザーにサーバー側サブスクリプションの使用を承認する」をご参照ください。
userName = clientId|iotInstanceId=${iotInstanceId},authMode=ststoken,securityToken=${SecurityToken},signMethod=hmacsha1,consumerGroupId=${consumerGroupId},authId=${accessKey},timestamp=1573489088171| password = signMethod(stringToSign, accessSecret)表 1. userName のパラメーター
パラメーター
必須
説明
clientId
はい
クライアントの ID。カスタム ID を指定する必要があります。 ID は 1 ～ 64 文字の長さである必要があります。クライアントが実行されているサーバーの UUID、MAC アドレス、IP アドレスなど、一意の識別子をクライアント ID として使用することをお勧めします。
AMQP クライアントが IoT Platform に接続して起動した後、次の手順を実行してクライアントの詳細を表示します。IoT Platform コンソールにログインし、管理する インスタンス のカードをクリックします。左側のナビゲーションウィンドウで、 を選択します。[コンシューマーグループ] タブで、管理するコンシューマーグループを見つけ、[操作] 列の [表示] をクリックします。各クライアントの ID は、[コンシューマーグループステータス] タブに表示されます。クライアント ID を使用して、クライアントを簡単に識別できます。
iotInstanceId
いいえ
IoT Platform インスタンスの ID。インスタンス [ID] は、IoT Platform コンソールの [概要] タブで確認できます。
インスタンス ID が表示されている場合は、このパラメーターをインスタンス ID に設定する必要があります。
[概要] タブが表示されていない場合、またはインスタンスに ID がない場合は、このパラメーターを指定する必要はありません。
authMode
はい
認証モード。
IoT Platform インスタンスが属する Alibaba Cloud アカウント、または Alibaba Cloud アカウント内で必要な権限を直接付与されている RAM ユーザーを使用する場合は、
aksignモードを使用します。RAM ロールによって承認された RAM ユーザーを使用する場合は、
ststokenモードを使用します。
securityToken
いいえ
重要このパラメーターは、RAM ロールによって承認された RAM ユーザーを使用して AMQP クライアントを IoT Platform に接続する場合にのみ必要です。
RAM ロールを引き受ける RAM ユーザーに割り当てられたセキュリティトークンサービス（STS）トークン。 AssumeRole 操作を呼び出して、STS トークンを取得できます。詳細については、「AssumeRole」をご参照ください。
signMethod
はい
署名アルゴリズム。有効な値：
hmacmd5、hmacsha1、hmacsha256。consumerGroupId
はい
IoT Platform インスタンスのコンシューマーグループの ID。
コンシューマーグループの ID を表示するには、次の手順を実行します。IoT Platform コンソールにログインし、管理するインスタンスのカードをクリックします。左側のナビゲーションウィンドウで、 を選択します。コンシューマーグループの ID は、[コンシューマーグループ] タブに表示されます。
authId
はい
認証情報。
IoT Platform インスタンスが属する Alibaba Cloud アカウント、または Alibaba Cloud アカウント内で必要な権限を直接付与されている RAM ユーザーを使用する場合：
このパラメーターを Alibaba Cloud アカウントの AccessKey ID または RAM ユーザーの AccessKey ID に設定します。
IoT Platform コンソールにログインし、ポインターをプロファイル画像の上に移動して、[accesskey 管理] をクリックします。表示されるページで、AccessKey ID を取得します。
RAM ロールによって承認された RAM ユーザーを使用する場合：
このパラメーターを、RAM ロールを引き受ける RAM ユーザーの AccessKey ID に設定します。
timestamp
はい
現在の時刻。タイムスタンプは LONG 整数です。単位：ミリ秒。
表 2. password のパラメーター パラメーター
必須
説明
signMethod
はい
署名アルゴリズム。userName パラメーターで指定された署名アルゴリズムを使用して署名値を計算します。次に、値を Base64 エンコード文字列に変換します。
stringToSign
はい
署名対象の文字列。
署名する必要があるパラメーターをアルファベット順にソートします。等号（=）を使用して、各パラメーターのキーと値を連結します。アンパサンド（&）を使用してパラメーターを連結します。
IoT Platform インスタンスが属する Alibaba Cloud アカウント、または Alibaba Cloud アカウント内で必要な権限を直接付与されている RAM ユーザーを使用する場合：
署名する必要があるパラメーターには、
authIdとtimestampが含まれます。stringToSign = authId=${accessKey}×tamp=1573489088171形式で値を設定します。RAM ロールによって承認された RAM ユーザーを使用する場合：
署名する必要があるパラメーターには、
securityToken、authId、timestampが含まれます。stringToSign = authId=${accessKey}&securityToken=${SecurityToken}×tamp=1573489088171形式で値を設定します。
accessSecret
はい
IoT Platform インスタンスが属する Alibaba Cloud アカウント、または Alibaba Cloud アカウント内で必要な権限を直接付与されている RAM ユーザーを使用する場合：
このパラメーターを Alibaba Cloud アカウントの AccessKey シークレットまたは RAM ユーザーの AccessKey シークレットに設定します。
IoT Platform コンソールにログインし、ポインターをプロファイル画像の上に移動して、[accesskey 管理] をクリックします。表示されるページで、AccessKey シークレットを取得します。
RAM ロールによって承認された RAM ユーザーを使用する場合：
このパラメーターを、RAM ロールを引き受ける RAM ユーザーの AccessKey シークレットに設定します。
IoT Platform によってプッシュされたメッセージを受信する
AMQP クライアントと IoT Platform の間にレシーバーリンクが確立されると、IoT Platform はリンクを介してクライアントにメッセージをプッシュします。
クライアントは、サブスクリプションで指定されたタイプのメッセージのみを受信できます。デバイスにメッセージまたはコマンドを送信する場合は、ビジネス要件に基づいて対応する操作を呼び出します。詳細については、「関数別の操作リスト」をご参照ください。
IoT Platform によってクライアントにプッシュされる各メッセージは、次の部分で構成されています。
メッセージ本文。メッセージのペイロードはバイナリ形式です。
トピックやメッセージ ID などのメッセージ属性。属性は、AMQP で定義されている application-properties セクションから取得できます。属性は、
key:value形式です。キー
説明
topic
メッセージのトピック。
messageId
メッセージの ID。
generateTime
メッセージが生成された時刻。
説明generateTime パラメーターに基づいてメッセージの順序を判断することはできません。
メッセージの受信：
AMQP クライアントは、メッセージが受信されたことを IoT Platform に通知するために、IoT Platform に受信確認を送信します。受信確認は、手動または自動で送信できます。自動モードを使用することをお勧めします。詳細については、クライアントのユーザーガイドをご参照ください。
メッセージングポリシー：
メッセージはリアルタイムでプッシュされます。
メッセージは蓄積されます。
特定の問題により、メッセージがリアルタイムで消費されない場合があります。たとえば、コンシューマーが IoT Platform から切断された場合、またはメッセージが低速で消費された場合、メッセージはこれらの場合に蓄積されます。
切断されたコンシューマーが IoT Platform に再接続し、安定した速度でメッセージの消費を開始すると、IoT Platform は蓄積されたメッセージをコンシューマーにプッシュします。
コンシューマーがプッシュされたメッセージを消費できない場合、蓄積されたメッセージが存在するキューがブロックされる可能性があります。メッセージが消費されない場合、IoT Platform は約 1 分後に蓄積されたメッセージをコンシューマーにプッシュしようと再試行します。
コンシューマーが処理するトラフィック量は、短期間に変動する可能性があります。ほとんどの場合、変動は 10 分以内に解消されます。 クエリ/秒（QPS）の数が多い場合、またはメッセージ処理でリソースが消費される場合は、コンシューマーの数を増やすことをお勧めします。これにより、メッセージ消費において許容レベルの冗長性を維持できます。
IoT Platform がメッセージを転送する場合、クライアントが ACK メッセージを返すか、メッセージの有効期限が切れるまで、メッセージが繰り返し送信される場合があります。複数のメッセージが同じメッセージ ID を使用する場合、ID に基づいてメッセージを重複排除できます。
メッセージングの制限の詳細については、「サーバー側サブスクリプションの制限」をご参照ください。
IoT Platform コンソールで蓄積されたメッセージをクリアできます。詳細については、「コンシューマーグループの管理」トピックの コンシューマーグループの表示と監視 セクションをご参照ください。
メッセージの順序付け：
メッセージの順序は保証されません。したがって、メッセージが生成された時刻までに、メッセージが順番に受信されない場合があります。
アップストリームおよびダウンストリームデバイスメッセージ：
返されるメッセージは時間順にソートされていません。メッセージを手動でソートする必要があります。
たとえば、次のメッセージを順番に受信したとします。
オンライン時間：2018-08-31 10:02:28.195
オフライン時間：2018-08-31 10:01:28.195
オフライン時間：2018-08-31 10:03:28.195
上記のメッセージは、デバイスが切断され、再接続され、再び切断されたことを示しています。
メッセージのパラメーターの詳細については、「データ形式」をご参照ください。
その他の種類のメッセージ：
アプリケーション層の各メッセージにシーケンス番号を追加する必要があります。受信したメッセージのシーケンス番号に基づいて、IoT Platform は冪等アルゴリズムを使用して、メッセージを処理する必要があるかどうかを確認します。
例
次のプログラミング言語固有の AMQP SDK のいずれかを使用して、クライアントを IoT Platform に接続できます。パラメーターの構成方法の詳細については、このトピックの 接続設定 セクションをご参照ください。
IoT Platform によって提供される AMQP SDK を使用することをお勧めします。Alibaba Cloud は、独自開発の AMQP SDK のテクニカルサポートを提供していません。
クライアントを IoT Platform に接続すると、メッセージ関連のエラーコードを受信する場合があります。詳細については、「IoT プラットフォームログ」トピックの メッセージに関連するエラーコード セクションをご参照ください。