AWS IoT のルール

ルールを使用すると、AWS サービスとやり取りする権限をデバイスに許可できます。ルールの分析とアクションの実行は、MQTT トピックストリームに基づいて行われます。ルールを使用すると、次のようなタスクをサポートできます。

デバイスから受け取ったデータの加工またはフィルタ処理を行う。
デバイスから受け取ったデータを Amazon DynamoDB データベースに書き込む。
ファイルを Amazon S3 に保存する。
Amazon SNS を使用して、すべてのユーザーにプッシュ通知を送信する。
Amazon SQS キューにデータを発行する。
Lambda 関数を呼び出してデータを抽出する。
Amazon Kinesis を使用してデバイスからの多数のメッセージを処理する。
データを Amazon Elasticsearch Service に送信する。
CloudWatch メトリクスを取得する。
CloudWatch アラームを変更する。
MQTT メッセージから Amazon Machine Learning にデータを送信して、Amazon ML モデルに基づいて予測を行う。
Salesforce の IoT 入力ストリームにメッセージを送信します。
AWS IoT Analytics チャネルにメッセージデータを送信します。
Step Functions ステートマシンの実行を開始します。

AWS IoT がアクションを実行できるようにするには、AWS リソースにアクセスする権限をあらかじめ許可しておく必要があります。アクションが実行されると、使用している AWS サービスの標準料金が発生します。

AWS IoT への必要なアクセス権限の付与
ロールのアクセス権限の適用
AWS IoT ルールを作成する
ルールの表示
SQL バージョン
ルールのトラブルシューティング
ルールエラー処理
ルールの削除
AWS IoT ルールアクション
AWS IoT SQL リファレンス

AWS IoT への必要なアクセス権限の付与

各ルールからアクセスできる AWS リソースを制御するには、IAM ロールを使用します。ルールを作成するには、必要な AWS リソースへのアクセスを許可するポリシーを指定した IAM ロールをあらかじめ作成しておく必要があります。AWS IoT では、ルールの実行時にこのロールが適用されます。

IAM ロール (AWS CLI) を作成するには

次の信頼ポリシードキュメントを iot-role-trust.json というファイルに保存します。このポリシーでは、ロールを適用する権限が AWS IoT に許可されます。


{
    "Version":"2012-10-17",
    "Statement":[{
        "Effect": "Allow",
        "Principal": {
            "Service": "iot.amazonaws.com"
        },
        "Action": "sts:AssumeRole"
    }]
}

create-role コマンドを使用し、iot-role-trust.json ファイルを指定して IAM ロールを作成します。


aws iam create-role --role-name my-iot-role --assume-role-policy-document file://iot-role-trust.json

このコマンドの出力は以下のようになります。


{
  "Role": {
      "AssumeRolePolicyDocument": "url-encoded-json",
      "RoleId": "AKIAIOSFODNN7EXAMPLE",
      "CreateDate": "2015-09-30T18:43:32.821Z",
      "RoleName": "my-iot-role",
      "Path": "/",
      "Arn": "arn:aws:iam::123456789012:role/my-iot-role"
  }
}

次の JSON を iot-policy.json というファイルに保存します。
```
{
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Action": "dynamodb:*",
        "Resource": "*"
    }]
}
```
この JSON は、AWS IoT への管理者アクセス権限を DynamoDB に付与するポリシードキュメントの例です。

ロールの適用後、AWS リソースへのアクセス権限を AWS IoT に付与するには、iot-policy.json ファイルを指定して create-policy コマンドを使用します。
```
aws iam create-policy --policy-name my-iot-policy --policy-document file://my-iot-policy.json
```
AWS IoT のポリシーで AWS サービスへのアクセスを許可する方法については、「AWS IoT ルールを作成する」を参照してください。

create-policy コマンドの出力には、ポリシーの ARN が含められます。このポリシーをロールにアタッチする必要があります。
```
{
    "Policy": {
        "PolicyName": "my-iot-policy",
        "CreateDate": "2015-09-30T19:31:18.620Z",
        "AttachmentCount": 0,
        "IsAttachable": true,
        "PolicyId": "ZXR6A36LTYANPAI7NJ5UV",
        "DefaultVersionId": "v1",
        "Path": "/",
        "Arn": "arn:aws:iam::123456789012:policy/my-iot-policy",
        "UpdateDate": "2015-09-30T19:31:18.620Z"
    }
}
```

ポリシーをロールにアタッチするには、attach-role-policy コマンドを使用します。


