Amazon Web Services ブログ
IoT CoreからWebサービスに直接データをルーティング可能に
このブログでは、AWS IoT Core Rule EngineのHTTPアクションを使って任意のHTTPS エンドポイントへ追加コードなしもしくは変更してデータを送る方法を紹介します。この機能を使用すると、AWS IoTを独自のウェブサービスと統合できます。中間サービスの使用に伴う追加Latencyの発生や複雑さはありません。 この機能の詳細については、HTTPアクションのドキュメントを参照してください。 AWS IoTルールを初めて使用する場合は、このチュートリアルをご覧ください。
本ブログの前提:
- AWS IoTのコンソールにログイン可能もしくはAWS CLIがインストール済みであること
- あなたがすでに証明局(CA)により署名された確かな証明書が存在するHTTPSをもっていること
- HTTPSエンドポイントのログへアクセス可能もしくは、エンドポイントへ送ったメッセージを読むことができること
本ブログでは以下をウォークスルーします
- コンソールでトピックに基づくHTTPアクションルールを作成します
- コンソールでルールの宛先の確認と有効化
- HTTPアクションルールの作成をAWS CLIで実施
- 置換用のテンプレートを使わずにHTTPアクションを定義
- HTTPアクションのhaeaderと認証を定義
- ルールの宛先をAWS CLIを使って管理する
- 作成
- 確認
- 更新
- リスト
- 削除
始める準備はできてますか？
ウェブサービスがAWS IoTからデータを受信するには、最初に新しいHTTPアクションでトピックルールを作成する必要があります。 HTTPアクションは、アクションが実行されるたびに、指定されたHTTPSエンドポイントにメッセージペイロードとアクションで指定されたヘッダーをPOSTします。 HTTPS POSTを使用してエンドポイントからデータを取り込むことができるため、エンドポイントがAWS IoTと統合するためにコードを変更する必要はありません。
AWS コンソールでHTTPアクションを行うトピックルールの作成
この手順では、以下に示すHTTPアクションをAWSコンソールでの作り方の詳細になります。
1. AWS IoT コンソールのナビゲーションから Act -> Rulesを選択します。
2. ルールのページで Create を選択します
3. Create Ruleのページで、ルール名と説明を設定します
4. Ruleのquery statementで最新のバージョンをSQL version listから選択します。 rule queryには以下を記載します。
SELECT * FROM 'my/topic'この設定は my/topic にpublishで送られたメッセージのペイロードデータとして取り扱いそして、ルールアクションで関連付けられたサービスへペイロードデータを送信します。もしあなたが新しいルールのqueryを作成したい場合は、このSQLリファレンスを参照してください。
5. アクションの設定
6. アクションの選択ページで Send a message to a downstream HTTPS endpointを選択
ここで、HTTPSエンドポイントのURLを指定できます。 このアクションが実行されると、ルールエンジンはそのエンドポイントへのPOSTリクエストを作成し、アクションで指定されたヘッダーを追加し、SQLステートメントの評価後にリクエストボディにメッセージペイロードを追加します。
7. アクションの設定ページで、あなたが持っている存在するHTTPS Endpoint 情報を入力します。 例) https://www.example.com/ingest
8. アクションの追加を選択します
9. ルールの作成を選択
これで、AWS IoTの「my / topic」にpublishされたデータを取得してhttps://www.example.com/ingestに送信するトピックルールが作成されました。 このHTTP リクエスト適切に流れるように（かつ、Rules Engineによってブロックされないように）、エンドポイントを制御していることを最初に検証する必要があることに注意することが非常に重要です。
トピックルールの宛先のコンセプトの紹介
制御するエンドポイントにデータが送信されるようにするには、AWS IoTルールエンジンは、そのエンドポイントに送信されたデータにアクセスできることを確認する必要があります。エンドポイントを追跡するために、新しいAWS IoTトピックルールの宛先リソースが追加されます。 HTTPアクションでトピックルールを作成または更新すると、ルールエンジンは新しいトピックルールの宛先を作成しようとします。
トピックルールの宛先がHTTPアクション用に作成されると、ルールエンジンは指定されたエンドポイントにトークンでチャレンジメッセージを発行します。トークンを取得してそれをルールエンジンに送り返すことができれば、受信側のデータにアクセスできることを証明でき、確認プロセスが完了します。エンドポイントの確認は1回限りの操作です。確認して有効にすると、追加の確認なしで同じエンドポイントを複数のルールに使用できます。
トークンは3日間有効です。その後、新しいHTTPアクションを作成するか、トピックルールの宛先の更新セクションの手順に従って確認プロセスを再開する必要があります。詳細については、HTTPアクション宛先の使用に関するドキュメントを参照してください。
AWSコンソール操作でのトピックルールの宛先確認と有効化
以下の手順で、AWS IoTのコンソールから確認と有効化の方法を示します。
1. AWS IoTのコンソールのナビゲーションペインから、Act-> Destinationsを選択します
2. 宛先リストから対象を選択します。この例では https://wwww.examle.com/ingest を選択します。
3. 宛先の詳細画面から、Actions-> confirm and Enableを選択します。
選択したエンドポイントのダイアログが表示されます。
確認用のTokenの処理が要求されます。宛先が作成されると、ルールエンジンがチャレンジメッセージをあなたのエンドポイントに発行します。このメッセージは確認用のTokenを内包しており、そのフォーマットは以下となります。
HTTP POST {confirmationUrl}/?confirmationToken={confirmationToken}
Headers:
x-amz-rules-engine-message-type: DestinationConfirmation
x-amz-rules-engine-destination-arn: <Destination ARN>
Content-Type: application/json
...
Body:
{
"arn": <ARN for the destination that needs to be confirmed>,
"confirmationToken": <Confirmation Token, same as {confirmationToken} in URL>,
"enableUrl": <Callback URL to complete the confirmation. Make HTTP GET request to this URL to finish confirmation>,
"messageType": "DestinationConfirmation"
}
そのエンドポイントをコントロールする場合、confirmationToken URIクエリを使用してそのリソースへのPOSTリクエストのサービスログを検索し、そのトークン値を抽出して、AWS IoTコンソールに貼り付けることができます。
Tips：サーバーでこのエンドポイントのURI Query（cs-uri-query）W3Cロギングフィールドを有効にしてください。そうしないと、confirmationTokenを含むクエリパラメーターがフィルターで除外されます。
4. 宛先確認のダイアログに {確認用Token}を入力してください
5. 確認と有効を選択します
この時点で、Tokenが正しい場合、エンドポイントの宛先エントリは有効と表示されます。 AWS IoT Rules Engineは、ルールがトリガーされるたびにそのエンドポイントにデータを送信します。
本ブログにかかれている内容についての注意点
- HTTPアクションは、公的な認証局（CA）によって署名された有効な証明書を持つHTTPSエンドポイントへのPOSTのみをサポートします。
- HTTPアクションは port番号 443と8443のみをサポートします。
- HTTPアクション 3秒で処理が完了しないとタイムアウトします。(リトライも含む)
- HTTPアクションには標準的なEC2のデータ転送料金が適用されます
最新のlimitなどの制限については、AWS IoT limitのページを参照ください
AWS CLIを用いてHTTPアクションを作成する
AWS CLIを用いてHTTPアクションのトピックルールを作成、管理することができます。以下のコマンドでルールの作成ができます。
aws iot create-topic-rule --rule-name test_http_action --topic-rule-payload file://<path/to/your/file.json> --region <your_region>
topic-rule-payloadには、トピックルールとそれに関連付けられたアクションを記述します。 topic-rule-payloadの例を以下に示します。
topic-rule-payloadを作成する場合、Webサービスがメッセージを受信できるHTTPエンドポイントであるurlを指定する必要があります。 urlは置換テンプレートをサポートしています。 URLを構成する方法は多数あり、それぞれに独自のルールがあります。 topic-rule-payloadでこのエンドポイントを定義する方法を説明するために、以下の5つの例を作成しました。
HTTPアクション定義
例1 ) ハードコーディング
{
"actions": [
{
"http": {
"url": "https://www.example.com"
}
}
],
"sql": "select * from 'a/b'",
"awsIotSqlVersion": "2016-03-23",
"ruleDisabled": false
}この例において、urlはハードコーディングされています。置換テンプレートを利用していないことを意味します。一度このアクションが追加されると、ルールエンジンは、https：//www.example.com URLのトピックルールの宛先を自動的に作成し、そのURLにチャレンジを発行します。 チャレンジに応答してURLを確認して有効にすると、ルールエンジンはそのエンドポイントにデータを配信します。 この場合、url値から推測できるため、confirmationUrlは必要ありません。 これは、urlに置換テンプレートがない場合にのみ可能です。
例2) sub-pathまたはquery パラメータとハードコーディングを併用
{
"actions": [
{
"http": {
"url": "https://www.example.com/subpath?myqueryparams=staticdata",
"confirmationUrl": "https://www.example.com"
}
}
],
"sql": "select * from 'a/b'",
"awsIotSqlVersion": "2016-03-23",
"ruleDisabled": false
}このオプションはオプション1と似ていますが、確認用（ベース）URLを指定することもできます。 confirmUrlを使用して、確認チャレンジの宛先であるトピックルールの宛先を作成します。 メッセージペイロードが配信されるURLのプレフィックスである必要があります。 confirmUrlを確認して有効にすると、ベースURL（https://www.example.com）とすべてのsub-path/queryパラメーターがすべてのルールで許可されます。
例3) 動的なエンドポイントをハードコーディング
{
"actions": [
{
"http": {
"url": "https://www.example.com/${clientid()}/data",
"confirmationUrl": "https://www.example.com"
}
}
],
"sql": "select * from 'a/b'",
"awsIotSqlVersion": "2016-03-23",
"ruleDisabled": false
}この例の場合、urlはメッセージが処理されるまで決定されないため、confirmationUrlが必要です。 confirmUrlを有効にすると、Rules Engineはhttps://www.example.comだけでなく、この宛先のsub-path/queryパラメーターにデータを送信できます。 宛先が有効になっていない場合、このアクションを作成すると、confirmationUrlに基づいてトピックルールの宛先が自動的に作成されます。 Rules EngineがURLにメッセージを送信する前に、その宛先を有効にする必要があります。
例4) 動的なエンドポイントを動的なドメイン名で記述
{
"actions": [
{
"http": {
"url": "https://${value_from_payload}.example.com/${clientid()}/data",
"confirmationUrl": "https://${value_from_payload}.example.com"
}
}
],
"sql": "select * from 'a/b'",
"awsIotSqlVersion": "2016-03-23",
"ruleDisabled": false
}これは最も複雑なシナリオです。これは、メッセージが評価されるまでurlとconfirmUrlの両方がわからないためです。このような場合、ルールエンジンは、ルールの作成時にトピックルールの宛先を自動的に作成しません。ルールエンジンには2つの要件があります。
置換テンプレート（$ {value_from_payload}）を含むconfirmUrlは、urlのプレフィックスである必要があります。そして、
お客様は、置換後、confirmationUrlのすべての可能なトピックルール宛先を手動で作成、確認、有効化する必要があります。
上記の例では、confirmationUrlはurlのプレフィックスであるため、ルールは正常に作成されます。 $ {value_from_payload}が可能な値のセット（「test」、「prod」、「beta」）であるとします。次のconfirmationUrlの値（https：//test.example.com、https：//prod.example.com、https：//beta.example.com）に対して、トピックルールの宛先を手動で作成して有効にする必要があります。 AWS CLIを使用してトピックルールの宛先を作成する方法については、以下のトピックルールの宛先を手動で作成するセクションを参照してください。
メッセージが評価されると、Rules Engineは、置換後のconfirmUrlが確認され、有効になっているかどうかを確認します。したがって、$ {value_from_payload}が「beta」に置き換えられると、Rules Engineはhttps://beta.example.comの宛先が確認済みであり、https：//beta.example.com/123456789012/にデータを送信する前に有効になっているかどうかを確認します。
例5) 完全に動的なエンドポイント
{
"actions": [
{
"http": {
"url": "${full_control_from_payload}",
"confirmationUrl": "${full_control_from_payload}"
}
}
],
"sql": "select * from 'a/b'",
"awsIotSqlVersion": "2016-03-23",
"ruleDisabled": false
}この例は、例4に非常に似ています。confirmationUrlの値はurlのプレフィックスである必要があり、置換後、confirmationUrlのすべての可能な宛先を手動で作成、確認、有効化する必要があります。 さらに、Rules Engineは、データがポート443（デフォルト）または8443でHTTPSエンドポイントをターゲットにしていることを確認します。
次に、HTTPアクションにヘッダーを追加する方法を見てみましょう。
HTTPアクションのHeader定義
Header情報はkey-valueのペアとして各HTTPアクションに100個まで登録することができます。注意事項として、Valueフィールドは置換テンプレートでのみサポートされ、また、特定のヘッダーはデフォルトで暗黙的に定義されています（Content-Type、User-Agentなど）。ヘッダーのキーと値のペアを使用して、Content-Typeヘッダーを上書きできます。
{
"actions": [
{
"http": {
"url": "https://www.example.com",
"headers": [
{
"key": "static_header_key",
"value": "static_header_value"
},
{
"key": "substitutable_header_key",
"value": "${value_from_payload}"
}
]
}
}
],
"sql": "select * from 'a/b'",
"awsIotSqlVersion": "2016-03-23",
"ruleDisabled": false
}HTTPアクションの認証定義
HTTPアクションはベーシック認証やAPIKeyのような認証方法をサポートしています。以下の例は、HTTPヘッダーとクエリパラメーターを使用してこれらの認証方法を構成する方法を示しています。
ベーシック認証の定義
{
"actions": [
{
"http": {
"url": "https://www.example.com",
"headers": [
{
"key": "Authorization",
"value": "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
}
]
}
}
],
"sql": "select * from 'a/b'",
"awsIotSqlVersion": "2016-03-23",
"ruleDisabled": false
}HTTPのベーシック認証のスキームはInternet Engineering Task Force(IETF)により定義されています。このHTTPアクションはHTTP Postリクエストのheaderとして構築されます。
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==API Keyベースの認証定義
{
"actions": [
{
"http": {
"url": "https://www.example.com/something?api_key=abcd1234",
"confirmationUrl": "https://www.example.com"
}
}
],
"sql": "select * from 'a/b'",
"awsIotSqlVersion": "2016-03-23",
"ruleDisabled": false
}この例では、エンドポイントはAPIキークエリパラメーターを使用して認証します。 ターゲットサービスの実装に応じて、クエリパラメータまたはヘッダーを使用してAPIキーを指定できます。
AWS CLIを使ってのトピックルールの宛先管理
このセクションでは、トピックルールの宛先をどのように作り、確認、更新、リスト、削除するのかを説明します。
手動でのトピックルールの宛先作成
aws iot create-topic-rule-destination --destination-configuration '{"httpUrlConfiguration": {"confirmationUrl": "https://www.example.com"}}' --region <your_region>
このコマンドは、新しいトピックルールの宛先を作成し、https：//www.example.comに確認用のチャレンジを発行します。 トピックルールの送信先ステータスは、確認待ちのステータス理由を含むIN_PROGRESSになります。 確認が3日以内に完了しない場合、状態はERRORに移行します。
HTTPアクションのconfirmUrlに置換テンプレートが含まれている場合、このコマンドラインを使用して、トピックルールの宛先を手動で作成する必要があります。
トピックルールの宛先確認
aws iot confirm-topic-rule-destination --confirmation-token 'confirmationToken' --region <your_region>
確認メッセージから確認トークンを取得したら、上記のコマンドラインを使用して、対応するトピックルールの宛先を確認できます。
セキュリティ上の理由から、確認後、トピックルールの宛先はDISABLEDステータスになります。 Rules Engineがトラフィックをこの宛先に送信するには、update-topic-rule-destinationコマンドライン（下記を参照）またはコンソールで宛先を有効にする必要があります。
トピックルールの宛先の更新
aws iot update-topic-rule-destination --arn 'arn' --status 'ENABLED|DISABLED|IN_PROGRESS' --region <your_region>
このコマンドラインを使用して、トピックルールの宛先を有効または無効にしたり、新しい確認メッセージを宛先に再送信したりできます。 arnはトピックルールの宛先を識別するために使用され、list-topic-rule-destinationコマンドライン（以下を参照）またはコンソールでarnを受信できます。 statusは、宛先に必要な新しいステータス状態です。 ルールエンジンがこの宛先にトラフィックを送信するには、ステータスがENABLED状態になっている必要があります。
確認チャレンジメッセージを再送信するために、トピックルールの宛先ステータスをIN_PROGRESSに更新できます。 詳細については、UpdateTopicRuleDestination APIドキュメントを参照してください。
トピックルールの宛先をリストとして表示
aws iot list-topic-rule-destinations --max-results <value> --region <your_region>
このコマンドは指定したarnに含まれるトピックルールの宛先をリストします。
トピックルールの宛先削除
aws iot delete-topic-rule-destination --arn 'arn' --region <your_region>
上記コマンドにより、簡単にarn に紐づく宛先設定を削除することが可能です。
コードを1行も書かずに、AWS IoT Coreから独自のウェブサービスに直接データを送信して処理する準備はできていますか？ HTTPアクションは、AWS IoT Coreが利用可能なすべてのAWSリージョンで利用でき、この追加により、AWS IoT Coreは17のアクションタイプをサポートするようになりました。 詳細については、AWS IoTドキュメントを参照してください。
本文はこちら。翻訳はSAの小梁川が担当しました。