aws iam attach-role-policy --role-name my-iot-role --policy-arn "arn:aws:iam::123456789012:policy/my-iot-policy"

ロールのアクセス権限の適用

ルール定義の一部として、ルールのアクションで指定されたリソースにアクセスする権限を付与する IAM ロールがあります。ルールエンジンは、ルールのアクションがトリガーされたときに、そのロールを引き受けます。ロールは、ルールと同じ AWS アカウントで定義する必要があります。

ルールを作成または置き換えるときに、実質的にロールをルールエンジンに渡します。このオペレーションを実行するユーザーには、iam:PassRole アクセス権限が必要です。このアクセス権限を確保するには、iam:PassRole アクセス権限を付与し、それを IAM ユーザーにアタッチするポリシーを作成します。次のポリシーは、ロールに iam:PassRole 権限を付与する方法を示しています。


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Stmt1",
            "Effect": "Allow",
            "Action": [
                "iam:PassRole"
            ],
            "Resource": [
                "arn:aws:iam::123456789012:role/myRole"
            ]
        }
    ]
}

このポリシー例では、ロール iam:PassRole に myRole アクセス権限を付与します。ロールは、ロールの ARN を使用して指定されています。IAM ユーザーまたはユーザーに対応するロールに、このポリシーをアタッチする必要があります。詳細については、「管理ポリシーの使用」を参照してください。

注記

Lambda 関数ではリソースベースのポリシーが使用され、ポリシーが Lambda 関数自体に直接アタッチされます。Lambda 関数を呼び出すルールを作成する場合は、ロールを適用しないため、ルールを作成するユーザーに iam:PassRole アクセス権限は必要ありません。Lambda 関数の認証については、「リソースポリシーを使用したアクセス権限の付与」を参照してください。

AWS IoT ルールを作成する

接続されているモノからのデータをルーティングするためのルールを設定できます。ルールには、次の内容が含まれます。

ルール名: ルールの名前。
説明 (オプション): ルールに関してテキストで示された説明。
SQL ステートメント: MQTT トピックで受け取ったメッセージをフィルタ処理し、別の場所にデータを送るための単純な SQL 構文。詳細については、「AWS IoT SQL リファレンス」を参照してください。
SQL のバージョン: ルールを評価する際に使用する SQL ルールエンジンのバージョン。このプロパティはオプションですが、SQL バージョンを指定することを強くお勧めします。このプロパティが設定されていない場合、デフォルトでは、2015-10-08 が使用されます。
1 つ以上のアクション: ルールの実行時に AWS IoT によって行われるアクション。たとえば、データを DynamoDB テーブルに挿入する、データを Amazon S3 バケットに書き込む、Amazon SNS トピックに発行する、Lambda 関数を呼び出すなどのアクションを指定できます。
エラーアクション: アクション AWS IoT は、ルールのアクションを実行できないときに実行されます。

ルールを作成する際には、トピックに対して公開されるデータの量に注意してください。ワイルドカードのトピックパターンが含まれるルールを作成すると、一致するメッセージの割合が大きくなる可能性があるため、場合によってはターゲットアクションに使用する AWS リソースの容量を増やす必要があります。また、ワイルドカードのトピックパターンが含まれる再発行ルールを作成すると、循環ルールが作成され、無限ループが発生する可能性があります。

注記

ルールの作成と更新は、管理者レベルの操作です。ルールを作成または更新するアクセス権限のあるユーザーは、そのルールで処理されたデータにもアクセスできます。

ルール (AWS CLI) を作成するには

ルールを作成するには、create-topic-rule コマンドを使用します。


aws iot create-topic-rule --rule-name my-rule --topic-rule-payload file://my-rule.json

以下のペイロードファイル例では、iot/test トピックに送信されたすべてのメッセージを指定の DynamoDB テーブルに挿入するルールが指定されています。SQL ステートメントでメッセージがフィルタ処理され、ロールの ARN によって AWS IoT テーブルへの書き込みアクセス権限が DynamoDB に付与されています。


{
  "sql": "SELECT * FROM 'iot/test'",
  "ruleDisabled": false,
  "awsIotSqlVersion": "2016-03-23",
  "actions": [{
      "dynamoDB": {
          "tableName": "my-dynamodb-table",
          "roleArn": "arn:aws:iam::123456789012:role/my-iot-role",
          "hashKeyField": "topic",
          "hashKeyValue": "${topic(2)}",
          "rangeKeyField": "timestamp",
          "rangeKeyValue": "${timestamp()}"
      }
  }]
}

以下のペイロードファイル例では、iot/test トピックに送信されたすべてのメッセージを指定の S3 バケットに挿入するルールが指定されています。SQL ステートメントでメッセージがフィルタ処理され、ロールの ARN によって AWS IoT バケットへの書き込みアクセス権限が Amazon S3 に付与されています。


{
    "awsIotSqlVersion": "2016-03-23",
    "sql": "SELECT * FROM 'iot/test'",
    "ruleDisabled": false,
    "actions": [
    {
        "s3": {
            "roleArn": "arn:aws:iam::123456789012:role/aws_iot_s3",
            "bucketName": "my-bucket",
            "key": "myS3Key"
        }
    }
    ]
}

以下のペイロードファイル例では、データを Amazon ES にプッシュするルールが指定されています。


{
   "sql":"SELECT *, timestamp() as timestamp FROM 'iot/test'",
   "ruleDisabled":false,
  "awsIotSqlVersion": "2016-03-23",
    "actions":[
      {
        "elasticsearch":{
          "roleArn":"arn:aws:iam::123456789012:role/aws_iot_es",
          "endpoint":"https://my-endpoint",
         "index":"my-index",
          "type":"my-type",
          "id":"${newuuid()}"
        }
      }
    ]
}

以下のペイロードファイル例では、Lambda 関数を呼び出すルールが指定されています。


{
  "sql": "expression",
  "ruleDisabled": false,
  "awsIotSqlVersion": "2016-03-23",
  "actions": [{
      "lambda": {
          "functionArn": "arn:aws:lambda:us-west-2:123456789012:function:my-lambda-function"
      }
  }]
}

以下のペイロードファイル例では、Amazon SNS トピックに発行するルールが指定されています。


{
  "sql": "expression",
  "ruleDisabled": false,
  "awsIotSqlVersion": "2016-03-23",
  "actions": [{
      "sns": {
          "targetArn": "arn:aws:sns:us-west-2:123456789012:my-sns-topic",
          "roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
      }
  }]
}

以下のペイロードファイル例では、別の MQTT トピックに再発行するルールが指定されています。


{
  "sql": "expression",
  "ruleDisabled": false,
  "awsIotSqlVersion": "2016-03-23",
  "actions": [{
      "republish": {
          "topic": "my-mqtt-topic",
          "roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
      }
  }]
}

以下のペイロードファイル例では、データを Amazon Kinesis Data Firehose ストリームにプッシュするルールが指定されています。


{
    "sql": "SELECT * FROM 'my-topic'",
    "ruleDisabled": false,
  "awsIotSqlVersion": "2016-03-23",
    "actions": [{
        "firehose": {
            "roleArn": ""arn:aws:iam::123456789012:role/my-iot-role",
            "deliveryStreamName": "my-stream-name"
        }
    }]
}

以下のペイロードファイル例では、MQTT ペイロード内のデータが 1 として分類されると Amazon Machine Learning の machinelearning_predict 関数を使用してトピックに再発行するルールが指定されています。


{
    "sql": "SELECT * FROM 'iot/test' where machinelearning_predict('my-model', 'arn:aws:iam::123456789012:role/my-iot-aml-role', *).predictedLabel=1",
    "ruleDisabled": false,
  "awsIotSqlVersion": "2016-03-23",
    "actions": [{
        "republish": {
            "roleArn": "arn:aws:iam::123456789012:role/my-iot-role",
            "topic": "my-mqtt-topic"
        }
    }]
}

以下は、Salesforce IoT クラウド入力ストリームにメッセージを発行するルールを持つペイロードファイルの例です。


{
    "sql": "expression",
    "ruleDisabled": false,
    "awsIotSqlVersion": "2016-03-23",
    "actions": [{
        "salesforce": {
            "token": "ABCDEFGHI123456789abcdefghi123456789",
            "url": "https://ingestion-cluster-id.my-env.sfdcnow.com/streams/stream-id/connection-id/my-event"
        }
    }]
}

以下のペイロードファイル例では、Step Functions ステートマシンの実行を開始するルールが指定されています。


{
  "sql": "expression",
  "ruleDisabled": false,
  "awsIotSqlVersion": "2016-03-23",
  "actions": [{
      "stepFunctions": {
          "stateMachineName": "myCoolStateMachine",
          "executionNamePrefix": "coolRunning",
          "roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
      }
  }]
}

ルールの表示

ルールをリスト表示するには、list-topic-rules コマンドを使用します。


aws iot list-topic-rules

ルールに関する情報を取得するには、get-topic-rule コマンドを使用します。


aws iot get-topic-rule --rule-name my-rule

SQL バージョン

AWS IoT ルールエンジンは、SQL に似た構文を使用して、MQTT メッセージからデータを選択します。SQL ステートメントは、ルールが記述されている JSON ドキュメント内の awsIotSqlVersion プロパティで指定された SQL バージョンに基づいて解釈されます。JSON ルールドキュメントの構造については、「ルールの作成」を参照してください。awsIotSqlVersion プロパティを使用すると、使用する AWS IoT SQL ルールエンジンのバージョンを指定できます。新しいバージョンをデプロイした場合は、引き続き古いバージョンを使用することも、新しいバージョンを使用できるようにルールを変更することもできます。現在のルールでは、ルールの作成時のバージョンが引き続き使用されます。

以下の JSON 例は、awsIotSqlVersion プロパティを使用して SQL バージョンを指定する方法を示しています。


{
    "sql": "expression",
    "ruleDisabled": false,
    "awsIotSqlVersion": "2016-03-23",
    "actions": [{
        "republish": {
            "topic": "my-mqtt-topic",
            "roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
        }
     }]
}

現在サポートされているバージョンは次のとおりです。

2015-10-08: 2015 年 10 月 8 日にビルドされた元の SQL バージョン。
2016-03-23: 2016 年 3 月 23 日にビルドされた SQL バージョン。
beta: 最新のベータ SQL バージョン。このバージョンを使用する場合は、ルールへの変更が必要になる場合があります。

SQL ルールエンジン 2016-03-23 バージョンの最新情報

入れ子になっている JSON オブジェクトの選択が修正されました。
配列クエリに関する修正が行われました。
オブジェクト間でのクエリがサポートされるようになりました。
最上位レベルのオブジェクトとして配列を出力できるようになりました。
JSON または非 JSON 形式のデータに適用できる encode(value, encodingScheme) 関数が追加されました。

オブジェクト間のクエリ

この機能を使用すると、JSON オブジェクトの属性を照会できます。たとえば、次の MQTT メッセージの場合:


{ 
    "e": [
       { "n": "temperature", "u": "Cel", "t": 1234, "v":22.5 },
       { "n": "light", "u": "lm", "t": 1235, "v":135 },
       { "n": "acidity", "u": "pH", "t": 1235, "v":7 }
    ]
}

次のルールを使用します。


SELECT (SELECT v FROM e WHERE n = 'temperature') as temperature FROM 'my/topic'

この場合、ルールにより、次の出力が生成されます。


{"temperature": [{"v":22.5}]}

以下では、もう少し複雑なルールを指定して、同じ MQTT メッセージを使用しています。


SELECT get((SELECT v FROM e WHERE n = 'temperature'),1).v as temperature FROM 'topic'

この場合、ルールにより、次の出力が生成されます。


{"temperature":22.5}

最上位レベルのオブジェクトとして `Array` を出力する

この機能を使用すると、ルールから、最上位レベルのオブジェクトとして配列を返すことができます。たとえば、次の MQTT メッセージの場合:


{
    "a": {"b":"c"},
    "arr":[1,2,3,4]
}

次のルールを使用します。


SELECT VALUE arr FROM 'topic'

この場合、ルールにより、次の出力が生成されます。


[1,2,3,4]

Encode 関数

指定されたエンコードスキームに基づいて、ペイロード (非 JSON データの場合もある) を文字列表現にエンコードします。

ルールのトラブルシューティング

ルールに問題が発生した場合は、CloudWatch Logs を有効にすることをお勧めします。ログの分析によって、認証に関する問題かどうか、WHERE 句の条件に一致する結果が見つからない問題かどうかなどを判断できます。Amazon CloudWatch Logs の使用の詳細については、「CloudWatchLogs のセットアップ」を参照してください。

ルールエラー処理

AWS IoT がデバイスからメッセージを受信すると、ルールエンジンはそのメッセージがルールと一致するかどうかを確認します。その場合は、ルールの SQL ステートメントが評価され、ルールのアクションが呼び出され、SQL ステートメントの結果が渡されます。

アクションを呼び出すときに問題が発生した場合、ルールエンジンはエラーアクションを呼び出します (ルールにエラーアクションが指定されている場合)。これは、たとえば次のような場合に発生します。

ルールに Amazon S3 バケットにアクセスする権限がない。
ユーザーエラーにより、DynamoDB のプロビジョニングされたスループットを超える。

エラーアクションメッセージ形式

ルールとメッセージごとに 1 つのメッセージが生成されます。たとえば、同じルール内の 2 つのルールアクションが失敗した場合、エラーアクションは両方のエラーを含む 1 つのメッセージを受け取ります。

エラーアクションメッセージは次のようになります。


{
      "ruleName": "TestAction",
      "topic": "testme/action",
      "cloudwatchTraceId": "7e146a2c-95b5-6caf-98b9-50e3969734c7",
      "clientId": "iotconsole-1511213971966-0",
      "base64OriginalPayload": "ewogICJtZXNzYWdlIjogIkhlbGxvIHZyb20gQVdTIElvVCBjb25zb2xlIgp9",
      "failures": [
        {
          "failedAction": "S3Action",
          "failedResource": "us-east-1-s3-verify-user",
          "errorMessage": "Failed to put S3 object. The error received was The specified bucket does not exist (Service: Amazon S3; Status Code: 404; Error Code: NoSuchBucket; Request ID: 9DF5416B9B47B9AF; S3 Extended Request ID: yMah1cwPhqTH267QLPhTKeVPKJB8BO5ndBHzOmWtxLTM6uAvwYYuqieAKyb6qRPTxP1tHXCoR4Y=). Message arrived on: error/action, Action: s3, Bucket: us-east-1-s3-verify-user, Key: \"aaa\". Value of x-amz-id-2: yMah1cwPhqTH267QLPhTKeVPKJB8BO5ndBHzOmWtxLTM6uAvwYYuqieAKyb6qRPTxP1tHXCoR4Y="
        }
      ]
    }

ruleName

エラーアクションをトリガーしたルールの名前。

topic

元のメッセージが受信されたトピック。

cloudwatchTraceId

CloudWatch でエラーログを参照する一意の ID。

clientId

メッセージの発行元のクライアント ID。

base64OriginalPayload

base64 でエンコードされた元のメッセージペイロード。

エラー

failedAction: 完了に失敗したアクションの名前、たとえば「S3Action」。
failedResource: リソースの名前、たとえば S3 バケットの名前。
errorMessage: エラーの記述と説明。

エラーアクションの例

次に、エラーアクションが追加されたルールの例を示します。次のルールには、メッセージデータを DynamoDB テーブルに書き込むアクションと、Amazon S3 バケットにデータを書き込むエラーアクションがあります。


{
    "sql" : "SELECT * FROM ..."
    "actions" : [{ 
        "dynamoDB" : {
            "table" : "PoorlyConfiguredTable",
            "hashKeyField" : "AConstantString",
            "hashKeyValue" : "AHashKey"}}
    ],
    "errorAction" : { "s3" : {
            "roleArn": "arn:aws:iam::123456789012:role/aws_iot_s3",
            "bucket" : "message-processing-errors",
            "key" : "${replace(topic(), '/', '-') + '-' + timestamp() + '-' + newuuid()}"
    }}
}

外部関数を除き、エラーアクションの SQL ステートメントで任意の関数または置換を使用できます (例: get_thing_shadow、aws_lambda､machinelearning_predict など)。

ルールとエラーアクションを指定する方法の詳細については、「AWS IoT ルールの作成」を参照してください。

CloudWatch を使用してルールの成功または失敗を監視する方法の詳細については、「AWS IoT メトリクスとディメンション」を参照してください。

ルールの削除

不要になったルールは、削除することができます。

ルール (AWS CLI) を削除するには

delete-topic-rule コマンドを使用して、ルールを削除します。


aws iot delete-topic-rule --rule-name my-rule

ブラウザで JavaScript が無効になっているか、または使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。詳細については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

« 前次 »

AWS IoT のルール

AWS IoT への必要なアクセス権限の付与

ロールのアクセス権限の適用

AWS IoT ルールを作成する

ルールの表示

SQL バージョン

SQL ルールエンジン 2016-03-23 バージョンの最新情報

オブジェクト間のクエリ

最上位レベルのオブジェクトとして Array を出力する

Encode 関数

ルールのトラブルシューティング

ルールエラー処理

エラーアクションメッセージ形式

エラーアクションの例

ルールの削除

最上位レベルのオブジェクトとして `Array` を出力する