翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# のルール AWS IoT
ルールにより、デバイスは とやり取りできるようになります AWS のサービス。ルールの分析とアクションの実行は、MQTT トピックストリーミングに基づいて行われます。ルールを使用すると、次のようなタスクをサポートできます。
+ デバイスから受け取ったデータの加工またはフィルター処理を行う。
+ デバイスから受け取ったデータを Amazon DynamoDB データベースに書き込む。
+ Amazon S3 にファイルを保存します。
+ Amazon SNS を使用しているすべてのユーザーにプッシュ通知を送信します。
+ Amazon SQS キューにデータを発行します。
+ Lambda 関数を呼び出してデータを抽出する。
+ Amazon Kinesis を使用して、デバイスからの多数のメッセージを処理する。
+ Amazon OpenSearch Service にデータを送信します。
+ CloudWatch メトリクスを取得します。
+ CloudWatch アラームを変更します。
+ MQTT メッセージから Amazon SageMaker AI にデータを送信して、機械学習 (ML) モデルに基づいて予測を行います。
+ Salesforce の IoT 入力ストリーミングにメッセージを送信します。
+ Step Functions ステートマシンのプロセスを開始します。
+ メッセージデータを AWS IoT Events 入力に送信します。
+ AWS IoT SiteWiseでアセットプロパティにメッセージデータを送信します
+ ウェブアプリケーションまたはサービスにメッセージデータを送信します。
ルールには、[デバイス通信プロトコル](protocols.md) がサポートするパブリッシュ/サブスクライブプロトコルを通過する MQTT メッセージを使用できます。また、[基本的な取り込み](iot-basic-ingest.md)機能を使用して、[メッセージングコスト](https://aws.amazon.com/iot-core/pricing/)を発生させることなく、 AWS のサービス 前述の にデバイスデータを安全に送信することもできます。[基本的な取り込み](iot-basic-ingest.md)機能では、取り込みパスからパブリッシュ/サブスクライブのメッセージブローカーを除外することによってデータフローが最適化されます。これにより、 のセキュリティとデータ処理機能を維持しながら、コスト効率が向上します AWS IoT。
AWS IoT がこれらのアクションを実行する前に、ユーザーに代わって AWS リソースにアクセスするためのアクセス許可を付与する必要があります。アクションを実行すると、 AWS のサービス 使用する の標準料金が発生します。
**Topics**
+ [必要なアクセスを AWS IoT ルールに付与する](iot-create-role.md)
+ [ロールのアクセス許可の適用](pass-role.md)
+ [AWS IoT ルールの作成](iot-create-rule.md)
+ [AWS IoT ルールの管理](iot-managae-rule.md)
+ [AWS IoT ルールアクション](iot-rule-actions.md)
+ [ルールのトラブルシューティング](#iot-troubleshoot-rule)
+ [AWS IoT ルールを使用したクロスアカウントリソースへのアクセス](accessing-cross-account-resources-using-rules.md)
+ [エラー処理 (エラーアクション)](rule-error-handling.md)
+ [基本的な取り込みによるメッセージングコストの削減](iot-basic-ingest.md)
+ [AWS IoT SQL リファレンス](iot-sql-reference.md)
# 必要なアクセスを AWS IoT ルールに付与する
IAM ロールを使用して、各ルールがアクセスできる AWS リソースを制御します。ルールを作成する前に、必要な AWS リソースへのアクセスを許可するポリシーを持つ IAM ロールを作成する必要があります。 は、ルールを実装するときにこのロール AWS IoT を引き受けます。
**必要なアクセス () を AWS IoT ルールに付与する IAM ロールと AWS IoT ポリシーを作成するには、次の手順を実行しますAWS CLI。**
1. ロールを引き受ける AWS IoT アクセス許可を付与する次の信頼ポリシードキュメントを、 という名前のファイルに保存します`iot-role-trust.json`。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "123456789012"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:iot:us-east-1:123456789012:rule/rulename"
}
}
}
]
}
```
[create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) コマンドを使用し、`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"
}
}
```
1. 次の JSON を `my-iot-policy.json` という名前のファイルに保存します。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "dynamodb:*",
"Resource": "*"
}
]
}
```
この JSON は、DynamoDB への AWS IoT 管理者アクセスを許可するポリシードキュメントの例です。
[create-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/create-policy.html) コマンドを使用して、ロールを引き受けるときに AWS リソース AWS IoT へのアクセスを許可し、 `my-iot-policy.json` ファイルを渡します。
```
aws iam create-policy --policy-name my-iot-policy --policy-document file://my-iot-policy.json
```
のポリシー AWS のサービス で へのアクセスを許可する方法の詳細については AWS IoT、「」を参照してください[AWS IoT ルールの作成](iot-create-rule.md)。
[create-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/create-policy.html) コマンドの出力には、ポリシーの 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"
}
}
```
1. ポリシーをロールにアタッチするには、[attach-role-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/attach-role-policy.html) コマンドを使用します。
```
aws iam attach-role-policy --role-name my-iot-role --policy-arn "arn:aws:iam::123456789012:policy/my-iot-policy"
```
## ルールエンジンアクセスを取り消す
ルールエンジンへのアクセスを即時に取り消すには、次の手順を実行します。
1. [信頼ポリシー](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html)から iot.amazonaws.com を削除する
1. ステップに従って [iot ロールセッションを取り消す](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_revoke-sessions.html)
# ロールのアクセス許可の適用
ルール定義の一部として、ルールのアクションで指定されたリソースにアクセスする権限を付与する 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 ユーザーまたはユーザーが所属するロールにアタッチします。詳細については、「[管理ポリシーの使用](https://docs.aws.amazon.com/service-authorization/latest/reference/access_policies_managed-using.html)」を参照してください。
**注記**
Lambda 関数はリソースベースのポリシーを使用し、このポリシーは Lambda 関数自体に直接アタッチされます。Lambda 関数を呼び出すルールを作成する場合は、ロールを適用しないため、ルールを作成するユーザーに `iam:PassRole` アクセス許可は必要ありません。Lambda 関数の承認については、「[リソースポリシーを使用したアクセス許可の付与](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html#intro-permission-model-access-policy)」を参照してください。
# AWS IoT ルールの作成
接続されたモノからデータをルーティングして他の AWS サービスとやり取りする AWS IoT ルールを作成できます。 AWS IoT ルールは以下のコンポーネントで構成されます。
**ルールのコンポーネント**
| コンポーネント | 説明 | 必須またはオプション |
| --- | --- | --- |
| ルール名 | ルールの名前。ルールの名前に個人を特定できる名前や情報を使用することはお勧めしません。 | 必須。 |
| ルールの説明 | ルールのテキスト説明。ルールの説明に個人を特定できる名前や情報を使用することはお勧めしません。 | オプション。 |
| SQL ステートメント | MQTT トピックで受け取ったメッセージをフィルター処理し、別の場所にデータを送るための単純な SQL 構文。詳細については、「[AWS IoT SQL リファレンス](iot-sql-reference.md)」を参照してください。 | 必須。 |
| SQL バージョン | ルールを評価する際に使用する SQL ルールエンジンのバージョン。このプロパティはオプションですが、SQL バージョンを指定することを強くお勧めします。 AWS IoT Core コンソールは、このプロパティを`2016-03-23`デフォルトで に設定します。 AWS CLI コマンドや CloudFormation テンプレートなど、このプロパティが設定されていない場合`2015-10-08`は、 が使用されます。詳細については、「[SQL バージョン](iot-rule-sql-version.md)」を参照してください。 | 必須。 |
| 1 つ以上のアクション | アクションは、ルールを作成するときに AWS IoT 実行されます。例えば、データを DynamoDB テーブルに挿入する、データを Amazon S3 バケットに書き込む、Amazon SNS トピックに発行する、Lambda 関数を呼び出すなどのアクションを指定できます。 | 必須。 |
| エラーアクション | アクションは AWS IoT 、ルールのアクションを実行できない場合に実行されます。 | オプション。 |
AWS IoT ルールを作成する前に、必要な AWS リソースへのアクセスを許可するポリシーを持つ IAM ロールを作成する必要があります。 は、ルールを実装するときにこのロール AWS IoT を引き受けます。詳細については、[「必要なアクセス許可を AWS IoT ルールに付与する](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-role.html)」および[「ロールのアクセス許可を渡す](https://docs.aws.amazon.com//iot/latest/developerguide/pass-role.html)」を参照してください。
ルールを作成する際には、トピックに対して公開されるデータの量に注意してください。ワイルドカードのトピックパターンが含まれるルールを作成すると、一致するメッセージの割合が大きくなる可能性があります。この場合、場合によってはターゲットアクションに使用する AWS リソースの容量を増やす必要があります。処理の重複を防ぎ、コストを削減するために、再発行のルールでワイルドカードのトピックパターンを回避することをお勧めします。
**注記**
ルールの作成と更新は、管理者レベルのアクションです。ルールを作成または更新するアクセス権限のあるユーザーは、そのルールで処理されたデータにもアクセスできます。
## ルールを作成する (コンソール)
**ルール (AWS マネジメントコンソール) を作成するには**
[AWS マネジメントコンソール](https://console.aws.amazon.com//iot/home#/home) コマンドを使用してルールを作成します。
1. [AWS IoT コンソール](https://console.aws.amazon.com//iot/home#/home)を開きます。
1. 左側のナビゲーションで、**[管理]** セクションから **[メッセージルーティング]** を選択します。次に、**[ルール]** を選択します。
1. **[Rules]** (ルール) ページで、**[Create rule]** (ルールの作成) を選択します。
1. **[ルールのプロパティを指定]** ページで、ルールの名前を入力します。**[ルールの説明]** と **[タグ]** はオプションです。[**次へ**] を選択します。
1. **[SQL ステートメントを設定]** ページで、SQL バージョンを選択し、SQL ステートメントを入力します。例えば、SQL ステートメントには `SELECT temperature FROM 'iot/topic' WHERE temperature > 50` などがあります。詳細については、「[SQL バージョン](https://docs.aws.amazon.com//iot/latest/developerguide/iot-rule-sql-version.html)」と「[AWS IoT SQL リファレンス](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-reference.html)」を参照してください。
1. **ルールアクションのアタッチ**ページで、ルールアクションを追加してデータを他の AWS サービスにルーティングします。
1. **[ルールアクション]** で、ドロップダウンリストからルールアクションを選択します。例えば、**[Kinesis Stream]** を選択できます。ルールアクションの詳細については、「[AWS IoT ルールアクション](https://docs.aws.amazon.com//iot/latest/developerguide/iot-rule-actions.html)」を参照してください。
1. 選択したルールアクションに応じて、関連する設定の詳細を入力します。例えば、**[Kinesis Stream]** を選択した場合、データストリームリソースを選択または作成し、オプションで**パーティションキー**などの設定の詳細を入力する必要があります。パーティションキーは、スチーム内のシャード別にデータをグループ化するために使用されます。
1. **IAM ロール**で、エンドポイント AWS IoT へのアクセスを許可するロールを選択または作成します。 AWS IoT は、選択した IAM ロール`aws-iot-rule`の下に というプレフィックスを持つポリシーを自動的に作成します。**[表示]** を選択して、IAM コンソールから IAM ロールとポリシーを表示できます。**[エラーアクション]** はオプションです。詳細については、[[エラー処理 (エラーアクション)]](https://docs.aws.amazon.com//iot/latest/developerguide/rule-error-handling.html) を参照してください。ルールの IAM ロールの作成の詳細については、「[必要とするアクセスをルールに付与する](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-role.html)」を参照してください。[**次へ**] を選択します。
1. **[確認と作成]** ページで、すべての設定を確認し、必要に応じて編集します。**[作成]** を選択します。
ルールを正常に作成すると、**[ルール]** ページにそのルールが表示されます。ルールを選択して **[詳細]** ページを開き、ルールの表示、ルールの編集、ルールの無効化、ルールの削除を行うことができます。
## ルール (CLI) を作成する
**ルール (AWS CLI) を作成するには**
ルールを作成するには、[create-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html) コマンドを使用します。
```
aws iot create-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```
以下のペイロードファイル例では、`iot/test` トピックに送信されたすべてのメッセージを指定の DynamoDB テーブルに挿入するルールが指定されています。SQL ステートメントはメッセージをフィルタリングし、ロール ARN は DynamoDB テーブルに書き込む AWS IoT アクセス許可を付与します。
```
{
"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 は Amazon S3 バケットに書き込む AWS IoT アクセス許可を付与します。
```
{
"awsIotSqlVersion": "2016-03-23",
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"actions": [
{
"s3": {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_s3",
"bucketName": "amzn-s3-demo-bucket",
"key": "myS3Key"
}
}
]
}
```
以下のペイロードファイル例では、データを Amazon OpenSearch Service にプッシュするルールが指定されています。
```
{
"sql": "SELECT *, timestamp() as timestamp FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"OpenSearch": {
"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 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 SageMaker AI の `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"
}
}
]
}
```
# AWS IoT ルールの管理
AWS IoT ルールを管理するには、次のアクションを使用できます。
**Topics**
+ [ルールのタグ付け](#iot-create-rule-tagging)
+ [ルールの表示](#iot-view-rules)
+ [ルールの削除](#iot-delete-rule)
## ルールのタグ付け
新規のルールまたは既存のルールにさらに詳細性のレイヤーを追加するには、タグ付けを適用できます。タグ付けは、ルール内のキーと値のペアを活用して、 AWS IoT リソースとサービスにルールを適用する方法と場所をより細かく制御できます。例えば、プレリリーステスト (`Key=environment, Value=beta`) のために、ルールのスコープをベータ環境でのみ適用するように制限したり、特定のエンドポイントのみから `iot/test` トピックに送信されたすべてのメッセージをキャプチャして、Amazon S3 バケットに保存したりできます。
### IAM ポリシーの例
ルールのタグ付けのアクセス許可を付与する方法を示す例として、次のコマンドを実行してルールを作成し、タグ付けしてベータ環境にのみ適用する方法について考えてみましょう。
この例では、次のように置き換えます。
+ *MyTopicRuleName* をルールの名前に置き換えます。
+ *myrule.json* をポリシードキュメントの名前に置き換えます。
```
aws iot create-topic-rule
--rule-name MyTopicRuleName
--topic-rule-payload file://myrule.json
--tags "environment=beta"
```
この例では、次の IAM ポリシーを使用する必要があります。
****
```
{
"Version":"2012-10-17",
"Statement":
{
"Action": [ "iot:CreateTopicRule", "iot:TagResource" ],
"Effect": "Allow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:rule/MyTopicRuleName"
]
}
}
```
上の例は、ベータ環境にのみ適用される、`MyTopicRuleName` という新しく作成されたルールを示しています。`MyTopicRuleName` を明確に呼び出したポリシーステートメントの `iot:TagResource` により、`MyTopicRuleName` の作成時または更新時にタグ付けが可能になります。ルールの作成時にパラメータ `--tags "environment=beta"` を使用すると、`MyTopicRuleName` のスコープがベータ環境のみに制限されます。パラメータ `--tags "environment=beta"` を削除した場合、`MyTopicRuleName` はすべての環境に適用されます。
AWS IoT ルールに固有の IAM ロールとポリシーの作成に関する詳細については、「[必要なアクセスを AWS IoT ルールに付与する](iot-create-role.md)」を参照してください。
リソースのタグ付けの詳細については、「[AWS IoT リソースのタグ付け](tagging-iot.md)」を参照してください。
## ルールの表示
ルールをリスト表示するには、[list-topic-rules](https://docs.aws.amazon.com/cli/latest/reference/iot/list-topic-rules.html) コマンドを使用します。
```
aws iot list-topic-rules
```
ルールに関する情報を取得するには、[get-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/get-topic-rule.html) コマンドを使用します。
```
aws iot get-topic-rule --rule-name myrule
```
## ルールの削除
不要になったルールは、削除することができます。
**ルール (AWS CLI) を削除するには**
[delete-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-topic-rule.html) コマンドを使用して、ルールを削除します。
```
aws iot delete-topic-rule --rule-name myrule
```
# AWS IoT ルールアクション
AWS IoT ルールアクションは、ルールが呼び出されたときに何をするかを指定します。Amazon DynamoDB データベースへのデータの送信、Amazon Kinesis Data Streams へのデータの送信、 関数の AWS Lambda 呼び出しなどのアクションを定義できます。 は、アクションのサービス AWS リージョン が利用可能な で以下のアクション AWS IoT をサポートします。
| ルールアクション | 説明 | API での名前 |
| --- | --- | --- |
| [Apache Kafka](apache-kafka-rule-action.md) | Apache Kafka クラスターにメッセージを送信します。 | kafka |
| [CloudWatch アラーム](cloudwatch-alarms-rule-action.md) | Amazon CloudWatch アラームの状態を変更します。 | cloudwatchAlarm |
| [CloudWatch Logs](cloudwatch-logs-rule-action.md) | Amazon CloudWatch Logs にメッセージを送信します。 | cloudwatchLogs |
| [CloudWatch メトリクス](cloudwatch-metrics-rule-action.md) | CloudWatch メトリクスにメッセージを送信します。 | cloudwatchMetric |
| [DynamoDB](dynamodb-rule-action.md) | DynamoDB テーブルにメッセージを送信します。 | dynamoDB |
| [DynamoDBv2](dynamodb-v2-rule-action.md) | DynamoDB テーブル内の複数の列に、メッセージデータを送信します。 | dynamoDBv2 |
| [Elasticsearch](elasticsearch-rule-action.md) | OpenSearch エンドポイントにメッセージを送信します。 | OpenSearch |
| [HTTP](https-rule-action.md) | HTTPS エンドポイントに、メッセージをポストします。 | http |
| [AWS IoT Events](iotevents-rule-action.md) | AWS IoT Events 入力にメッセージを送信します。 | iotEvents |
| [AWS IoT SiteWise](iotsitewise-rule-action.md) | メッセージデータを AWS IoT SiteWise アセットプロパティに送信します。 | iotSiteWise |
| [Firehose](kinesis-firehose-rule-action.md) | Firehose 配信ストリーミングにメッセージを送信します。 | firehose |
| [Kinesis Data Streams](kinesis-rule-action.md) | Kinesis データストリーミングにメッセージを送信します。 | kinesis |
| [Lambda](lambda-rule-action.md) | メッセージデータを入力として Lambda 関数を呼び出します。 | lambda |
| [ロケーション](location-rule-action.md) | 位置データを Amazon Location Service に送信します。 | location |
| [OpenSearch](opensearch-rule-action.md) | Amazon OpenSearch Service エンドポイントにメッセージを送信します。 | OpenSearch |
| [再発行](republish-rule-action.md) | メッセージを別の MQTT トピックに再発行します。 | republish |
| [S3](s3-rule-action.md) | Amazon Simple Storage Service (Amazon S3) バケットにメッセージを保存します。 | s3 |
| [Salesforce IoT](salesforce-iot-rule-action.md) | Salesforce の IoT 入力ストリーミングにメッセージを送信します。 | salesforce |
| [SNS](sns-rule-action.md) | Amazon Simple Notification Service (Amazon SNS) プッシュ通知としてメッセージを発行します。 | sns |
| [SQS](sqs-rule-action.md) | Amazon Simple Queue Service (Amazon SQS) キューにメッセージを送信します。 | sqs |
| [ステップ関数](stepfunctions-rule-action.md) | AWS Step Functions ステートマシンを起動します。 | stepFunctions |
| [Timestream](timestream-rule-action.md) | Amazon Timestream データベーステーブルに、メッセージを送信します。 | timestream |
**注意事項**
ルールアクションがそのリソースとやり取りできるように、別のサービスのリソース AWS リージョン と同じ でルールを定義します。
断続的なエラーが発生した場合、 AWS IoT ルールエンジンはアクションの実行を複数回試みることがあります。すべての試行が失敗すると、メッセージは破棄され、CloudWatch ログにエラーが表示されます。障害が発生した後に呼び出される各ルールに対して、エラーアクションを指定できます。詳細については、「[エラー処理 (エラーアクション)](rule-error-handling.md)」を参照してください。
一部のルールアクションは、 AWS Key Management Service (AWS KMS) と統合されたサービスでアクションをアクティブ化して、保管時のデータ暗号化をサポートします。カスタマーマネージド AWS KMS key (KMS キー) を使用して保管中のデータを暗号化する場合、サービスには発信者に代わって KMS キーを使用するアクセス許可が必要です。カスタマーマネージド KMS キー許可を管理する方法については、該当するサービスガイドのデータ暗号化トピックを参照してください。カスタマーマネージド KMS キーの詳細については、[*AWS Key Management Service Developer Guide*](デベロッパーガイド)の「[AWS Key Management Service concepts](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html)」(コンセプト) を参照してください。
エラーアクションの SQL ステートメントでは、、[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda)、、[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb)、、[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data)、 などの外部[関数](iot-sql-functions.md)を含む任意の関数または[置換テンプレート](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html)を使用できます[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow)[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret)[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-machine-learning](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-machine-learning)[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64)。エラーアクションで外部関数を呼び出す必要がある場合、エラーアクションを呼び出すと、外部関数に追加の請求が発生する可能性があります。
# Apache Kafka
Apache Kafka (Kafka) アクションは、[Amazon Managed Streaming for Apache Kafka](https://docs.aws.amazon.com//msk/latest/developerguide/what-is-msk.html) (Amazon MSK)、[Confluent Cloud](https://www.confluent.io/) などのサードパーティープロバイダーによって管理される Apache Kafka クラスター、またはセルフマネージド Apache Kafka クラスターに直接メッセージを送信します。Kafka ルールアクションを使用すると、IoT データを Kafka クラスターにルーティングできます。これにより、ストリーミング分析、データ統合、視覚化、ミッションクリティカルなビジネス用途など、さまざまな目的で高性能データパイプラインを構築できます。
**注記**
このトピックでは、Apache Kafka プラットフォームおよび関連概念について精通していることを前提としています。Apache Kafka の詳細については、「[Apache Kafka](https://kafka.apache.org/)」を参照してください。[MSK Serverless](https://docs.aws.amazon.com//msk/latest/developerguide/serverless.html) はサポートされていません。MSK Serverless クラスターは、Apache Kafka ルールアクションが現在サポートしていない IAM 認証を介してのみ実行できます。Confluent AWS IoT Core で を設定する方法の詳細については、[「Confluent の活用」およびIoT デバイスとデータ管理の課題の解決 AWS](https://aws.amazon.com/blogs/apn/leveraging-confluent-and-aws-to-solve-iot-device-and-data-management-challenges/)」を参照してください。
## 要件
このルールアクションには、以下の要件があります。
+ が 、`ec2:CreateNetworkInterface`、`ec2:DescribeNetworkInterfaces`、、、`ec2:CreateNetworkInterfacePermission``ec2:DeleteNetworkInterface`、`ec2:DescribeVpcAttribute`、および `ec2:DescribeSecurityGroups`オペレーションを実行するために引き受け AWS IoT ることができる IAM `ec2:DescribeSubnets` `ec2:DescribeVpcs`ロール。このロールは、Kafka ブローカーに到達するために、Amazon Virtual Private Cloud への伸縮自在なネットワークインターフェイスを作成および管理します。詳細については、「[必要なアクセスを AWS IoT ルールに付与する](iot-create-role.md)」を参照してください。
AWS IoT コンソールで、このルールアクションを実行することを に許可 AWS IoT Core するロールを選択または作成できます。
ネットワークインターフェイスの詳細については、*Amazon EC2 ユーザーガイド*の「[Elastic Network Interface](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html)」を参照してください。
指定したロールにアタッチされるポリシーは次の例のようになります。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:CreateNetworkInterfacePermission",
"ec2:DeleteNetworkInterface",
"ec2:DescribeSubnets",
"ec2:DescribeVpcs",
"ec2:DescribeVpcAttribute",
"ec2:DescribeSecurityGroups"
],
"Resource": "*"
}
]
}
```
+ AWS Secrets Manager を使用して Kafka ブローカーへの接続に必要な認証情報を保存する場合は、 が `secretsmanager:GetSecretValue`および `secretsmanager:DescribeSecret`オペレーションを実行するために引き受け AWS IoT Core ることができる IAM ロールを作成する必要があります。
指定したロールにアタッチされるポリシーは次の例のようになります。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue",
"secretsmanager:DescribeSecret"
],
"Resource": [
"arn:aws:secretsmanager:us-east-1:123456789012:secret:kafka_client_truststore-*",
"arn:aws:secretsmanager:us-east-1:123456789012:secret:kafka_keytab-*"
]
}
]
}
```
+ Amazon Virtual Private Cloud (Amazon VPC) 内で Apache Kafka クラスターを実行できます。Apache Kafka Virtual Private Cloud (VPC) 送信先を作成し、サブネットで NAT ゲートウェイを使用して からパブリック Kafka クラスター AWS IoT にメッセージを転送する必要があります。 AWS IoT ルールエンジンは、送信先に記載されている各サブネットにネットワークインターフェイスを作成し、トラフィックを VPC に直接ルーティングします。送信先を指定すると、 AWS IoT ルールエンジンによって VPC ルールアクションが自動的に作成されます。VPC ルールアクションの詳細については、[Apache Kafka Virtual Private Cloud (VPC) の送信先](kafka-vpc-destination.md) を参照してください。
+ カスタマーマネージド AWS KMS key (KMS キー) を使用して保管中のデータを暗号化する場合、サービスには発信者に代わって KMS キーを使用するアクセス許可が必要です。詳細については、*Amazon Managed Streaming for Apache Kafka デベロッパーガイド*の [Amazon MSK 暗号化](https://docs.aws.amazon.com/msk/latest/developerguide/msk-encryption.html)を参照してください。
## パラメータ
このアクションで AWS IoT ルールを作成するときは、次の情報を指定する必要があります。
destinationArn
Apache Kafka Virtual Private Cloud (VPC) 送信先の Amazon リソースネーム (ARN)。送信先の作成の詳細については、「」を参照してください[Apache Kafka Virtual Private Cloud (VPC) の送信先](kafka-vpc-destination.md)。
トピック
Kafka のブローカーに送信されるメッセージの Kafka のトピック。
このフィールドは、置換テンプレートを使用して置換できます。詳細については、「[置換テンプレート](iot-substitution-templates.md)」を参照してください。
キー (オプション)
Kafka のメッセージキー
このフィールドは、置換テンプレートを使用して置換できます。詳細については、「[置換テンプレート](iot-substitution-templates.md)」を参照してください。
ヘッダー (オプション)
指定した Kafka ヘッダーのリスト。各ヘッダーは、Kafka アクションを作成するときに指定できるキーと値のペア (1 つのキーと 1 つの値) です。これらのヘッダーを使用して、メッセージペイロードを変更せずに IoT クライアントからダウンストリーム Kafka クラスターにデータをルーティングできます。
このフィールドは、置換テンプレートを使用して置換できます。インラインルールの関数を Kafka Action のヘッダーで代替テンプレートとして渡す方法については、「[例](#apache-kafka-rule-action-examples)」を参照してください。詳細については、「[置換テンプレート](iot-substitution-templates.md)」を参照してください。
バイナリ形式のヘッダーはサポートされていません。
パーティション (オプション)
Kafka のメッセージパーティション。
このフィールドは、置換テンプレートを使用して置換できます。詳細については、「[置換テンプレート](iot-substitution-templates.md)」を参照してください。
clientProperties
Apache Kafka プロデューサークライアントのプロパティを定義するオブジェクト。
acks (オプション)
リクエストが完了したとみなされる前に、プロデューサーがサーバーに受信することを求める確認応答の数。
値として 0 を指定すると、プロデューサーはサーバーからの確認応答を待機しなくなります。サーバーがメッセージを受信しない場合、プロデューサーはメッセージの送信を再試行しません。
有効な値は、`-1`、`0`、`1`、`all` です。デフォルト値は `1` です。
bootstrap.servers
Kafka クラスターへの初期接続を確立するために使用されるホストとポートのペア (`host1:port1`、`host2:port2` など) のリスト。
compression.type (optional)
プロデューサーによって生成されるすべてのデータの圧縮タイプ。
有効な値: `none`、`gzip`、`snappy`、`lz4`、`zstd`。デフォルト値は `none` です。
security.protocol
Kafka ブローカーにアタッチするために使用されるセキュリティプロトコル。
有効な値: `SSL`、`SASL_SSL`。デフォルト値は `SSL` です。
key.serializer
`ProducerRecord` で提供するキーオブジェクトをバイトに変換する方法を指定します。
有効な値: `StringSerializer`。
value.serializer
`ProducerRecord` で提供する値オブジェクトをバイトに変換する方法を指定します。
有効な値: `ByteBufferSerializer`。
ssl.truststore
base64 形式のトラストストアファイル、または [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) 内のトラストストアファイルの場所。トラストストアが Amazon 認証機関 (CA) によって信頼されている場合は、この値は必須ではありません。
このフィールドは置換テンプレートをサポートしています。Secrets Manager を使用して Kafka ブローカーへの接続に必要な認証情報を保存する場合、`get_secret` SQL 関数を使用してこのフィールドの値を取得できます。置換テンプレートの詳細については、「[置換テンプレート](iot-substitution-templates.md)」を参照してください。`get_secret` SQL 関数の詳細については、「[get\$1secret(secretId, secretType, key, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret)」を参照してください。トラストストアがファイル形式の場合は、`SecretBinary` パラメータを使用します。トラストストアが文字列の形式である場合は、`SecretString` パラメータを使用します。
この値の最大サイズは 65 KB です。
ssl.truststore.password
信頼ストアのパスワード。この値は、トラストストアのパスワードを作成した場合にのみ必要です。
ssl.keystore
キーストアファイル。`security.protocol` の値として `SSL` を指定する場合、この値は必須です。
このフィールドは置換テンプレートをサポートしています。Secrets Manager を使用して、Kafka ブローカーへの接続に必要な認証情報を保存します。このフィールドの値を取得するには、`get_secret` 関数を使用します。置換テンプレートの詳細については、「[置換テンプレート](iot-substitution-templates.md)」を参照してください。`get_secret` SQL 関数の詳細については、「[get\$1secret(secretId, secretType, key, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret)」を参照してください。`SecretBinary` パラメータを使用します。
ssl.keystore.password
キーストアファイルのストアパスワード。`ssl.keystore` の値を指定している場合、この値は必須です。
このフィールドの値はプレーンテキストにすることができます。このフィールドは、代替テンプレートもサポートします。Secrets Manager を使用して、Kafka ブローカーへの接続に必要な認証情報を保存します。このフィールドの値を取得するには、`get_secret` 関数を使用します。置換テンプレートの詳細については、「[置換テンプレート](iot-substitution-templates.md)」を参照してください。`get_secret` SQL 関数の詳細については、「[get\$1secret(secretId, secretType, key, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret)」を参照してください。`SecretString` パラメータを使用します。
ssl.key.password
キーストアファイル内のプライベートキーのパスワード。
このフィールドは置換テンプレートをサポートしています。Secrets Manager を使用して、Kafka ブローカーへの接続に必要な認証情報を保存します。このフィールドの値を取得するには、`get_secret` 関数を使用します。置換テンプレートの詳細については、「[置換テンプレート](iot-substitution-templates.md)」を参照してください。`get_secret` SQL 関数の詳細については、「[get\$1secret(secretId, secretType, key, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret)」を参照してください。`SecretString` パラメータを使用します。
sasl.mechanism
Kafka のブローカーに接続するために使用されるセキュリティメカニズム。この値は、`security.protocol` の `SASL_SSL` を指定する場合に必要です。
有効な値: `PLAIN`、`SCRAM-SHA-512`、`GSSAPI`。
`SCRAM-SHA-512` は、cn-north-1、cn-northwest-1、us-gov-east-1、および us-gov-west-1 リージョンでサポートされている唯一のセキュリティメカニズムです。
sasl.plain.username
Secrets Manager からシークレット文字列を取得するために使用されるユーザー名。この値は、`security.protocol` の `SASL_SSL` および `sasl.mechanism` の `PLAIN` を指定する場合に必要です。
sasl.plain.password
Secrets Manager からシークレット文字列を取得するために使用されるパスワード。この値は、`security.protocol` の `SASL_SSL` および `sasl.mechanism` の `PLAIN` を指定する場合に必要です。
sasl.scram.username
Secrets Manager からシークレット文字列を取得するために使用されるユーザー名。この値は、`security.protocol` の `SASL_SSL` および `sasl.mechanism` の `SCRAM-SHA-512` を指定する場合に必要です。
sasl.scram.password
Secrets Manager からシークレット文字列を取得するために使用されるパスワード。この値は、`security.protocol` の `SASL_SSL` および `sasl.mechanism` の `SCRAM-SHA-512` を指定する場合に必要です。
sasl.kerberos.keytab
Secrets Manager の Kerberos 認証用のキータブファイル。この値は、`security.protocol` の `SASL_SSL` および `sasl.mechanism` の `GSSAPI` を指定する場合に必要です。
このフィールドは置換テンプレートをサポートしています。Secrets Manager を使用して、Kafka ブローカーへの接続に必要な認証情報を保存します。このフィールドの値を取得するには、`get_secret` 関数を使用します。置換テンプレートの詳細については、「[置換テンプレート](iot-substitution-templates.md)」を参照してください。`get_secret` SQL 関数の詳細については、「[get\$1secret(secretId, secretType, key, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret)」を参照してください。`SecretBinary`パラメータを使用します。
sasl.kerberos.service.name
Apache Kafka が実行される Kerberos プリンシパル名。この値は、`security.protocol` の `SASL_SSL` および `sasl.mechanism` の `GSSAPI` を指定する場合に必要です。
sasl.kerberos.krb5.kdc
Apache Kafka プロデューサークライアントが接続するキー配布センター (KDC) のホスト名。この値は、`security.protocol` の `SASL_SSL` および `sasl.mechanism` の `GSSAPI` を指定する場合に必要です。
sasl.kerberos.krb5.realm
Apache Kafka プロデューサークライアントが接続する領域。この値は、`security.protocol` の `SASL_SSL` および `sasl.mechanism` の `GSSAPI` を指定する場合に必要です。
sasl.kerberos.principal
Kerberos 対応サービスにアクセスするためのチケットを Kerberos が割り当てることができる一意の Kerberos ID。この値は、`security.protocol` の `SASL_SSL` および `sasl.mechanism` の `GSSAPI` を指定する場合に必要です。
## 例
次の JSON 例では、 AWS IoT ルールで Apache Kafka アクションを定義します。次の例では、[sourceIp ()](iot-sql-functions.md#iot-function-sourceip) インライン関数を Kafka Action ヘッダーの[代替テンプレート](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html)として渡します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"kafka": {
"destinationArn": "arn:aws:iot:region:123456789012:ruledestination/vpc/VPCDestinationARN",
"topic": "TopicName",
"clientProperties": {
"bootstrap.servers": "kafka.com:9092",
"security.protocol": "SASL_SSL",
"ssl.truststore": "${get_secret('kafka_client_truststore', 'SecretBinary','arn:aws:iam::123456789012:role/kafka-get-secret-role-name')}",
"ssl.truststore.password": "kafka password",
"sasl.mechanism": "GSSAPI",
"sasl.kerberos.service.name": "kafka",
"sasl.kerberos.krb5.kdc": "kerberosdns.com",
"sasl.kerberos.keytab": "${get_secret('kafka_keytab','SecretBinary', 'arn:aws:iam::123456789012:role/kafka-get-secret-role-name')}",
"sasl.kerberos.krb5.realm": "KERBEROSREALM",
"sasl.kerberos.principal": "kafka-keytab/kafka-keytab.com"
},
"headers": [
{
"key": "static_header_key",
"value": "static_header_value"
},
{
"key": "substitutable_header_key",
"value": "${value_from_payload}"
},
{
"key": "source_ip",
"value": "${sourceIp()}"
}
]
}
}
]
}
}
```
**Kerberos セットアップに関する重要な注意事項**
+ キー配布センター (KDC) は、ターゲット VPC 内のプライベートドメインネームシステム (DNS) を介して解決可能である必要があります。考えられる方法の 1 つは、KDC DNS エントリをプライベートホストゾーンに追加することです。このアプローチの詳細については、「[プライベートホストゾーンの使用](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-private.html)」を参照してください。
+ 各 VPC で DNS 解決が有効になっている必要があります。詳細については、「[Using DNS with Your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html)」を参照してください。
+ VPC 送信先のネットワークインターフェイスセキュリティグループとインスタンスレベルのセキュリティグループは、次のポートで VPC 内からのトラフィックを許可する必要があります。
+ ブートストラップブローカーのリスナーポート上の TCP トラフィック (通常は 9092 ですが、9000～9100 の範囲内である必要があります)
+ KDC のポート 88 の TCP および UDP トラフィック
+ `SCRAM-SHA-512` は、cn-north-1、cn-northwest-1、us-gov-east-1、および us-gov-west-1 リージョンでサポートされている唯一のセキュリティメカニズムです。
# Apache Kafka Virtual Private Cloud (VPC) の送信先
Apache Kafka ルールアクションは、データを Amazon Virtual Private Cloud (Amazon VPC) の Apache Kafka クラスターにルーティングします。Apache Kafka ルールアクションで使用される VPC 設定は、ルールアクションの VPC 送信先を指定すると自動的に有効になります。
Apache Kafka Virtual Private Cloud (VPC) の送信先には、VPC 内のサブネットのリストが含まれます。ルールエンジンは、このリストで指定する各サブネットで Elastic Network Interface を作成します。ネットワークインターフェイスの詳細については、Amazon EC2 ユーザーガイドの[ Elastic Network Interface ](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html)（伸縮自在のネットワークインターフェース）を参照してください。
## 要件と考慮事項
+ インターネット経由でパブリックエンドポイントを使用してアクセスされるセルフマネージド型 Apache Kafka クラスターを使用している場合。
+ サブネット内のインスタンス用に NAT ゲートウェイを作成します。NAT ゲートウェイには、インターネットに接続できるパブリック IP アドレスがあるため、ルールエンジンがメッセージをパブリック Kafka クラスターに転送できます。
+ Apache Kafka Virtual Private Cloud (VPC) の送信先によって作成された Elastic Network Interface (ENIs) を使用して Elastic IP アドレスを割り当てます。使用するセキュリティグループは、着信トラフィックをブロックするように設定する必要があります。
**注記**
Apache Kafka Virtual Private Cloud (VPC) の送信先が無効になってから再度有効になっている場合は、Elastic IPs を新しい ENIs に再関連付けする必要があります。
+ Apache Kafka Virtual Private Cloud (VPC) 送信先が 30 日間連続してトラフィックを受信しない場合、無効になります。
+ Apache Kafka Virtual Private Cloud (VPC) の送信先で使用されるリソースが変更されると、送信先は無効になり、使用できなくなります。
+ Apache Kafka Virtual Private Cloud (VPC) の送信先を無効にすることができる変更には、次のようなものがあります。
+ VPC、サブネット、セキュリティグループ、または使用されるロールを削除します。
+ 必要なアクセス許可がなくなるようにロールを変更します。
+ サブネット容量に近いため、[FedRAMP](https://aws.amazon.com/compliance/fedramp/) パッチを適用できません。
+ 送信先を無効にします。
## 料金
請求のために、リソースが VPC 内にある場合にリソースにメッセージを送信するアクションに加えて、VPC ルールアクションが計測されます。料金については、[AWS IoT Core 料金](https://aws.amazon.com/iot-core/pricing/)を参照してください。
## Apache Kafka Virtual Private Cloud (VPC) 送信先の作成
[CreateTopicRuleDestination](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateTopicRuleDestination.html) API または AWS IoT Core コンソールを使用して、Apache Kafka Virtual Private Cloud (VPC) の送信先を作成します。
送信先を作成するときは、次の情報を指定する必要があります。
vpcId
Amazon VPC の一意の ID。
subnetIds
ルールエンジンが Elastic Network Iinterfaces を作成するサブネットのリスト。ルールエンジンは、リスト内のサブネットごとに 1 つのネットワークインターフェイスを割り当てます。
securityGroups (オプション)
ネットワークインターフェイスに適用するセキュリティグループのリスト。
roleArn
ユーザーに代わってネットワークインターフェイスを作成するための許可を持つロールの Amazon リソースネーム (ARN)。
この ARN には、次の例のようなポリシーがアタッチされている必要があります。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeVpcs",
"ec2:DeleteNetworkInterface",
"ec2:DescribeSubnets",
"ec2:DescribeVpcAttribute",
"ec2:DescribeSecurityGroups"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "ec2:CreateNetworkInterfacePermission",
"Resource": "*",
"Condition": {
"StringEquals": {
"ec2:ResourceTag/VPCDestinationENI": "true"
}
}
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface",
"aws:RequestTag/VPCDestinationENI": "true"
}
}
}
]
}
```
### を使用して Apache Kafka Virtual Private Cloud (VPC) 送信先を作成する AWS CLI
次の例は、 を使用して送信先を作成する方法を示しています AWS CLI。
```
aws --region regions iot create-topic-rule-destination --destination-configuration 'vpcConfiguration={subnetIds=["subnet-123456789101230456"],securityGroups=[],vpcId="vpc-123456789101230456",roleArn="arn:aws:iam::123456789012:role/role-name"}'
```
このコマンドを実行すると、送信先ステータスは になります`IN_PROGRESS`。数分後、そのステータスは`ERROR` (コマンドが成功しなかった場合) または `ENABLED`に変わります。送信先ステータスが `ENABLED` の場合、使用可能です。
次のコマンドを使用して、Apache Kafka Virtual Private Cloud (VPC) の送信先のステータスを取得できます。
```
aws --region region iot get-topic-rule-destination --arn "VPCDestinationARN"
```
### AWS IoT Core コンソールを使用して Apache Kafka Virtual Private Cloud (VPC) 送信先を作成する
次の手順では、 AWS IoT Core コンソールを使用して送信先を作成する方法について説明します。
1. AWS IoT Core コンソールに移動します。左のペインの**[Act]** タブで、**[送信先]** を選択します。
1. 以下のフィールドに値を入力します。
+ **VPC ID**
+ **サブネット ID**
+ **セキュリティグループ**
1. ネットワークインターフェイスの作成に必要な許可を持つロールを選択します。上記のポリシー例には、これらの許可が含まれています。
Apache Kafka Virtual Private Cloud (VPC) の送信先ステータスが **ENABLED** になると、すぐに使用できます。
# CloudWatch アラーム
CloudWatch アラーム (`cloudWatchAlarm`) アクションは、Amazon CloudWatch アラームの状態を変更します。状態変更の理由と、この呼び出しでの値を指定できます。
## 要件
このルールアクションには、以下の要件があります。
+ オペレーションを実行するために が引き受け AWS IoT ることができる IAM ロール`cloudwatch:SetAlarmState`。詳細については、「[必要なアクセスを AWS IoT ルールに付与する](iot-create-role.md)」を参照してください。
AWS IoT コンソールで、このルールアクションを実行 AWS IoT することを に許可するロールを選択または作成できます。
## パラメータ
このアクションで AWS IoT ルールを作成するときは、次の情報を指定する必要があります。
`alarmName`
CloudWatch アラーム名｡
[代替テンプレート](iot-substitution-templates.md)をサポート: API および AWS CLI のみ
`stateReason`
アラーム変更の理由。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`stateValue`
アラーム状態の値。有効な値: `OK`、`ALARM`、`INSUFFICIENT_DATA`。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`roleArn`
CloudWatch アラームへのアクセスを許可する IAM ロール。詳細については、「[要件](#cloudwatch-alarms-rule-action-requirements)」を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
## 例
次の JSON 例は、 AWS IoT ルールで CloudWatch アラームアクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"cloudwatchAlarm": {
"alarmName": "IotAlarm",
"stateReason": "Temperature stabilized.",
"stateValue": "OK",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw"
}
}
]
}
}
```
## 以下の資料も参照してください。
+ *Amazon CloudWatch ユーザーガイド*の「[Amazon CloudWatch とは](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/)」
+ *Amazon CloudWatch ユーザーガイド*の「[Amazon CloudWatch アラームの使用](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html)」
# CloudWatch Logs
CloudWatch Logs (`cloudwatchLogs`) アクションは、データを Amazon CloudWatch Logs に送信します。`batchMode` を使用して、1 つのメッセージで複数のデバイスログレコードをアップロードし、タイムスタンプを付けることができます。アクションがデータを送信するロググループを指定できます。
## 要件
このルールアクションには、以下の要件があります。
+ が `logs:CreateLogStream`、、`logs:DescribeLogStreams`および `logs:PutLogEvents`オペレーションを実行するために引き受け AWS IoT ることができる IAM ロール。詳細については、「[必要なアクセスを AWS IoT ルールに付与する](iot-create-role.md)」を参照してください。
AWS IoT コンソールで、このルールアクションを実行することを に許可 AWS IoT するロールを選択または作成できます。
+ カスタマーマネージド AWS KMS key (KMS キー) を使用して CloudWatch Logs のログデータを暗号化する場合、サービスには発信者に代わって KMS キーを使用するアクセス許可が必要です。詳しくは、*Amazon CloudWatch Logs ユーザーガイド*の[AWS KMSを使用して CloudWatch Logs のログデータを暗号化する](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/encrypt-log-data-kms.html)を参照してください。
## `batchMode` の MQTT メッセージ形式の要件
`batchMode` をオフにして CloudWatch Logs ルールアクションを使用する場合、MQTT メッセージフォーマットの要件はありません。(注意: `batchMode` パラメータのデフォルト値は `false` です)。ただし、`batchMode` をオンにして、CloudWatch Logs ルールアクションを使用する場合 (パラメータ値は `true`) 、デバイス側のログを含む MQTT メッセージはタイムスタンプとメッセージペイロードを含むようにフォーマットする必要があります。**注意:** `timestamp` は、イベントの発生時刻を表し、1970 年 1 月 1 日 00:00:00 UTC からのミリ秒数で表されます。
発行形式の例を次に示します。
```
[
{"timestamp": 1673520691093, "message": "Test message 1"},
{"timestamp": 1673520692879, "message": "Test message 2"},
{"timestamp": 1673520693442, "message": "Test message 3"}
]
```
デバイス側のログの生成方法によっては、この要件を満たすために送信する前にフィルタリングして再フォーマットする必要がある場合があります。詳細については、「[MQTT メッセージペイロード](https://docs.aws.amazon.com/iot/latest/developerguide/topicdata.html)」を参照してください。
`batchMode` パラメータに関係なく、`message`コンテンツは AWS IoT メッセージサイズの制限に準拠する必要があります。詳細については、「[AWS IoT Core エンドポイントとクォータ](https://docs.aws.amazon.com/general/latest/gr/iot-core.html)」を参照してください。
## パラメータ
このアクションで AWS IoT ルールを作成するときは、次の情報を指定する必要があります。
`logGroupName`
アクションがデータを送信する CloudWatch ロググループ。
[置換テンプレート](iot-substitution-templates.md)をサポート: API および AWS CLI のみ
`roleArn`
CloudWatch ロググループへのアクセスを許可する IAM ロール。詳細については、「[要件](#cloudwatch-logs-rule-action-requirements)」を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
(オプション) `batchMode`
ログレコードのバッチを抽出して CloudWatch にアップロードするかどうかを示します。値には `true`または `false` (デフォルト) が含まれます。詳細については、「[要件](#cloudwatch-logs-rule-action-requirements)」を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
## 例
次の JSON 例では、 AWS IoT ルールで CloudWatch Logs アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"cloudwatchLogs": {
"logGroupName": "IotLogs",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw",
"batchMode": false
}
}
]
}
}
```
## 関連情報
+ *Amazon CloudWatch Logs ユーザーガイド*の「[Amazon CloudWatch Logs とは](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/)」
# CloudWatch メトリクス
CloudWatch メトリクス (`cloudwatchMetric`) アクションは Amazon CloudWatch メトリクスを取得します。メトリクスの名前空間、名前、値、単位、タイムスタンプを指定できます。
## 要件
このルールアクションには、以下の要件があります。
+ オペレーションを実行するために が引き受け AWS IoT ることができる IAM ロール`cloudwatch:PutMetricData`。詳細については、「[必要なアクセスを AWS IoT ルールに付与する](iot-create-role.md)」を参照してください。
AWS IoT コンソールで、このルールアクションを実行することを に許可 AWS IoT するロールを選択または作成できます。
## パラメータ
このアクションで AWS IoT ルールを作成するときは、次の情報を指定する必要があります。
`metricName`
CloudWatch メトリクス名前空間。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`metricNamespace`
CloudWatch メトリクス名前空間。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`metricUnit`
CloudWatch でサポートされているメトリクス単位。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`metricValue`
CloudWatch メトリクス値を含む文字列。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`metricTimestamp`
(オプション) タイムスタンプ (秒単位) を含む文字列 (Unix エポック時間)。デフォルトは現在の Unix エポック時間です。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`roleArn`
CloudWatch メトリクスへのアクセスを許可する IAM ロール。詳細については、「[要件](#cloudwatch-metrics-rule-action-requirements)」を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
## 例
次の JSON 例では、 AWS IoT ルールで CloudWatch メトリクスアクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"cloudwatchMetric": {
"metricName": "IotMetric",
"metricNamespace": "IotNamespace",
"metricUnit": "Count",
"metricValue": "1",
"metricTimestamp": "1456821314",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw"
}
}
]
}
}
```
次の JSON の例では、 AWS IoT ルールで置換テンプレートを使用して CloudWatch メトリクスアクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"cloudwatchMetric": {
"metricName": "${topic()}",
"metricNamespace": "${namespace}",
"metricUnit": "${unit}",
"metricValue": "${value}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw"
}
}
]
}
}
```
## 関連情報
+ *Amazon CloudWatch ユーザーガイド*の「[Amazon CloudWatch とは](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/)」
+ *Amazon CloudWatch ユーザーガイド*の [Amazon CloudWatch メトリクスの使用](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html)
# DynamoDB
DynamoDB (`dynamoDB`) アクションは、MQTT メッセージの全部または一部を Amazon DynamoDB テーブルに書き込みます。
DynamoDB アクションでルールを作成してテストする方法を示すチュートリアルに従うことができます。詳細については、「[チュートリアル: デバイスデータの DynamoDB テーブルへの保存](iot-ddb-rule.md)」を参照してください。
**注記**
このルールは、JSON 以外のデータをバイナリデータとして DynamoDB に書き込みます。DynamoDB コンソールでは、base64 でエンコードされたテキストとしてデータが表示されます。
## 要件
このルールアクションには、以下の要件があります。
+ オペレーションを実行するために が引き受け AWS IoT ることができる IAM ロール`dynamodb:PutItem`。詳細については、「[必要なアクセスを AWS IoT ルールに付与する](iot-create-role.md)」を参照してください。
AWS IoT コンソールで、このルールアクションを実行することを に許可 AWS IoT するロールを選択または作成できます。
+ カスタマーマネージド AWS KMS key (KMS キー) を使用して DynamoDB に保管中のデータを暗号化する場合、サービスには発信者に代わって KMS キーを使用するアクセス許可が必要です。詳細については、[*Amazon DynamoDB Getting Started Guide*](Amazon DynamoDB 開始方法ガイド) の [[Customer Managed KMS key](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/encryption.howitworks.html#managed-cmk-customer-managed)](カスタマー管理の CMK) を参照してください。
## パラメータ
このアクションで AWS IoT ルールを作成するときは、次の情報を指定する必要があります。
`tableName`
DynamoDB テーブルの名前。
[置換テンプレート](iot-substitution-templates.md)をサポート: API および AWS CLI のみ
`hashKeyField`
ハッシュキー (パーティションキーとも呼ばれます) の名前。
[置換テンプレート](iot-substitution-templates.md)をサポート: API および AWS CLI のみ
`hashKeyType`
(オプション) ハッシュキー (パーティションキーとも呼ばれます) のデータ型。有効な値: `STRING`、`NUMBER`。
[置換テンプレート](iot-substitution-templates.md)をサポート: API および AWS CLI のみ
`hashKeyValue`
ハッシュキーの値。`${topic()}` や `${timestamp()}` などの置換テンプレートの使用を検討してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`rangeKeyField`
(オプション) 範囲キー (ソートキーとも呼ばれます) の名前。
[置換テンプレート](iot-substitution-templates.md)をサポート: API および AWS CLI のみ
`rangeKeyType`
(オプション) 範囲キー (ソートキーとも呼ばれます) のデータ型。有効な値: `STRING`、`NUMBER`。
[置換テンプレート](iot-substitution-templates.md)をサポート: API および AWS CLI のみ
`rangeKeyValue`
(オプション) 範囲キーの値。`${topic()}` や `${timestamp()}` などの置換テンプレートの使用を検討してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`payloadField`
(オプション) ペイロードが書き込まれる列の名前。この値を省略した場合、ペイロードは `payload` という名前の列に書き込まれます。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`operation`
(オプション) 実行する操作の種類。有効な値: `INSERT`、`UPDATE`、`DELETE`。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`roleARN`
DynamoDB テーブルへのアクセスを許可する IAM ロール。詳細については、「[要件](#dynamodb-rule-action-requirements)」を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
DynamoDB テーブルに書き込まれるデータは、ルールの SQL ステートメントの結果です。
## 例
次の JSON の例では、 AWS IoT ルールで DynamoDB アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * AS message FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"dynamoDB": {
"tableName": "my_ddb_table",
"hashKeyField": "key",
"hashKeyValue": "${topic()}",
"rangeKeyField": "timestamp",
"rangeKeyValue": "${timestamp()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDB"
}
}
]
}
}
```
## 関連情報
+ *Amazon DynamoDB デベロッパーガイド*の [Amazon DynamoDB とは?](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/)
+ *Amazon DynamoDB デベロッパーガイド*の [DynamoDB の開始方法](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html)
+ [チュートリアル: デバイスデータの DynamoDB テーブルへの保存](iot-ddb-rule.md)
# DynamoDBv2
DynamoDBv2 (`dynamoDBv2`) アクションは、MQTT メッセージの全部または一部を Amazon DynamoDB テーブルに書き込みます。ペイロードの各属性は、DynamoDB データベースの個別の列に書き込まれます。
## 要件
このルールアクションには、以下の要件があります。
+ オペレーションを実行するために が引き受け AWS IoT ることができる IAM ロール`dynamodb:PutItem`。詳細については、「[必要なアクセスを AWS IoT ルールに付与する](iot-create-role.md)」を参照してください。
AWS IoT コンソールで、このルールアクションを実行することを に許可 AWS IoT するロールを選択または作成できます。
+ MQTT メッセージのペイロードは、定義されている場合、テーブルのプライマリパーティションキーおよびテーブルのプライマリソートキーに一致するルートレベルキーが含まれる必要があります。
+ カスタマーマネージド AWS KMS key (KMS キー) を使用して DynamoDB に保管中のデータを暗号化する場合、サービスには発信者に代わって KMS キーを使用するアクセス許可が必要です。詳細については、[*Amazon DynamoDB Getting Started Guide*](Amazon DynamoDB 開始方法ガイド) の [[Customer Managed KMS key](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/encryption.howitworks.html#managed-cmk-customer-managed)](カスタマー管理の CMK) を参照してください。
## パラメータ
このアクションで AWS IoT ルールを作成するときは、次の情報を指定する必要があります。
`putItem`
メッセージデータを書き込む DynamoDB テーブルを指定するオブジェクト。このオブジェクトには、次の情報が含まれている必要があります。
`tableName`
DynamoDB テーブルの名前。
[置換テンプレート](iot-substitution-templates.md)をサポート: API および AWS CLI のみ
`roleARN`
DynamoDB テーブルへのアクセスを許可する IAM ロール。詳細については、「[要件](#dynamodb-v2-rule-action-requirements)」を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
DynamoDB テーブルに書き込まれるデータは、ルールの SQL ステートメントの結果です。
## 例
次の JSON の例では、 AWS IoT ルールで DynamoDBv2 アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * AS message FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"dynamoDBv2": {
"putItem": {
"tableName": "my_ddb_table"
},
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDBv2",
}
}
]
}
}
```
次の JSON の例では、 AWS IoT ルールで置換テンプレートを使用して DynamoDB アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2015-10-08",
"actions": [
{
"dynamoDBv2": {
"putItem": {
"tableName": "${topic()}"
},
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDBv2"
}
}
]
}
}
```
## 関連情報
+ *Amazon DynamoDB デベロッパーガイド*の [Amazon DynamoDB とは?](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/)
+ *Amazon DynamoDB デベロッパーガイド*の [DynamoDB の開始方法](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html)
# Elasticsearch
Elasticsearch (`elasticsearch`) アクションは、Amazon OpenSearch Service ドメインに MQTT メッセージのデータを書き込みます。その後、OpenSearch Dashboards などのツールを使用して、OpenSearch Service のデータをクエリおよび視覚化できます。
**警告**
`Elasticsearch`アクションは、既存のルールアクションのみで使用できます。新しいルールアクションを作成したり、既存のルールアクションを更新したりするには、`OpenSearch`ルールアクションを代わりに使用します。詳細については、「[OpenSearch](opensearch-rule-action.md)」を参照してください。
## 要件
このルールアクションには、以下の要件があります。
+ オペレーションを実行するために が引き受け AWS IoT ることができる IAM ロール`es:ESHttpPut`。詳細については、「[必要なアクセスを AWS IoT ルールに付与する](iot-create-role.md)」を参照してください。
AWS IoT コンソールで、このルールアクションを実行することを に許可 AWS IoT するロールを選択または作成できます。
+ カスタマーマネージド AWS KMS key (KMS キー) を使用して OpenSearch で保管中のデータを暗号化する場合、サービスには発信者に代わって KMS キーを使用するアクセス許可が必要です。詳細については、[Amazon OpenSearch Service デベロッパーガイド](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/encryption-at-rest.html)の「*Amazon OpenSearch Service の保管中のデータの暗号化*」を参照してください。
## パラメータ
このアクションで AWS IoT ルールを作成するときは、次の情報を指定する必要があります。
`endpoint`
サービスドメインのエンドポイント。
[置換テンプレート](iot-substitution-templates.md)をサポート: API および AWS CLI のみ
`index`
データを保存したい インデックス。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`type`
保存するドキュメントのタイプ。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`id`
各ドキュメントの一意の識別子。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`roleARN`
OpenSearch Service ドメインへのアクセスを許可する IAM ロール。詳細については、「[要件](#elasticsearch-rule-action-requirements)」を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
## 例
次の JSON の例では、 AWS IoT ルールで Elasticsearch アクションを定義し、`elasticsearch`アクションのフィールドを指定する方法を定義します。詳しくは、[ElasticsearchAction](https://docs.aws.amazon.com/iot/latest/apireference/API_ElasticsearchAction.html) を参照してください。
```
{
"topicRulePayload": {
"sql": "SELECT *, timestamp() as timestamp FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"elasticsearch": {
"endpoint": "https://my-endpoint",
"index": "my-index",
"type": "my-type",
"id": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_es"
}
}
]
}
}
```
次の JSON の例では、 AWS IoT ルールで置換テンプレートを使用して Elasticsearch アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"elasticsearch": {
"endpoint": "https://my-endpoint",
"index": "${topic()}",
"type": "${type}",
"id": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_es"
}
}
]
}
}
```
## 関連情報
+ [OpenSearch](opensearch-rule-action.md)
+ [Amazon OpenSearch Service とは](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/)
# HTTP
HTTPS (`http`) アクションは、MQTT メッセージからウェブアプリケーションまたはサービスを指すことができる HTTPS エンドポイントにデータを送信します。
## 要件
このルールアクションには、以下の要件があります。
+ ルールエンジンが HTTPS エンドポイントを使用する前に、それらの HTTPS エンドポイントを確認して有効にする必要があります。詳細については、「[HTTP アクションの送信先](http-action-destination.md)」を参照してください。
## パラメータ
このアクションで AWS IoT ルールを作成するときは、次の情報を指定する必要があります。
`url`
HTTP POST メソッドを使用してメッセージを送信する HTTPS エンドポイント。ホスト名の代わりに IP アドレスを使用する場合は、IPv4 アドレスである必要があります。IPv6 アドレスはサポートされません。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`confirmationUrl`
(オプション) 指定した場合、確認 URL AWS IoT を使用して一致するトピックルールの送信先を作成します。HTTP アクションで使用する前に、HTTP アクションの送信先を有効にする必要があります。詳細については、「[HTTP アクションの送信先](http-action-destination.md)」を参照してください。置換テンプレートを使用する場合は、アクションを使用する前に HTTP `http`アクションの送信先を手動で作成する必要があります。 は のプレフィックス`confirmationUrl`である必要があります`url`。
`url` との関係および `confirmationUrl` は、次のように記述されます。
+ `url` がハードコードされており、 が指定されていない場合`confirmationUrl`、 `url`フィールドは暗黙的に として扱われます`confirmationUrl`。 は のトピックルールの送信先 AWS IoT を作成します`url`。
+ `url` と `confirmationUrl`がハードコードされている場合、 は で始まる`url`必要があります`confirmationUrl`。 は のトピックルールの送信先 AWS IoT を作成します`confirmationUrl`。
+ `url` に置換テンプレートが含まれている場合は、`confirmationUrl` を指定し、`url` は `confirmationUrl` で始まる必要があります。に置換テンプレート`confirmationUrl`が含まれている場合は、アクションを使用する前に HTTP `http`アクションの送信先を手動で作成する必要があります。`confirmationUrl` に置換テンプレートが含まれていない場合、 は のトピックルールの送信先 AWS IoT を作成します`confirmationUrl`。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`headers`
(オプション) エンドポイントへの HTTP リクエストに含めるヘッダーのリスト。各ヘッダーには、以下の情報が必要です。
`key`
ヘッダーのキー。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
`value`
ヘッダーの値
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
ペイロードが JSON 形式の場合、デフォルトのコンテンツタイプは application/json です。それ以外の場合は、application/octet-stream です。キー content-type (大文字と小文字を区別しない) でヘッダー内の正確なコンテンツタイプを指定することで、上書きできます。
`auth`
(オプション) `url` 引数で指定されたエンドポイント URL に接続するためにルールエンジンが使用する認証。現在、サポートされている認証タイプは署名バージョン 4 のみです。認可の詳細については、「[HTTP 承認](https://docs.aws.amazon.com/iot/latest/apireference/API_HttpAuthorization.html)」を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
`enableBatching`
(オプション) HTTP アクションメッセージを特定の URL に対する 1 つのリクエストに処理するかどうか。値は true または false にすることができます。バッチ処理の詳細については、[「HTTP アクションメッセージのバッチ処理](http_batching.md)」を参照してください。
ブール値
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
`batchConfig`
(オプション) バッチ処理の設定。有効にしたら、`batchConfig`パラメータを指定する必要があります。`batchConfig` パラメータを指定しない場合、デフォルト値が使用されます。
`maxBatchOpenMs`
送信メッセージが他のメッセージがバッチを作成するのを待機する最大時間 (ミリ秒単位）。設定が高いほど、バッチ処理された HTTP アクションのレイテンシーが長くなります。
最小値: 5 ミリ秒。最大値: 200 ミリ秒。
デフォルト値: 20 ミリ秒
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
`maxBatchSize`
1 回のアクション実行でまとめてバッチ処理されるメッセージの最大数。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
最小値: 2 メッセージ。最大値: 10 メッセージ
デフォルト値: 10 メッセージ
`maxBatchSizeBytes`
メッセージバッチの最大サイズ、バイト単位。
最小値: 100 バイト。最大値: 131,072 バイト
デフォルト値: 5,120 バイト
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
ペイロードが JSON 形式の場合、デフォルトのコンテンツタイプは application/json です。それ以外の場合は、application/octet-stream です。キー content-type (大文字と小文字を区別しない) でヘッダー内の正確なコンテンツタイプを指定することで、上書きできます。
## 例
次の JSON の例では、HTTP アクションを使用して AWS IoT ルールを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com",
"headers": [
{
"key": "static_header_key",
"value": "static_header_value"
},
{
"key": "substitutable_header_key",
"value": "${value_from_payload}"
}
]
}
}
]
}
}
```
```
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com",
"headers": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"enableBatching": true,
"batchConfig": {
"maxBatchOpenMs": 123,
"maxBatchSize": 5,
"maxBatchSizeBytes": 131072,
}
},
"errorAction": {
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com"
// batchConfig is not allowed here
}
}
```
## HTTP アクションの再試行ロジック
AWS IoT ルールエンジンは、次のルールに従って HTTP アクションを再試行します。
+ ルールエンジンは、1 回以上メッセージの送信を試みます。
+ ルールエンジンは、最大で 2 回再試行します。最大試行回数は 3 回です。
+ 次の場合、ルールエンジンは再試行を試行しません。
+ 前回の試行で 16,384 バイトを超える応答が提供された場合。
+ ダウンストリームウェブサービスまたはアプリケーションが試行後に TCP 接続を閉じた場合。
+ 再試行を含むリクエストを完了するための合計時間が、リクエストタイムアウト制限を超えた場合。
+ リクエストが 429、500～599 以外の HTTP ステータスコードを返した場合。
**注記**
再試行には、[標準データ転送コスト](https://aws.amazon.com/ec2/pricing/on-demand/)が適用されます。
## 関連情報
+ [HTTP アクションメッセージのバッチ処理](http_batching.md)
+ [HTTP アクションの送信先](http-action-destination.md)
+ ブログの*モノのインターネット AWS*で、 [からウェブサービス AWS IoT Core にデータを直接ルーティング](https://aws.amazon.com/blogs/iot/route-data-directly-from-iot-core-to-your-web-services/)する
# HTTP アクションメッセージのバッチ処理
バッチ処理を使用して、1 つのリクエストで複数の HTTP アクションメッセージを送信できます。
## 概要:
バッチ処理を使用すると、 AWS IoT Core ルールエンジンから HTTP エンドポイントにバッチでメッセージを送信できます。この機能は、HTTP アクションの実行数を減らすことでコストを削減し、新しい接続の確立に関連するオーバーヘッドを減らすことで効率を向上させるのに役立ちます。
**注記**
バッチ処理された HTTP アクションは 1 つのアクションとして計測されます。 AWS IoT Core ルールエンジンからダウンストリームサービスに出力されるバッチ処理されたアウトバウンドペイロードのサイズに基づいて、5 kiB 単位で計測されます。詳細については、[AWS IoT Core 料金表ページ](https://aws.amazon.com/iot-core/pricing/) を参照してください。
IoT ルールアクションの定義でバッチ処理を有効にすると、次のパラメータを設定できるようになります。
`maxBatchOpenMs`
送信メッセージが他のメッセージがバッチを作成するのを待機する最大時間 (ミリ秒単位）。設定が高いほど、バッチ処理された HTTP アクションのレイテンシーが長くなります。
最小値: 5 ミリ秒。最大値: 200 ミリ秒。
デフォルト値: 20 ミリ秒
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
`maxBatchSize`
1 回の IoT ルールアクション実行でまとめてバッチ処理されるメッセージの最大数。
最小値: 2 メッセージ。最大値: 10 メッセージ
デフォルト値: 10 メッセージ
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
`maxBatchSizeBytes`
メッセージバッチの最大サイズ、バイト単位。
最小値: 100 バイト。最大値: 131,072 バイト
デフォルト値: 5120 バイト
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
**重要**
複数のバッチパラメータを指定すると、最初の制限に達するとバッチ処理が完了します。たとえば、最大バッチオープン時間として 100 ミリ秒、最大バッチサイズとして 5 kiB を指定し、ルールエンジンが 100 ミリ秒以内に 2 kiB のみをバッチ処理する場合、2 kiB バッチが作成されて送信されます。
## バッチでの HTTP ヘッダーの使用
HTTP アクションでヘッダーを使用する場合、バッチ処理されたリクエストは、バッチに追加された最後のメッセージ (最後に発行したメッセージではない) のヘッダー値を使用します。次のいずれかのヘッダー値を使用することをお勧めします。
+ バッチ内のすべてのメッセージで同一
+ すべてのメッセージに適用可能 (認証情報など)
ヘッダーは HTTP リクエストとともに送信され、メッセージ本文の一部ではありません。
**注記**
バッチ処理が有効になっている場合:
バッチ処理されたリクエストには、バッチが JSON 配列として送信されるため、 `Content-Type: application/json`ヘッダーが自動的に含まれます。
バッチ内の最後のメッセージが、発行した最後のメッセージであることを保証することはできません。これは、バッチに書き込まれた最後のメッセージです。
## ペイロードの例
次の例は、HTTP エンドポイントに送信されるバッチ処理されたメッセージペイロードの構造を示しています。
```
[
{
"user_id": "user1",
"steps_today": 1000
},
{
"user_id": "user2",
"steps_today": 21000
},
{
"user_id": "user8",
"steps_today": 1500
},
...
]
```
## 制限事項
バッチ処理の制限は次のとおりです。
+ AWS IoT Core は、メッセージの全体的な順序付けを保証しません。バッチ処理は各ホストでローカルに実行されるため、バッチ内のメッセージが受信された順序とは異なる順序で処理される可能性があります。
+ AWS IoT Core は、受信者側でメッセージ処理をサポートしていません。ダウンストリームサービスがデータをバッチで受け入れて処理するように設定されていることを確認するのはお客様の責任です。
+ クロスアカウントバッチ処理は、メッセージが同じリソース識別子 (HTTP URL またはリソース ARN) 宛てであってもサポートされていません。
+ AWS IoT Core は、バッチサイズが指定した設定を満たすことを保証するものではありません。バッチは、タイミングとメッセージフローに基づいて設定された制限よりも小さい場合があります。
+ バッチ処理が有効になっている場合、バイナリペイロード (UTF-8 以外のデータ) はサポートされていません。UTF-8 テキストペイロード (JSON など) のみが受け入れられます。バイナリデータを送信するには、base64 でエンコードしてから HTTP アクションに送信し、受信エンドポイントでデコードします。たとえば、IoT ルールの[エンコード関数](iot-sql-functions.html#iot-function-encode)を使用してバイナリペイロードをエンコードできます。または、IoT デバイスでバイナリペイロードをエンコードして公開することもできます AWS IoT Core。
## バッチ処理のエラーアクション
エラーアクション定義で別のバッチロジックを定義することはできません。ただし、プライマリアクションでバッチ処理ロジックを定義している場合、エラーアクションはバッチ処理をサポートします。
バッチリクエストが失敗すると、 AWS IoT Core ルールエンジンは [HTTP アクションの再試行ロジック](https-rule-action.md#https-rule-action-retry-logic)に従います。最後の再試行後、失敗したバッチ全体に対してエラーアクションが呼び出されます。
バッチ処理が有効になっているエラーメッセージの例を次に示します。
```
{
"ruleName": "FailedTopicRule",
"topic": "topic/rulesengine",
"payloadsWithMetadata": [
{
"id": 1,
"cloudwatchTraceId": "bebd6d93-6d4a-899e-9e40-56e82252d2be",
"clientId": "Test",
"sourceIp": "10.0.0.0",
"base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
},
{
"id": 2,
"cloudwatchTraceId": "af94d3b8-0b18-1dbf-2c7d-513f5cb9e2e1",
"clientId": "Test",
"sourceIp": "10.0.0.0",
"base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
},
{
"id": 3,
"cloudwatchTraceId": "ca441266-c2ce-c916-6aee-b9e5c7831675",
"clientId": "Test",
"sourceIp": "10.0.0.0",
"base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
}
],
"failures": [
{
"affectedIds": [
1,
2,
3
],
"failedAction": "HttpAction",
"failedResource": "https://example.foobar.com/HttpAction",
"errorMessage": "HttpAction failed to make a request to the specified endpoint. StatusCode: 500. Reason: Internal Server Error."
},
{
"affectedIds": [
3
],
"failedAction": "S3Action",
"failedResource": "amzn-s3-demo-bucket",
"errorMessage": "Failed to put S3 object. The error received was The specified bucket does not exist"
},
{
"affectedIds": [
3
],
"failedAction": "LambdaAction",
"failedResource": "arn:aws:lambda:us-west-2:123456789012:function:dummy",
"errorMessage": "Failed to invoke lambda function. Received Server error from Lambda. The error code is 403"
}
]
}
```
**注記**
バッチ処理されたアクションの失敗は、より大きなエラーアクションペイロードも生成するため、サイズによるエラーアクションの失敗の可能性が高くなる可能性があります。`ErrorActionFailure` メトリクスを使用して、エラーアクションの失敗をモニタリングできます。詳細については「[ルールアクションのメトリクス](metrics_dimensions.md#rule-action-metrics)」を参照してください。
## を使用した HTTP アクションメッセージのバッチ処理 AWS CLI
### バッチ処理によるルールアクションの作成または更新
1. 適切な AWS CLI コマンドを使用して、ルールを作成または更新します。
+ 新しいルールを作成するには、[create-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html) コマンドを使用します。
```
aws iot create-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```
+ 既存のルールを更新するには、 [replace-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/replace-topic-rule.html) コマンドを使用します。
```
aws iot replace-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```
1. トピックルールペイロードで enableBatching パラメータを true に設定して、バッチ処理機能を有効にします。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com",
"headers": [
{
"key": "static_header_key",
"value": "static_header_value"
},
{
"key": "substitutable_header_key",
"value": "${value_from_payload}"
}
],
"enableBatching": true,
"batchConfig": {
"maxBatchOpenMs": 100,
"maxBatchSize": 5,
"maxBatchSizeBytes": 1024
}
}
}
]
}
```
1. バッチ処理パラメータを設定します。すべてのバッチパラメータを指定する必要はありません。1、2、または 3 つのバッチパラメータすべてを指定できます。バッチパラメータを指定しない場合、ルールエンジンはそのパラメータをデフォルト値で更新します。バッチパラメータとそのデフォルト値の詳細については、[「HTTP パラメータ](https-rule-action.md#https-rule-action-parameters)」を参照してください。
# HTTP アクションの送信先
HTTP アクションの送信先は、ルールエンジンがトピックルールからデータをルーティングできるウェブサービスです。 AWS IoT Core リソースは、 のウェブサービスを記述します AWS IoT。送信先リソースは、異なるルールで共有できます。
AWS IoT Core が別のウェブサービスにデータを送信する前に、サービスのエンドポイントにアクセスできることを確認する必要があります。
## 概要:
HTTP アクションの送信先は、確認 URL と 1 つ以上のデータ収集 URLs。送信先リソースには、ウェブサービスの確認 URL が含まれています。HTTP アクションを設定するときは、データを受信するエンドポイントの実際の URL とウェブサービスの確認 URL を指定します。送信先が確認されると、トピックルールは、SQL ステートメントの結果を HTTPS エンドポイントに送信します (確認 URL ではない)。
HTTP アクションの送信先は、次のいずれかの状態になります。
有効
送信先は確認済みで、ルールアクションによって使用できます。送信先をルールで使用するには、送信先は、`ENABLED`の状態である必要があります。有効にできるのは、「DISABLED」ステータスの送信先のみです。
無効
送信先は確認されましたが、ルールアクションでは使用できません。これは、確認プロセスを再度実行することなく、エンドポイントへのトラフィックを一時的に防止する場合に便利です。無効にできるのは、有効ステータスの送信先のみです。
IN\$1PROGRESS
送信先の確認は進行中です。
ERROR
送信先の確認がタイムアウトしました。
HTTP アクションの送信先を確認して有効にすると、アカウントの任意のルールで使用できます。
## HTTP アクションの送信先の管理
次のオペレーションを使用して、HTTP アクションの送信先を管理できます。
### HTTP アクションの送信先の作成
HTTP アクションの送信先を作成するには、 `CreateTopicRuleDestination`オペレーションを呼び出すか、 AWS IoT コンソールを使用します。
送信先を作成すると、 は確認 URL に確認リクエスト AWS IoT を送信します。確認リクエストの形式は次のとおりです。
```
HTTP POST {confirmationUrl}/?confirmationToken={confirmationToken}
Headers:
x-amz-rules-engine-message-type: DestinationConfirmation
x-amz-rules-engine-destination-arn:"arn:aws:iot:us-east-1:123456789012:ruledestination/http/7a280e37-b9c6-47a2-a751-0703693f46e4"
Content-Type: application/json
Body:
{
"arn":"arn:aws:iot:us-east-1:123456789012:ruledestination/http/7a280e37-b9c6-47a2-a751-0703693f46e4",
"confirmationToken": "AYADeMXLrPrNY2wqJAKsFNn-…NBJndA",
"enableUrl": "https://iot.us-east-1.amazonaws.com/confirmdestination/AYADeMXLrPrNY2wqJAKsFNn-…NBJndA",
"messageType": "DestinationConfirmation"
}
```
確認リクエストの内容には、以下の情報が含まれます。
arn
確認する HTTP アクションの送信先の Amazon リソースネーム (ARN)。
confirmationToken
によって送信された確認トークン AWS IoT Core。この例のトークンは切り捨てられます。トークンは長くなります。 AWS IoT Coreで目的地を確認するには、このトークンが必要です。
enableUrl
トピックルールの送信先を確認するために参照する URL。
messageType
メッセージのタイプ。
### HTTP アクションの送信先の確認
エンドポイントの確認プロセスを完了するには、 AWS CLIを使用している場合、確認 URL が確認リクエストを受信した後、次のいずれかの手順を実施する必要があります。
1.
**送信先がメッセージを受信する準備ができていることを確認する**
HTTP アクションの送信先が IoT メッセージを受信する準備ができていることを確認するには、確認リクエスト`enableUrl`で を呼び出すか、 `ConfirmTopicRuleDestination` API オペレーションを実行して確認リクエスト`confirmationToken`から を渡します。
1.
**トピックルールのステータスを有効に設定する**
送信先がメッセージを受信できることを確認したら、`UpdateTopicRuleDestination` API オペレーションを実行してトピックルールのステータスを `ENABLED` に設定する必要があります。
AWS IoT コンソールを使用している場合は、 をコピー`confirmationToken`し、 AWS IoT コンソールの送信先の確認ダイアログに貼り付けます。その後、トピックルールを有効にできます。
### 新しい確認リクエストの送信
送信先の新しい確認メッセージをアクティブ化するには、`UpdateTopicRuleDestination` を呼び出 して、トピックルールの送信先のステータスを `IN_PROGRESS` に設定します。
新しい確認リクエストを送信した後、確認プロセスを繰り返します。
### HTTP アクションの送信先の無効化と削除
送信先を無効にするには、`UpdateTopicRuleDestination`を呼び出して、トピックルールの送信先のステータスを `DISABLED` に設定します。無効状態のトピックルールは、新しい確認要求を送信しなくても、再度有効にすることができます。
HTTP アクションの送信先を削除するには、 を呼び出します`DeleteTopicRuleDestination`。
## 認証機関のサポート
**注記**
自己署名証明書はサポートされていません。
HTTP アクションの送信先の HTTPS エンドポイントは、[AWS プライベート認証機関](https://www.amazontrust.com/repository/)と [Lets Encrypt ](https://letsencrypt.org/certificates/)の両方によって発行された証明書をサポートします。
# AWS IoT Events
AWS IoT Events (`iotEvents`) アクションは、MQTT メッセージから AWS IoT Events 入力にデータを送信します。
**重要**
ペイロードが AWS IoT Core なしで に送信された場合`Input attribute Key`、またはキーがキーで指定された同じ JSON パスにない場合、IoT ルールはエラー で失敗します`Failed to send message to Iot Events`。
## 要件
このルールアクションには、以下の要件があります。
+ オペレーションを実行するために が引き受け AWS IoT ることができる IAM ロール`iotevents:BatchPutMessage`。詳細については、「[必要なアクセスを AWS IoT ルールに付与する](iot-create-role.md)」を参照してください。
AWS IoT コンソールで、このルールアクションを実行することを に許可 AWS IoT するロールを選択または作成できます。
## パラメータ
このアクションを使用して AWS IoT ルールを作成するときは、次の情報を指定する必要があります。
`batchMode`
(オプション) イベントアクションをバッチとして処理するかどうか。デフォルト値は `false` です。
`batchMode` が `true`で、ルール SQL ステートメントが配列に評価される場合、各配列要素は、 を呼び出して AWS IoT イベントに送信したときに個別のメッセージとして扱われます[https://docs.aws.amazon.com/iotevents/latest/apireference/API_iotevents-data_BatchPutMessage.html](https://docs.aws.amazon.com/iotevents/latest/apireference/API_iotevents-data_BatchPutMessage.html)。結果の配列には 10 を超えるメッセージを含めることはできません。
`batchMode` が `true` の場合、`messageId` を指定することはできません。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
`inputName`
AWS IoT Events 入力の名前。
[置換テンプレート](iot-substitution-templates.md)をサポート: API および AWS CLI のみ
`messageId`
(オプション) これを使用して、特定の を持つ 1 つの入力 (メッセージ) `messageId` のみがディ AWS IoT Events テクターによって処理されていることを確認します。`${newuuid()}` 置換テンプレートを使用して、リクエストごとに一意の ID を生成できます。
`batchMode` が `true` である場合、`messageId` を指定することはできません。新しい UUID 値が割り当てられます。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`roleArn`
がディテクターに入力 AWS IoT Events を送信 AWS IoT できるようにする IAM ロール。詳細については、「[要件](#iotevents-rule-action-requirements)」を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
## 例
次の JSON 例では、 AWS IoT ルールで IoT Events アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"iotEvents": {
"inputName": "MyIoTEventsInput",
"messageId": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_events"
}
}
]
}
}
```
## 関連情報
+ デ*AWS IoT Events ベロッパーガイド*の[「 AWS IoT Eventsとは](https://docs.aws.amazon.com/iotevents/latest/developerguide/)」
# AWS IoT SiteWise
AWS IoT SiteWise (`iotSiteWise`) アクションは、MQTT メッセージから のアセットプロパティにデータを送信します AWS IoT SiteWise。
AWS IoT モノからデータを取り込む方法を示すチュートリアルに従うことができます。詳細については、[AWS IoT SiteWise 「 ユーザーガイド」の AWS IoT 「 ](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/ingest-data-from-iot-things.html)へのデータの取り込み」チュートリアルまたは[AWS IoT 「 Core ルールを使用したデータの取り込み](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/iot-rules.html)」セクションを参照してください。 *AWS IoT SiteWise *
## 要件
このルールアクションには、以下の要件があります。
+ オペレーションを実行するために が引き受け AWS IoT ることができる IAM ロール`iotsitewise:BatchPutAssetPropertyValue`。詳細については、「[必要なアクセスを AWS IoT ルールに付与する](iot-create-role.md)」を参照してください。
次の信頼ポリシーの例をロールにアタッチできます。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iotsitewise:BatchPutAssetPropertyValue",
"Resource": "*"
}
]
}
```
セキュリティを向上させるために、 `Condition`プロパティで AWS IoT SiteWise アセット階層パスを指定できます。次の例は、アセット階層パスを指定する信頼ポリシーです。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iotsitewise:BatchPutAssetPropertyValue",
"Resource": "*",
"Condition": {
"StringLike": {
"iotsitewise:assetHierarchyPath": [
"/root node asset ID",
"/root node asset ID/*"
]
}
}
}
]
}
```
+ このアクション AWS IoT SiteWise を使用して にデータを送信する場合、データは `BatchPutAssetPropertyValue`オペレーションの要件を満たしている必要があります。詳細については、「*AWS IoT SiteWise API リファレンス*」の「[BatchPutAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html)」を参照してください。
## パラメータ
このアクションを使用して AWS IoT ルールを作成するときは、次の情報を指定する必要があります。
`putAssetPropertyValueEntries`
アセットプロパティ値エントリのリストで、それぞれに次の情報が含まれています。
`propertyAlias`
(オプション) アセットプロパティに関連付けられたプロパティエイリアス。`propertyAlias` または `assetId` と `propertyId` の両方のいずれかを指定します。プロパティのエイリアスの詳細については、*AWS IoT SiteWise ユーザーガイド*の [Mapping industrial data streams to asset properties](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/connect-data-streams.html) を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`assetId`
(オプション) AWS IoT SiteWise アセットの ID。`propertyAlias` または `assetId` と `propertyId` の両方のいずれかを指定します。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`propertyId`
(オプション) アセットのプロパティの ID。`propertyAlias` または `assetId` と `propertyId` の両方のいずれかを指定します。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`entryId`
(オプション) このエントリの一意な識別子。`entryId` を定義して、障害発生時にエラーの原因となったメッセージをより正確に追跡します。デフォルトは新しい UUID です。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`propertyValues`
次の形式でタイムスタンプ、品質、値 (TQV) を含み、挿入するプロパティ値のリスト。
`timestamp`
次の情報を含むタイムスタンプ構造体。
`timeInSeconds`
時間を秒単位で含む文字列 (Unix エポック時間)。メッセージペイロードにタイムスタンプがない場合は、[timestamp()](iot-sql-functions.md#iot-function-timestamp) を使用して、現在の時間をミリ秒単位で返すことができます。この時間を秒に変換するには、次の置換テンプレートを使用できます: **\$1\$1floor(timestamp() / 1E3)\$1**。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`offsetInNanos`
(オプション) 秒単位の時間からのナノ秒の時間オフセットを含む文字列。メッセージペイロードにタイムスタンプがない場合は、[timestamp()](iot-sql-functions.md#iot-function-timestamp) を使用して、現在の時間をミリ秒単位で返すことができます。その時点からのナノ秒のオフセットを計算するには、次の置換テンプレートを使用できます: **\$1\$1(timestamp() % 1E3) \$1 1E6\$1**。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
Unix エポック時間に関して、 はタイムスタンプが過去最大 7 日、5 分先までのエントリのみ AWS IoT SiteWise を受け入れます。
`quality`
(オプション) 値の品質を表す文字列。有効な値: `GOOD`、`BAD`、`UNCERTAIN`。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`value`
アセットプロパティのデータ型に応じて、次のいずれかの値フィールドを含む値構造体。
`booleanValue`
(オプション) 値エントリのブール値を含む文字列。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`doubleValue`
(オプション) 値エントリの double 値を含む文字列。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`integerValue`
(オプション) 値エントリの整数値を含む文字列。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`stringValue`
(オプション) 値エントリの文字列値。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`roleArn`
アセットプロパティ値を送信する AWS IoT アクセス許可を付与する IAM ロールの ARN AWS IoT SiteWise。詳細については、「[要件](#iotsitewise-rule-action-requirements)」を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
## 例
次の JSON 例では、 AWS IoT ルールで基本的な IoT SiteWise アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"iotSiteWise": {
"putAssetPropertyValueEntries": [
{
"propertyAlias": "/some/property/alias",
"propertyValues": [
{
"timestamp": {
"timeInSeconds": "${my.payload.timeInSeconds}"
},
"value": {
"integerValue": "${my.payload.value}"
}
}
]
}
],
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sitewise"
}
}
]
}
}
```
次の JSON の例では、 AWS IoT ルールで IoT SiteWise アクションを定義します。この例では、トピックをプロパティエイリアスおよび `timestamp()` 関数として使用します。たとえば、`/company/windfarm/3/turbine/7/rpm` にデータをパブリッシュする場合、このアクションは、指定したトピックと同じプロパティエイリアスを持つアセットプロパティにデータを送信します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM '/company/windfarm/+/turbine/+/+'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"iotSiteWise": {
"putAssetPropertyValueEntries": [
{
"propertyAlias": "${topic()}",
"propertyValues": [
{
"timestamp": {
"timeInSeconds": "${floor(timestamp() / 1E3)}",
"offsetInNanos": "${(timestamp() % 1E3) * 1E6}"
},
"value": {
"doubleValue": "${my.payload.value}"
}
}
]
}
],
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sitewise"
}
}
]
}
}
```
## 関連情報
+ 「 AWS IoT SiteWiseユーザーガイド」の「[AWS IoT SiteWise とは](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/what-is-sitewise.html)」
+ *AWS IoT SiteWise ユーザーガイド*の[AWS IoT Core ルールを使用したデータの取り込み](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/iot-rules.html)
+ [「 ユーザーガイド」の AWS IoT SiteWiseAWS IoT 「 へのデータの取り込み](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/ingest-data-from-iot-things.html)*AWS IoT SiteWise *」
+ *AWS IoT SiteWise ユーザーガイド*[の AWS IoT SiteWise ルールアクションのトラブルシューティング](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/troubleshoot-rule.html)
# Firehose
Firehose (`firehose`) アクションは、MQTT メッセージから Amazon Data Firehose ストリーミングにデータを送信します。
## 要件
このルールアクションには、以下の要件があります。
+ オペレーションを実行するために が引き受け AWS IoT ることができる IAM ロール`firehose:PutRecord`。詳細については、「[必要なアクセスを AWS IoT ルールに付与する](iot-create-role.md)」を参照してください。
AWS IoT コンソールで、このルールアクションを実行することを に許可 AWS IoT するロールを選択または作成できます。
+ Firehose を使用して Amazon S3 バケットにデータを送信し、カスタマーマネージドを使用して AWS KMS Amazon S3 に保管中のデータを AWS KMS key 暗号化する場合、Firehose はバケットへのアクセス権と、発信者に代わって AWS KMS key を使用するアクセス許可を持っている必要があります。詳細については、「*Amazon Firehose データファイアハウスデベロッパーガイド*」の「[Amazon S3 送信先に Firehose アクセスを付与する](https://docs.aws.amazon.com/firehose/latest/dev/controlling-access.html#using-iam-s3)」を参照してください。
## パラメータ
このアクションを使用して AWS IoT ルールを作成するときは、次の情報を指定する必要があります。
`batchMode`
(オプション) [https://docs.aws.amazon.com/firehose/latest/APIReference/API_PutRecordBatch.html](https://docs.aws.amazon.com/firehose/latest/APIReference/API_PutRecordBatch.html) を使用して、Firehose ストリーミングをバッチとして配信するかどうか。デフォルト値は `false` です。
`batchMode` が `true` で、ルールの SQL ステートメントが配列に評価される場合、各配列要素は `PutRecordBatch` リクエストで 1 つのレコードを形成します。結果の配列には 500 を超えるレコードを含めることはできません。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
`deliveryStreamName`
メッセージデータの書き込み先として指定する Firehose ストリーム。
[置換テンプレート](iot-substitution-templates.md)をサポート: API および AWS CLI のみ
`separator`
(オプション) Firehose ストリーミングに書き込まれたレコードを区切るために使用される文字区切り記号。このパラメータを省略すると、ストリーミングは区切り記号を使用しません。有効な値: `,` (カンマ)、`\t` (タブ)、`\n` (改行)、`\r\n` (Windows 改行)。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
`roleArn`
Firehose ストリーミングへのアクセスを許可する IAM ロール。詳細については、「[要件](#kinesis-firehose-rule-action-requirements)」を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
## 例
次の JSON の例では、 AWS IoT ルールで Firehose アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"firehose": {
"deliveryStreamName": "my_firehose_stream",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_firehose"
}
}
]
}
}
```
次の JSON の例では、 AWS IoT ルールで置換テンプレートを使用して Firehose アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"firehose": {
"deliveryStreamName": "${topic()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_firehose"
}
}
]
}
}
```
## 関連情報
+ *Amazon Data Firehose デベロッパーガイド*の [Amazon Data Firehose とは](https://docs.aws.amazon.com/firehose/latest/dev/)
# Kinesis Data Streams
Kinesis Data Streams (`kinesis`) アクションは、Amazon Kinesis Data Streams に MQTT メッセージのデータを書き込みます。
## 要件
このルールアクションには、以下の要件があります。
+ オペレーションを実行するために が引き受け AWS IoT ることができる IAM ロール`kinesis:PutRecord`。詳細については、「[必要なアクセスを AWS IoT ルールに付与する](iot-create-role.md)」を参照してください。
AWS IoT コンソールで、このルールアクションを実行することを に許可 AWS IoT するロールを選択または作成できます。
+ AWS KMS カスタマーマネージド AWS KMS key (KMS キー) を使用して Kinesis Data Streams に保管中のデータを暗号化する場合、サービスには AWS KMS key 発信者に代わって を使用するアクセス許可が必要です。詳細については、[*Amazon Kinesis Data Streams Developer Guide*](Amazon Kinesis Data Streams デベロッパーガイド)の[[AWS KMS keys Permissions to use user-generated](https://docs.aws.amazon.com/streams/latest/dev/permissions-user-key-KMS.html)](ユーザーが生成した アクセス許可)を参照してください。
## パラメータ
このアクションを使用して AWS IoT ルールを作成するときは、次の情報を指定する必要があります。
`stream`
データを書き込む Kinesis データストリーミング。
[置換テンプレート](iot-substitution-templates.md)をサポート: API および AWS CLI のみ
`partitionKey`
どのシャードにデータを書き込むかを決定するために使用されるパーティションキー。パーティションキーは通常、式 (例: `${topic()}` または `${timestamp()}`) で構成されます。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`roleArn`
Kinesis データストリームへのアクセス AWS IoT 許可を付与する IAM ロールの ARN。詳細については、「[要件](#kinesis-rule-action-requirements)」を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
## 例
次の JSON の例では、 AWS IoT ルールで Kinesis Data Streams アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"kinesis": {
"streamName": "my_kinesis_stream",
"partitionKey": "${topic()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_kinesis"
}
}
]
}
}
```
次の JSON の例では、 AWS IoT ルールで置換テンプレートを使用して Kinesis アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"kinesis": {
"streamName": "${topic()}",
"partitionKey": "${timestamp()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_kinesis"
}
}
]
}
}
```
## 関連情報
+ *Amazon Kinesis Data Streams デベロッパーガイド*の [Amazon Kinesis Data Streams とは](https://docs.aws.amazon.com/streams/latest/dev/)
# Lambda
Lambda (`lambda`) アクションは AWS Lambda 関数を呼び出し、MQTT メッセージを渡します。 は Lambda 関数を非同期的に AWS IoT 呼び出します。
Lambda アクションを使用してルールを作成およびテストする方法を示すチュートリアルに従うことができます。詳細については、「[チュートリアル: AWS Lambda 関数を使用して通知をフォーマットする](iot-lambda-rule.md)」を参照してください。
## 要件
このルールアクションには、以下の要件があります。
+ AWS IoT が Lambda 関数を呼び出すには、 アクセス`lambda:InvokeFunction`許可を付与するポリシーを設定する必要があります AWS IoT。Lambda ポリシーが存在する AWS リージョン のと同じ で定義された Lambda 関数のみを呼び出すことができます。Lambda 関数はリソースベースのポリシーを使用するため、ポリシーを Lambda 関数自体にアタッチする必要があります。
次の AWS CLI コマンドを使用して、 アクセス`lambda:InvokeFunction`許可を付与するポリシーをアタッチします。このコマンドを、以下のように置き換えます。
+ *function\$1name* を Lambda 関数の名前に置き換えます。関数のリソースポリシーを更新するための新しいアクセス許可を追加します。
+ *region* と 関数 AWS リージョン の 。
+ *account-id* は、ルールが定義されている AWS アカウント 番号です。
+ *rule-name* は、Lambda アクションを定義する AWS IoT ルールの名前です。
+ *unique\$1id* を一意のステートメント識別子で置き換えます。
**重要**
`source-arn` または を指定せずにプリン AWS IoT シパルのアクセス許可を追加すると`source-account`、Lambda アクションを使用してルールを作成する AWS アカウント は、Lambda 関数を呼び出すルールをアクティブ化できます AWS IoT。
詳細については、「[AWS Lambda のアクセス許可](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html)」を参照してください。
```
aws lambda add-permission \
--function-name function_name \
--region region \
--principal iot.amazonaws.com \
--source-arn arn:aws:iot:region:account-id:rule/rule_name \
--source-account account-id
--statement-id unique_id
--action "lambda:InvokeFunction"
```
+ AWS IoT コンソールを使用して Lambda ルールアクションのルールを作成すると、Lambda 関数が自動的にトリガーされます。 AWS CloudFormation の代わりに を使用する場合は[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iot-topicrule-lambdaaction.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iot-topicrule-lambdaaction.html)、 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-permission.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-permission.html)リソースを追加する必要があります。このリソースにより、Lambda 関数をトリガーするアクセス許可が付与されます。
次のコードは、このリソースを追加する方法を示しています。この例では、次のように置き換えます。
+ *function\$1name* を Lambda 関数の名前に置き換えます。
+ 関数 AWS リージョン の を持つ *リージョン*。
+ *account-id* は、ルールが定義されている AWS アカウント 番号です。
+ *rule-name* は、Lambda アクションを定義する AWS IoT ルールの名前です。
```
Type: AWS::Lambda::Permission
Properties:
Action: lambda:InvokeFunction
FunctionName: !Ref function_name
Principal: "iot.amazonaws.com"
SourceAccount: account-id
SourceArn: arn:aws:iot:region:account-id:rule/rule_name
```
+ AWS KMS カスタマーマネージドを使用して Lambda AWS KMS key に保管中のデータを暗号化する場合、サービスには AWS KMS key 発信者に代わって を使用するアクセス許可が必要です。詳しくは、[AWS Lambda Developer Guide]( デベロッパーガイド)の[[Encryption at rest](https://docs.aws.amazon.com/lambda/latest/dg/security-dataprotection.html#security-privacy-atrest)](保管時の暗号化)を参照してください。
## パラメータ
このアクションを使用して AWS IoT ルールを作成するときは、次の情報を指定する必要があります。
`functionArn`
呼び出す Lambda 関数の ARN。 には、関数を呼び出すアクセス許可 AWS IoT が必要です。詳細については、「[要件](#lambda-rule-action-requirements)」を参照してください。
Lambda 関数のバージョンまたはエイリアスを指定しない場合、関数の最新バージョンがシャットダウンされます。Lambda 関数の特定のバージョンをシャットダウンする場合は、バージョンまたはエイリアスを指定できます。バージョンまたはエイリアスを指定するには、Lambda 関数の ARN にバージョンまたはエイリアスを追加します。
```
arn:aws:lambda:us-east-2:123456789012:function:myLambdaFunction:someAlias
```
バージョニングとエイリアスの詳細については、「[AWS Lambda 関数のバージョン](https://docs.aws.amazon.com/lambda/latest/dg/versioning-aliases.html)」を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: API および AWS CLI のみ
## 例
次の JSON の例では、 AWS IoT ルールで Lambda アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:us-east-2:123456789012:function:myLambdaFunction"
}
}
]
}
}
```
次の JSON の例では、 AWS IoT ルールで置換テンプレートを使用して Lambda アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:us-east-1:123456789012:function:${topic()}"
}
}
]
}
}
```
## 関連情報
+ デ*AWS Lambda ベロッパーガイド*の[「 AWS Lambdaとは](https://docs.aws.amazon.com/lambda/latest/dg/)」
+ [チュートリアル: AWS Lambda 関数を使用して通知をフォーマットする](iot-lambda-rule.md)
# ロケーション
Location (`location`) アクションによって、地理的位置データを [Amazon Location Service](https://docs.aws.amazon.com//location/latest/developerguide/welcome.html) に送信します。
## 要件
このルールアクションには、以下の要件があります。
+ オペレーションを実行するために が引き受け AWS IoT ることができる IAM ロール`geo:BatchUpdateDevicePosition`。詳細については、「[必要なアクセスを AWS IoT ルールに付与する](iot-create-role.md)」を参照してください。
AWS IoT コンソールでは、このルールアクションを実行することを に許可 AWS IoT するロールを選択または作成できます。
## パラメータ
このアクションを使用して AWS IoT ルールを作成するときは、次の情報を指定する必要があります。
`deviceId`
位置データを提供するデバイスの一意の ID。詳細については、*「Amazon Location Service API リファレンス」*の「[https://docs.aws.amazon.com//location/latest/APIReference/API_DevicePositionUpdate.html](https://docs.aws.amazon.com//location/latest/APIReference/API_DevicePositionUpdate.html)」を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`latitude`
デバイスの位置の緯度を表す double 値として評価される文字列。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`longitude`
デバイスの位置の経度を表す double 値として評価される文字列。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`roleArn`
Amazon Location Service ドメインへのアクセスを許可する IAM ロール。詳細については、「[要件](#location-rule-action-requirements)」を参照してください。
`timestamp`
位置データがサンプリングされた時刻。デフォルト値は MQTT メッセージが処理された時間です。
`timestamp` 値は、次の 2 つの値で構成されます。
+ `value`: 長いエポック時間の値を返す式。[time\$1to\$1epoch(String, String)](iot-sql-functions.md#iot-sql-function-time-to-epoch) 関数を使用して、メッセージペイロードで渡される日付または時刻の値から有効なタイムスタンプを作成できます。[置換テンプレート](iot-substitution-templates.md)のサポート: はい
+ `unit` (オプション): `value` で説明されている式の結果として生じるタイムスタンプ値の精度。有効な値: `SECONDS` \$1 `MILLISECONDS` \$1 `MICROSECONDS` \$1 `NANOSECONDS`。デフォルトは`MILLISECONDS`です。[置換テンプレート](iot-substitution-templates.md)をサポート: API および AWS CLI のみ。
`trackerName`
Location が更新される Amazon Location トラッカーリソースの名前。詳細については、「*Amazon Location Service デベロッパーガイド*」の「[トラッカー](https://docs.aws.amazon.com//location/latest/developerguide/geofence-tracker-concepts.html#tracking-overview)」を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: API および AWS CLI のみ
## 例
次の JSON の例では、 AWS IoT ルールで Location アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"location": {
"roleArn": "arn:aws:iam::123454962127:role/service-role/ExampleRole",
"trackerName": "MyTracker",
"deviceId": "001",
"sampleTime": {
"value": "${timestamp()}",
"unit": "MILLISECONDS"
},
"latitude": "-12.3456",
"longitude": "65.4321"
}
}
]
}
}
```
次の JSON の例では、 AWS IoT ルールで置換テンプレートを使用して Location アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"location": {
"roleArn": "arn:aws:iam::123456789012:role/service-role/ExampleRole",
"trackerName": "${TrackerName}",
"deviceId": "${DeviceID}",
"timestamp": {
"value": "${timestamp()}",
"unit": "MILLISECONDS"
},
"latitude": "${get(position, 0)}",
"longitude": "${get(position, 1)}"
}
}
]
}
}
```
次の MQTT ペイロードの例では、上記の例の置換テンプレートがデータにアクセスする方法を示しています。[https://docs.aws.amazon.com/cli/latest/reference/location/get-device-position-history.html](https://docs.aws.amazon.com/cli/latest/reference/location/get-device-position-history.html) CLI コマンドを使用して、MQTT ペイロードデータがロケーショントラッカーに配信されていることを確認できます。
```
{
"TrackerName": "mytracker",
"DeviceID": "001",
"position": [
"-12.3456",
"65.4321"
]
}
```
```
aws location get-device-position-history --device-id 001 --tracker-name mytracker
```
```
{
"DevicePositions": [
{
"DeviceId": "001",
"Position": [
-12.3456,
65.4321
],
"ReceivedTime": "2022-11-11T01:31:54.464000+00:00",
"SampleTime": "2022-11-11T01:31:54.308000+00:00"
}
]
}
```
## 関連情報
+ *Amazon Location Service デベロッパーガイド*の「[Amazon Location Service とは?](https://docs.aws.amazon.com//location/latest/developerguide/welcome.html)」
# OpenSearch
OpenSearch (`openSearch`) アクションは、Amazon OpenSearch Service ドメインに MQTT メッセージからデータを書き込みます。その後、OpenSearch Dashboards などのツールを使用して、OpenSearch Service のデータをクエリおよび視覚化できます。
## 要件
このルールアクションには、以下の要件があります。
+ オペレーションを実行するために が引き受け AWS IoT ることができる IAM ロール`es:ESHttpPut`。詳細については、「[必要なアクセスを AWS IoT ルールに付与する](iot-create-role.md)」を参照してください。
AWS IoT コンソールで、このルールアクションを実行することを に許可 AWS IoT するロールを選択または作成できます。
+ OpenSearch Service でカスタマーマネージドを使用して保管中のデータを AWS KMS key 暗号化する場合、サービスには発信者に代わって KMS キーを使用するアクセス許可が必要です。詳細については、[Amazon OpenSearch Service デベロッパーガイド](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/encryption-at-rest.html)の「*Amazon OpenSearch Service の保管中のデータの暗号化*」を参照してください。
## パラメータ
このアクションを使用して AWS IoT ルールを作成するときは、次の情報を指定する必要があります。
`endpoint`
Amazon OpenSearch Service ドメインのエンドポイント。
[代替テンプレート](iot-substitution-templates.md)をサポート: API および AWS CLI のみ
`index`
データを保存する OpenSearch インデックス。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`type`
保存するドキュメントのタイプ。
1.0 以降の OpenSearch バージョンでは、`type` パラメータの値は `_doc` である必要があります。詳細については、「[OpenSearch ドキュメント](https://opensearch.org/docs/1.0/opensearch/rest-api/document-apis/index-document/#response-body-fields)」を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`id`
各ドキュメントの一意の識別子。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`roleARN`
OpenSearch Service ドメインへのアクセスを許可する IAM ロール。詳細については、「[要件](#opensearch-rule-action-requirements)」を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
## 制限事項
OpenSearch (`openSearch`) アクションを使用して VPC Elasticsearch クラスターにデータを配信することはできません。
## 例
次の JSON の例では、 AWS IoT ルールで OpenSearch アクションを定義し、`OpenSearch`アクションのフィールドを指定する方法を定義します。詳細については、[[OpenSearchAction](https://docs.aws.amazon.com/iot/latest/apireference/API_OpenSearchAction.html)]を参照してください。
```
{
"topicRulePayload": {
"sql": "SELECT *, timestamp() as timestamp FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"openSearch": {
"endpoint": "https://my-endpoint",
"index": "my-index",
"type": "_doc",
"id": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_os"
}
}
]
}
}
```
次の JSON の例では、 AWS IoT ルールで置換テンプレートを使用して OpenSearch アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"openSearch": {
"endpoint": "https://my-endpoint",
"index": "${topic()}",
"type": "${type}",
"id": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_os"
}
}
]
}
}
```
**注記**
置換した `type` フィールドは OpenSearch バージョン 1.0 で機能します。1.0 以降のバージョンでは、`type` の値は `_doc` である必要があります。
## 関連情報
[Amazon OpenSearch Service デベロッパーガイド](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/)の「*Amazon OpenSearch Service とは?*」
# 再発行
再発行 (`republish`) アクションは、MQTT メッセージを別の MQTT トピックに再発行します。
## 要件
このルールアクションには、以下の要件があります。
+ オペレーションを実行するために が引き受け AWS IoT ることができる IAM ロール`iot:Publish`。詳細については、「[必要なアクセスを AWS IoT ルールに付与する](iot-create-role.md)」を参照してください。
AWS IoT コンソールで、このルールアクションを実行することを に許可 AWS IoT するロールを選択または作成できます。
## パラメータ
このアクションを使用して AWS IoT ルールを作成するときは、次の情報を指定する必要があります。
`headers`
MQTT バージョン 5.0 のヘッダー情報。
詳細については、「*AWS API リファレンス*」の「[RepublishAction](https://docs.aws.amazon.com//iot/latest/apireference/API_RepublishAction.html)」と「[MqttHeaders](https://docs.aws.amazon.com//iot/latest/apireference/API_MqttHeaders.html)」を参照してください。
`topic`
メッセージの再発行先として指定する MQTT トピック。
`$` で始まる予約済みトピックに再発行するには、代わりに `$$` を使用します。例えば、デバイスシャドウトピック `$aws/things/MyThing/shadow/update` に再発行する場合は、トピックを `$$aws/things/MyThing/shadow/update` として指定します。
[予約済みのジョブトピック](reserved-topics.md#reserved-topics-job)への再発行はサポートされていません。
AWS IoT Device Defender 予約トピックは HTTP パブリッシュをサポートしていません。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`qos`
(オプション) メッセージを再発行するときに使用する Quality of Service (QoS) レベル。有効な値: `0`、`1`。デフォルト値は `0` です。MQTT QoS の詳細については、「[MQTT](mqtt.md)」を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
`roleArn`
が MQTT トピックに発行 AWS IoT できるようにする IAM ロール。詳細については、「[要件](#republish-rule-action-requirements)」を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
## 例
次の JSON の例では、 AWS IoT ルールで再発行アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"topic": "another/topic",
"qos": 1,
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_republish"
}
}
]
}
}
```
次の JSON の例では、 AWS IoT ルールで置換テンプレートを使用して再発行アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"topic": "${topic()}/republish",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_republish"
}
}
]
}
}
```
次の JSON の例では、 AWS IoT ルール`headers`で を使用して再発行アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"topic": "${topic()}/republish",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_republish",
"headers": {
"payloadFormatIndicator": "UTF8_DATA",
"contentType": "rule/contentType",
"correlationData": "cnVsZSBjb3JyZWxhdGlvbiBkYXRh",
"userProperties": [
{
"key": "ruleKey1",
"value": "ruleValue1"
},
{
"key": "ruleKey2",
"value": "ruleValue2"
}
]
}
}
}
]
}
}
```
**注記**
元の送信元 IP は [Republish アクション](#republish-rule-action)には渡されません。
# S3
S3 (`s3`) アクションは、MQTT メッセージのデータを Amazon Simple Storage Service (Amazon S3) バケットに書き込みます。
## 要件
このルールアクションには、以下の要件があります。
+ オペレーションを実行するために が引き受け AWS IoT ることができる IAM ロール`s3:PutObject`。詳細については、「[必要なアクセスを AWS IoT ルールに付与する](iot-create-role.md)」を参照してください。
AWS IoT コンソールで、このルールアクションを実行することを に許可 AWS IoT するロールを選択または作成できます。
+ AWS KMS カスタマーマネージド を使用して Amazon S3 AWS KMS key に保管中のデータを暗号化する場合、サービスには発信者に代わって AWS KMS key を使用するアクセス許可が必要です。詳細については、*「Amazon Simple Storage Service デベロッパーガイド*」の「マネージド[AWSAWS KMS keys 」と「カスタマーマネージド AWS KMS keys](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html#aws-managed-customer-managed-cmks)」を参照してください。
## パラメータ
このアクションを使用して AWS IoT ルールを作成するときは、次の情報を指定する必要があります。
`bucket`
データの書き込み先として指定する Amazon S3 バケット。
[置換テンプレート](iot-substitution-templates.md)をサポート: API および AWS CLI のみ
`cannedacl`
(オプション) オブジェクトキーによって識別されるオブジェクトへのアクセスをコントロールする Amazon S3 既定 ACL。使用できる値などの詳細については、[既定 ACL](https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl) を参照してください (許可値の一覧が記載されています)。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
`key`
データの書き込み先として指定するファイルのパス。
このパラメータが `${topic()}/${timestamp()}` であり、トピックが `some/topic` であるメッセージをルールが受信する例を考えてください。現在のタイムスタンプが `1460685389` の場合、このアクションはデータを S3 バケットの `some/topic` フォルダの `1460685389` というファイルに書き込みます。
静的キーを使用する場合、 はルールが呼び出されるたびに 1 つのファイルを AWS IoT 上書きします。受信したメッセージごとに新しいファイルが Amazon S3 に保存されるように、メッセージのタイムスタンプまたは別の一意のメッセージ識別子を使用することをお勧めします。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`roleArn`
Amazon S3 バケットへのアクセスを許可する IAM ロール。詳細については、「[要件](#s3-rule-action-requirements)」を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
## 例
次の JSON の例では、 AWS IoT ルールで S3 アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"s3": {
"bucketName": "amzn-s3-demo-bucket",
"cannedacl": "public-read",
"key": "${topic()}/${timestamp()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_s3"
}
}
]
}
}
```
## 関連情報
+ *Amazon Simple Storage Service デベロッパーガイド*の[ Amazon S3 とは?](https://docs.aws.amazon.com/AmazonS3/latest/userguide/)
# Salesforce IoT
Salesforce IoT (`salesforce`) アクションは、ルールをトリガーした MQTT メッセージから Salesforce IoT 入力ストリーミングにデータを送信します。
## パラメータ
このアクションを使用して AWS IoT ルールを作成するときは、次の情報を指定する必要があります。
`url`
Salesforce IoT 入力ストリームによって公開される URL。この URL は、入力ストリームの作成時に Salesforce IoT プラットフォームから入手できます。詳細については、Salesforce IoT ドキュメントを参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
`token`
指定した Salesforce IoT 入力ストリームへのアクセスを認証するために使用されるトークン。このトークンは、入力ストリームの作成時に Salesforce IoT プラットフォームから入手できます。詳細については、Salesforce IoT ドキュメントを参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
## 例
次の JSON 例では、 AWS IoT ルールで Salesforce IoT アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"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"
}
}
]
}
}
```
# SNS
SNS (`sns`) アクションは、Amazon Simple Notification Service (Amazon SNS) プッシュ通知として MQTT メッセージからデータを送信します。
SNS アクションを使用してルールを作成およびテストする方法を示すチュートリアルに従うことができます。詳細については、「[チュートリアル: Amazon SNS 通知の送信](iot-sns-rule.md)」を参照してください。
**注記**
SNS アクションは、[Amazon SNS FIFO (First-In-First-Out) トピック](https://docs.aws.amazon.com/sns/latest/dg/sns-fifo-topics.html)をサポートしていません。ルールエンジンは完全に分散されたサービスであるため、SNS アクションが呼び出されたときのメッセージ順序の保証はありません。
## 要件
このルールアクションには、以下の要件があります。
+ オペレーションを実行するために が引き受け AWS IoT ることができる IAM ロール`sns:Publish`。詳細については、「[必要なアクセスを AWS IoT ルールに付与する](iot-create-role.md)」を参照してください。
AWS IoT コンソールで、このルールアクションを実行することを に許可 AWS IoT するロールを選択または作成できます。
+ AWS KMS カスタマーマネージドマネージドを使用して Amazon SNS AWS KMS key に保管中のデータを暗号化する場合、サービスには AWS KMS key 発信者に代わって を使用するアクセス許可が必要です。詳細については、[*Amazon Simple Notification Service Developer Guide*](Amazon 簡易通知サービスデベロッパーガイド)の[[Key management](https://docs.aws.amazon.com/sns/latest/dg/sns-key-management.html)](キー管理)を参照してください。
## パラメータ
このアクションを使用して AWS IoT ルールを作成するときは、次の情報を指定する必要があります。
`targetArn`
プッシュ通知の送信先として指定する SNS トピックまたは個々のデバイス。
[置換テンプレート](iot-substitution-templates.md)をサポート: API および AWS CLI のみ
`messageFormat`
(オプション) メッセージ形式。Amazon SNS ではこの設定を使用して、ペイロードを解析して関連するプラットフォーム固有の部分をペイロードから抽出するかどうかを判断します。有効な値: `JSON`、`RAW`。デフォルトは `RAW` です。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
`roleArn`
SNS へのアクセスを許可する IAM ロール。詳細については、「[要件](#sns-rule-action-requirements)」を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
## 例
次の JSON の例では、 AWS IoT ルールで SNS アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sns": {
"targetArn": "arn:aws:sns:us-east-2:123456789012:my_sns_topic",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sns"
}
}
]
}
}
```
次の JSON の例では、 AWS IoT ルールで置換テンプレートを使用して SNS アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sns": {
"targetArn": "arn:aws:sns:us-east-1:123456789012:${topic()}",
"messageFormat": "JSON",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sns"
}
}
]
}
}
```
## 関連情報
+ *Amazon Simple Notification Service デベロッパーガイド*の [Amazon Simple Notification Service とは](https://docs.aws.amazon.com/sns/latest/dg/)
+ [チュートリアル: Amazon SNS 通知の送信](iot-sns-rule.md)
# SQS
SQS (`sqs`) アクションは、Amazon Simple Queue Service (Amazon SQS) キューに MQTT メッセージのデータを送信します。
**注記**
SQS アクションは、[Amazon SQS FIFO (First-In-First-Out) キュー](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queues.html)をサポートしていません。ルールエンジンは完全に分散されたサービスであるため、SQS アクションがトリガーされたときのメッセージ順序の保証はありません。
## 要件
このルールアクションには、以下の要件があります。
+ オペレーションを実行するために が引き受け AWS IoT ることができる IAM ロール`sqs:SendMessage`。詳細については、「[必要なアクセスを AWS IoT ルールに付与する](iot-create-role.md)」を参照してください。
AWS IoT コンソールで、このルールアクションを実行することを に許可 AWS IoT するロールを選択または作成できます。
+ AWS KMS カスタマーマネージドを使用して Amazon SQS AWS KMS key で保管中のデータを暗号化する場合、サービスには AWS KMS key 発信者に代わって を使用するアクセス許可が必要です。詳細については、*Amazon Simple Storage Service デベロッパーガイド*の[キー管理](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-key-management.html)を参照してください。
## パラメータ
このアクションを使用して AWS IoT ルールを作成するときは、次の情報を指定する必要があります。
`queueUrl`
データの書き込み先として指定する Amazon SQS キューの URL。この URL のリージョンは、[AWS IoT ルール](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html) AWS リージョン と同じである必要はありません。
SQS ルールアクションを使用したデータ転送クロス AWS リージョン には追加料金が発生する場合があります。詳細については、「[Amazon SQSの料金](https://aws.amazon.com/sqs/pricing/)」を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: API および AWS CLI のみ
`useBase64`
このパラメータを `true` に設定して、データを Amazon SQS キューに書き込む前にメッセージデータを base64 エンコードするルールアクションを設定します。デフォルトは `false` です。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
`roleArn`
Amazon SQS キューへのアクセスを許可する IAM ロール。詳細については、「[要件](#sqs-rule-action-requirements)」を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
## 例
次の JSON の例では、 AWS IoT ルールで SQS アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sqs": {
"queueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/my_sqs_queue",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sqs"
}
}
]
}
}
```
次の JSON の例では、 AWS IoT ルールで置換テンプレートを使用して SQS アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sqs": {
"queueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/${topic()}",
"useBase64": true,
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sqs"
}
}
]
}
}
```
## 関連情報
+ *Amazon Simple Queue Service デベロッパーガイド*の [Amazon Simple Queue Service とは](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/)
# ステップ関数
Step Functions (`stepFunctions`) アクションは AWS Step Functions ステートマシンを起動します。
## 要件
このルールアクションには、以下の要件があります。
+ オペレーションを実行するために が引き受け AWS IoT ることができる IAM ロール`states:StartExecution`。詳細については、「[必要なアクセスを AWS IoT ルールに付与する](iot-create-role.md)」を参照してください。
AWS IoT コンソールで、このルールアクションを実行することを に許可 AWS IoT するロールを選択または作成できます。
## パラメータ
このアクションを使用して AWS IoT ルールを作成するときは、次の情報を指定する必要があります。
`stateMachineName`
開始する Step Functions ステートマシンの名前。
[置換テンプレート](iot-substitution-templates.md)をサポート: API および AWS CLI のみ
`executionNamePrefix`
(オプション) ステートマシンの実行に指定される、このプレフィックスとそれに続く UUID で構成される名前。Step Functions は、各ステートマシンの実行用に一意の名前を作成します (指定されていない場合)。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`roleArn`
ステートマシンを起動する AWS IoT アクセス許可を付与するロールの ARN。詳細については、「[要件](#stepfunctions-rule-action-requirements)」を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
## 例
次の JSON の例では、 AWS IoT ルールで Step Functions アクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"stepFunctions": {
"stateMachineName": "myStateMachine",
"executionNamePrefix": "myExecution",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_step_functions"
}
}
]
}
}
```
## 関連情報
+ デ*AWS Step Functions ベロッパーガイド*の[「 AWS Step Functionsとは](https://docs.aws.amazon.com/step-functions/latest/dg/)」
# Timestream
Timestream ルールアクションは、MQTT メッセージの属性 (メジャー) を Amazon Timestream テーブルに書き込みます。Amazon Timestream の詳細については、[Amazon Timestream とは](https://docs.aws.amazon.com/timestream/latest/developerguide/what-is-timestream.html)を参照してください。
**注記**
Amazon Timestream は、すべての AWS リージョンで利用できるわけではありません。リージョンで Amazon Timestream を利用できない場合は、ルールアクションのリストには表示されません。
このルールが Timestream データベースに保存する属性は、ルールのクエリステートメントから得られた属性です。クエリステートメントの結果の各属性の値は、そのデータタイプを ([DynamoDBv2](dynamodb-v2-rule-action.md) アクションにおけるのと同様に) 推測するために解析されます。各属性の値は、Timestream テーブルの独自のレコードに書き込まれます。属性のデータ型を指定または変更するには、クエリステートメントで[`cast()`](iot-sql-functions.md#iot-sql-function-cast)関数を使用します。各 Timestream レコードの内容の詳細については、「[Timestream レコードコンテンツ](#timestream-rule-action-data)」を参照してください。
**注記**
SQL V2 (2016-03-23) では、`10.0` などの整数である数値は整数表現 (`10`) に変換されます。[cast()](iot-sql-functions.md#iot-sql-function-cast) 関数を使用するなどして、それらを `Decimal`値に明示的にキャストしても、この動作は妨げられず、結果は `Integer` 値のままです。これにより、データが Timestream データベースに記録されるのを妨げる、タイプの不一致エラーが発生する可能性があります。整数の数値を `Decimal` 値として処理するには、ルールクエリステートメントに SQL V1 (2015-10-08) を使用します。
**注記**
タイムストリームルールアクションが Amazon Timestream テーブルに書き込むことができる値の最大数は 100 です。詳細については、[Amazon Timestream クォータのリファレンス](https://docs.aws.amazon.com//timestream/latest/developerguide/ts-limits.html#limits.default)を参照してください。
## 要件
このルールアクションには、以下の要件があります。
+ が `timestream:DescribeEndpoints`および `timestream:WriteRecords`オペレーションを実行するために引き受け AWS IoT ることができる IAM ロール。詳細については、「[必要なアクセスを AWS IoT ルールに付与する](iot-create-role.md)」を参照してください。
AWS IoT コンソールでは、このルールアクションを実行 AWS IoT することを に許可するロールを選択、更新、または作成できます。
+ Timestream で顧客 AWS KMS を使用して保管中のデータを暗号化する場合、サービスには AWS KMS key 発信者に代わって を使用するアクセス許可が必要です。詳細については、「 [AWS サービスが KMS AWS を使用する方法](https://docs.aws.amazon.com/kms/latest/developerguide/service-integration.html)」を参照してください。
## パラメータ
このアクションで AWS IoT ルールを作成するときは、次の情報を指定する必要があります。
`databaseName`
このアクションが作成したレコードを受信するテーブルを持つ Amazon Timestream データベースの名前。「`tableName`」も参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: API および AWS CLI のみ
`dimensions`
各メジャーレコードに書き込まれる時系列のメタデータ属性。例えば、EC2 インスタンスの名前とアベイラビリティーゾーン、または風力タービンの製造元の名前はディメンションです。
`name`
メタデータディメンション名。これはデータベーステーブルレコード内の列の名前です。
ディメンションに、`measure_name`、`measure_value`、`time` の名前を付けることはできません。これらの名前は予約されています。ディメンション名は、`ts_` または `measure_value` で始めることはできず、コロン (`:`) 文字を含めることはできません。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
`value`
データベースレコードのこの列に書き込む値。
[置換テンプレート](iot-substitution-templates.md)をサポート: はい
`roleArn`
Timestream データベーステーブルに書き込むためのアクセス許可を AWS IoT に付与するロールの Amazon リソースネーム (ARN)。詳細については、「[要件](#timestream-rule-action-requirements)」を参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: いいえ
`tableName`
メジャーレコードを書き込むデータベーステーブルの名前。「`databaseName`」も参照してください。
[置換テンプレート](iot-substitution-templates.md)をサポート: API および AWS CLI のみ
`timestamp`
エントリのタイムスタンプに使用する値。空白の場合、エントリが処理された時刻が使用されます。
`unit`
`value` で説明されている式から得られるタイムスタンプ値の精度。
有効な値: `SECONDS` \$1 `MILLISECONDS` \$1 `MICROSECONDS` \$1 `NANOSECONDS`。デフォルトは`MILLISECONDS`です。
`value`
長いエポック時間の値を返す式。
[time\$1to\$1epoch(String, String)](iot-sql-functions.md#iot-sql-function-time-to-epoch) 関数を使用して、メッセージペイロードで渡される日付または時刻の値から有効なタイムスタンプを作成できます。
## Timestream レコードコンテンツ
このアクションによって Amazon Timestream テーブルに書き込まれるデータには、タイムスタンプ、Timestream ルールアクションからのメタデータ、およびルールのクエリステートメントの結果が含まれます。
クエリステートメントの結果の各属性 (メジャー) について、このルールアクションは、これらの列を持つ指定された Timestream テーブルにレコードを書き込みます。
| 列名 | 属性タイプ | 値 | コメント |
| --- | --- | --- | --- |
| *dimension-name* | ディメンション | Timestream ルールアクションエントリで指定された値。 | ルールアクションエントリで指定された各 [**Dimension**] (ディメンション) は、ディメンションの名前で Timestream データベースに列を作成します。 |
| measure\$1name | MEASURE\$1NAME | 属性の名前 | `measure_value::data-type` 列で値が指定されているクエリステートメントの結果の属性の名前。 |
| measure\$1value::*data-type* | MEASURE\$1VALUE | クエリステートメントの結果に含まれる属性の値。属性の名前は `measure_name` 列にあります。 | 値は解釈\$1され、次に対する最適なマッチとしてキャストされます: `bigint`、`boolean`、`double`、`varchar`。Amazon Timestream は、データ型ごとに個別の列を作成します。メッセージ内の値は、ルールのクエリステートメントで[`cast()`](iot-sql-functions.md#iot-sql-function-cast) 関数を使用して別のデータ型にキャストできます。 |
| time | TIMESTAMP | データベース内のレコードの日時。 | この値は、ルールエンジンまたは `timestamp` プロパティ (定義されている場合) によって割り当てられます。 |
\$1 メッセージペイロードから読み取られた属性値は以下のように解釈されます。これらの各ケースの図については、「[例](#timestream-rule-action-examples)」を参照してください。
+ `true` または `false` の引用符で囲まれていない値は、`boolean` タイプとして解釈されます。
+ 10 進数値は `double` タイプとして解釈されます。
+ 小数点のない数値は `bigint` タイプとして解釈されます。
+ 引用符で囲まれた文字列は `varchar` タイプとして解釈されます。
+ オブジェクトと配列の値は JSON 文字列に変換され、`varchar` タイプとして保存されます。
## 例
次の JSON の例では、ルール内の置換テンプレートを使用して Timestream AWS IoT ルールアクションを定義します。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'iot/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"timestream": {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_timestream",
"tableName": "devices_metrics",
"dimensions": [
{
"name": "device_id",
"value": "${clientId()}"
},
{
"name": "device_firmware_sku",
"value": "My Static Metadata"
}
],
"databaseName": "record_devices"
}
}
]
}
}
```
前の例で定義された Timestream トピックルールアクションを次のメッセージペイロードで使用すると、Amazon Timestream レコードが次の表に書き込まれます。
```
{
"boolean_value": true,
"integer_value": 123456789012,
"double_value": 123.456789012,
"string_value": "String value",
"boolean_value_as_string": "true",
"integer_value_as_string": "123456789012",
"double_value_as_string": "123.456789012",
"array_of_integers": [23,36,56,72],
"array of strings": ["red", "green","blue"],
"complex_value": {
"simple_element": 42,
"array_of_integers": [23,36,56,72],
"array of strings": ["red", "green","blue"]
}
}
```
次の表は、指定されたトピックルールアクションを使用して以前のメッセージペイロードが作成したものの処理を行うデータベースの列とレコードを示しています。`device_firmware_sku` および `device_id` 列は、トピックルールアクションで定義された DIMENSIONS です。Timestream トピックルールアクションは、`time` 列と `measure_name` および `measure_value::*` 列を作成し、トピックルールアクションのクエリステートメントの結果からの値を入力します。
| device\$1firmware\$1sku | device\$1id | measure\$1name | measure\$1value::bigint | measure\$1value::varchar | measure\$1value::double | measure\$1value::boolean | time |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 静的メタデータ | iotconsole-159EXAMPLE738-0 | complex\$1value | - | \$1"simple\$1element":42,"array\$1of\$1integers":[23,36,56,72],"array of strings":["red","green","blue"]\$1 | - | - | 2020-08-26 22:42:16.423000000 |
| 静的メタデータ | iotconsole-159EXAMPLE738-0 | integer\$1value\$1as\$1string | - | 123456789012 | - | - | 2020-08-26 22:42:16.423000000 |
| 静的メタデータ | iotconsole-159EXAMPLE738-0 | boolean\$1value | - | - | - | TRUE | 2020-08-26 22:42:16.423000000 |
| 静的メタデータ | iotconsole-159EXAMPLE738-0 | integer\$1value | 123456789012 | - | - | - | 2020-08-26 22:42:16.423000000 |
| 静的メタデータ | iotconsole-159EXAMPLE738-0 | string\$1value | - | 文字列値 | - | - | 2020-08-26 22:42:16.423000000 |
| 静的メタデータ | iotconsole-159EXAMPLE738-0 | array\$1of\$1integers | - | [23,36,56,72] | - | - | 2020-08-26 22:42:16.423000000 |
| 静的メタデータ | iotconsole-159EXAMPLE738-0 | 文字列の配列 | - | ["red","green","blue"] | - | - | 2020-08-26 22:42:16.423000000 |
| 静的メタデータ | iotconsole-159EXAMPLE738-0 | boolean\$1value\$1as\$1string | - | TRUE | - | - | 2020-08-26 22:42:16.423000000 |
| 静的メタデータ | iotconsole-159EXAMPLE738-0 | double\$1value | - | - | 123.456789012 | - | 2020-08-26 22:42:16.423000000 |
| 静的メタデータ | iotconsole-159EXAMPLE738-0 | double\$1value\$1as\$1string | - | 123.45679 | - | - | 2020-08-26 22:42:16.423000000 |
## ルールのトラブルシューティング
ルールに問題が発生した場合は、CloudWatch Logs を有効にすることをお勧めします。ログを分析して、認可に関する問題かどうか、WHERE 句の条件に一致する結果が見つからない問題かどうかなどを判断できます。詳細については、[CloudWatch Logs のセットアップ](https://docs.aws.amazon.com/iot/latest/developerguide/cloud-watch-logs.html)を参照してください。
# AWS IoT ルールを使用したクロスアカウントリソースへのアクセス
クロスアカウントアクセスの AWS IoT ルールを設定して、あるアカウントの MQTT トピックに取り込まれたデータを別のアカウントの Amazon SQS や Lambda などの AWS サービスにルーティングできます。次に、あるアカウントの MQTT トピックから別のアカウントの宛先へのクロスアカウントデータ取り込みの AWS IoT ルールを設定する方法について説明します。
クロスアカウントルールは、宛先リソースの[リソースベースのアクセス許可](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_controlling.html#TypesPermissions)を使用して設定できます。したがって、 AWS IoT ルールを使用してクロスアカウントアクセスを有効にすることができるのは、リソースベースのアクセス許可をサポートする送信先のみです。サポートされる宛先には、Amazon SQS、Amazon SNS、Amazon S3、および AWS Lambdaがあります。
**注記**
Amazon SQS を除くサポートされている送信先については、ルールアクションがそのリソースとやり取りできるように、別のサービスのリソース AWS リージョン と同じ でルールを定義する必要があります。 AWS IoT ルールアクションの詳細については、[AWS IoT 「 ルールアクション](iot-rule-actions.md)」を参照してください。ルールの SQS アクションの詳細については、「[SQS](sqs-rule-action.md)」を参照してください。
## 前提条件
+ [AWS IoT ルール](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html)に詳しいこと
+ IAM [ユーザー](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_identity-management.html),[ロール](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html),および[リソースベースのアクセス許可](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_permissions.html#TypesPermissions)を理解していること
+ [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) がインストールされていること
## Amazon SQS のクロスアカウント設定
シナリオ: アカウント A が、MQTT メッセージからアカウント B の Amazon SQS キューにデータを送信します。
| AWS アカウント | アカウントの呼び方 | 説明 |
| --- | --- | --- |
| 1111-1111-1111 | アカウント A | ルールアクション: sqs:SendMessage |
| 2222-2222-2222 | アカウント B | Amazon SQS キュー [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot/latest/developerguide/accessing-cross-account-resources-using-rules.html) |
**注記**
送信先の Amazon SQS キューが[AWS IoT ルール](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html) AWS リージョン と同じ に存在する必要はありません。ルールの SQS アクションの詳細については、「[SQS](sqs-rule-action.md)」を参照してください。
**アカウント A のタスクを実行する**
**メモ**
次のコマンドを実行するには、リソースがルールの Amazon リソースネーム (ARN) である `iot:CreateTopicRule` へのアクセス許可と、リソースがロールの ARN である `iam:PassRole` アクションへのアクセス許可が IAM ユーザーに必要です。
1. アカウント A の IAM ユーザーを使用して、[AWS CLIを設定](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)します。
1. AWS IoT ルールエンジンを信頼する IAM ロールを作成し、アカウント B の Amazon SQS キューへのアクセスを許可するポリシーをアタッチします。[「必要なアクセス権を付与する」の「コマンドとポリシードキュメントの例 AWS IoT](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html)」を参照してください。
1. トピックにアタッチされるルールを作成するために、[create-topic-rule コマンド](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html)を実行します。
```
aws iot create-topic-rule --rule-name myRule --topic-rule-payload file://./my-rule.json
```
次のペイロードファイル例では、`iot/test` トピックに送信されたすべてのメッセージを指定の Amazon SQS キューに挿入するルールが指定されています。SQL ステートメントによってメッセージがフィルター処理され、ロールの ARN によって Amazon SQS キューにメッセージを追加するアクセス許可が AWS IoT に付与されます。
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sqs": {
"queueUrl": "https://sqs.region.amazonaws.com/2222-2222-2222/ExampleQueue",
"roleArn": "arn:aws:iam::1111-1111-1111:role/my-iot-role",
"useBase64": false
}
}
]
}
```
AWS IoT ルールで Amazon SQS アクションを定義する方法の詳細については、[AWS IoT 「ルールアクション - Amazon SQS](https://docs.aws.amazon.com/iot/latest/developerguide/sqs-rule-action.html)」を参照してください。
**アカウント B のタスクを実行する**
1. アカウント B の IAM ユーザーを使用して、[AWS CLIを設定](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)します。
1. Amazon SQS キューリソースへのアクセス許可をアカウント A に付与するために、[add-permission コマンド](https://docs.aws.amazon.com/cli/latest/reference/sqs/add-permission.html)を実行します。
```
aws sqs add-permission --queue-url https://sqs.region.amazonaws.com/2222-2222-2222/ExampleQueue --label SendMessagesToMyQueue --aws-account-ids 1111-1111-1111 --actions SendMessage
```
## Amazon SNS のクロスアカウント設定
シナリオ: アカウント A が、MQTT メッセージからアカウント B の Amazon SNS トピックにデータを送信します。
| AWS アカウント | アカウントの呼び方 | 説明 |
| --- | --- | --- |
| 1111-1111-1111 | アカウント A | ルールアクション: sns:Publish |
| 2222-2222-2222 | アカウント B | Amazon SNS トピックの ARN: arn:aws:sns:region:2222-2222-2222:ExampleTopic |
**アカウント A のタスクを実行する**
**注意事項**
次のコマンドを実行するには、リソースがルールの ARN である `iot:CreateTopicRule` へのアクセス許可と、リソースがロールの ARN である `iam:PassRole` アクションへのアクセス許可が IAM ユーザーに必要です。
1. アカウント A の IAM ユーザーを使用して、[AWS CLIを設定](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)します。
1. AWS IoT ルールエンジンを信頼し、アカウント B の Amazon SNS トピックへのアクセスを許可するポリシーをアタッチする IAM ロールを作成します。コマンドとポリシードキュメントの例については、[「必要なアクセス権 AWS IoT の付与](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html)」を参照してください。
1. トピックにアタッチされるルールを作成するために、[create-topic-rule コマンド](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html)を実行します。
```
aws iot create-topic-rule --rule-name myRule --topic-rule-payload file://./my-rule.json
```
次のペイロードファイル例では、`iot/test` トピックに送信されたすべてのメッセージを指定の Amazon SNS トピックに挿入するルールが指定されています。SQL ステートメントによってメッセージがフィルター処理され、ロールの ARN によって Amazon SNS トピックへのアクセス許可が AWS IoT に付与されます。
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sns": {
"targetArn": "arn:aws:sns:region:2222-2222-2222:ExampleTopic",
"roleArn": "arn:aws:iam::1111-1111-1111:role/my-iot-role"
}
}
]
}
```
AWS IoT ルールで Amazon SNS アクションを定義する方法の詳細については、[AWS IoT 「ルールアクション - Amazon SNS](https://docs.aws.amazon.com/iot/latest/developerguide/sns-rule-action.html)」を参照してください。
**アカウント B のタスクを実行する**
1. アカウント B の IAM ユーザーを使用して、[AWS CLIを設定](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)します。
1. Amazon SNS トピックリソースに対するアクセス許可をアカウント A に付与するために、[add-permission コマンド](https://docs.aws.amazon.com/cli/latest/reference/sns/add-permission.html)を実行します。
```
aws sns add-permission --topic-arn arn:aws:sns:region:2222-2222-2222:ExampleTopic --label Publish-Permission --aws-account-id 1111-1111-1111 --action-name Publish
```
## Amazon S3 のクロスアカウント設定
シナリオ: アカウント A が、MQTT メッセージからアカウント B の Amazon S3 バケットにデータを送信します。
| AWS アカウント | アカウントの呼び方 | 説明 |
| --- | --- | --- |
| 1111-1111-1111 | アカウント A | ルールアクション: s3:PutObject |
| 2222-2222-2222 | アカウント B | Amazon S3 バケットの ARN: arn:aws:s3:::amzn-s3-demo-bucket |
**アカウント A のタスクを実行する**
**メモ**
次のコマンドを実行するには、リソースがルールのARN である `iot:CreateTopicRule` に対するアクセス許可と、リソースがロールの ARN である `iam:PassRole` アクションに対するアクセス許可が IAM ユーザーに必要です。
1. アカウント A の IAM ユーザーを使用して、[AWS CLIを設定](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)します。
1. AWS IoT ルールエンジンを信頼し、アカウント B の Amazon S3 バケットへのアクセスを許可するポリシーをアタッチする IAM ロールを作成します。コマンドとポリシードキュメントの例については、[「必要なアクセス権 AWS IoT の付与](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html)」を参照してください。
1. ターゲット S3 バケットにアタッチされるルールを作成するために、[create-topic-rule コマンド](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html)を実行します。
```
aws iot create-topic-rule --rule-name my-rule --topic-rule-payload file://./my-rule.json
```
次のペイロードファイル例では、`iot/test` トピックに送信されたすべてのメッセージを指定の Amazon S3 バケットに挿入するルールが指定されています。SQL ステートメントによってメッセージがフィルター処理され、ロールの ARN によって Amazon S3 バケットにメッセージを追加するアクセス許可が AWS IoT に付与されます。
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"s3": {
"bucketName": "amzn-s3-demo-bucket",
"key": "${topic()}/${timestamp()}",
"roleArn": "arn:aws:iam::1111-1111-1111:role/my-iot-role"
}
}
]
}
```
AWS IoT ルールで Amazon S3 アクションを定義する方法の詳細については、[AWS IoT 「ルールアクション - Amazon S3](https://docs.aws.amazon.com/iot/latest/developerguide/s3-rule-action.html)」を参照してください。
**アカウント B のタスクを実行する**
1. アカウント B の IAM ユーザーを使用して、[AWS CLIを設定](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)します。
1. アカウント A のプリンシパルを信頼するバケットポリシーを作成します。
次のペイロードファイル例では、別のアカウントのプリンシパルを信頼するバケットポリシーを定義します。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AddCannedAcl",
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::123456789012:root"
]
},
"Action": "s3:PutObject",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*"
}
]
}
```
詳しくは、[バケットポリシーの例](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-bucket-policies.html#example-bucket-policies-use-case-1)を参照してください。
1. 指定したバケットにバケットポリシーをアタッチするために、[put-bucket-policy コマンド](https://docs.aws.amazon.com/cli/latest/reference/s3api/put-bucket-policy.html)を実行します。
```
aws s3api put-bucket-policy --bucket amzn-s3-demo-bucket --policy file://./amzn-s3-demo-bucket-policy.json
```
1. クロスアカウントアクセスが機能するように、**パブリックアクセスをすべてブロック**が正しく設定されていることを確認してください。詳しくは、[Amazon S3 のセキュリティベストプラクティス](https://docs.aws.amazon.com/AmazonS3/latest/userguide/security-best-practices.html)を参照してください。
## のクロスアカウント設定 AWS Lambda
シナリオ: アカウント A はアカウント B の AWS Lambda 関数を呼び出し、MQTT メッセージを渡します。
| AWS アカウント | アカウントの呼び方 | 説明 |
| --- | --- | --- |
| 1111-1111-1111 | アカウント A | ルールアクション: lambda:InvokeFunction |
| 2222-2222-2222 | アカウント B | Lambda 関数の ARN: arn:aws:lambda:region:2222-2222-2222:function:example-function |
**アカウント A のタスクを実行する**
**注意事項**
次のコマンドを実行するには、リソースがルールのARN である `iot:CreateTopicRule` に対するアクセス許可と、リソースがロールの ARN である `iam:PassRole` アクションに対するアクセス許可が IAM ユーザーに必要です。
1. アカウント A の IAM ユーザーを使用して、[AWS CLIを設定](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)します。
1. [create-topic-rule コマンド](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html)を実行して、アカウント B の Lambda 関数へのクロスアカウントアクセスを定義するルールを作成します。
```
aws iot create-topic-rule --rule-name my-rule --topic-rule-payload file://./my-rule.json
```
次のペイロードファイル例では、`iot/test` トピックに送信されたすべてのメッセージを指定の Lambda 関数に挿入するルールが指定されています。SQL ステートメントによってメッセージがフィルター処理され、ロールの ARN によって Lambda 関数にデータを渡すアクセス許可が AWS IoT に付与されます。
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:region:2222-2222-2222:function:example-function"
}
}
]
}
```
ルールで AWS Lambda AWS IoT アクションを定義する方法の詳細については、[AWS IoT ルールアクション - Lambda](https://docs.aws.amazon.com/iot/latest/developerguide/lambda-rule-action.html) を参照してください。
**アカウント B のタスクを実行する**
1. アカウント B の IAM ユーザーを使用して、[AWS CLIを設定](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)します。
1. [Lambda の add-permission コマンド](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html)を実行して、Lambda 関数をアクティブ化するアクセス許可を AWS IoT ルールに付与します。次のコマンドを実行するには、`lambda:AddPermission` アクションに対するアクセス許可が IAM ユーザーに必要です。
```
aws lambda add-permission --function-name example-function --region us-east-1 --principal iot.amazonaws.com --source-arn arn:aws:iot:region:1111-1111-1111:rule/example-rule --source-account 1111-1111-1111 --statement-id "unique_id" --action "lambda:InvokeFunction"
```
**オプション:**
**--プリンシパル**
このフィールドは、Lambda 関数を呼び出すアクセス許可を AWS IoT ( によって表されます`iot.amazonaws.com`) に付与します。
**--source-arn**
このフィールドは、 AWS IoT の `arn:aws:iot:region:1111-1111-1111:rule/example-rule` のみがこのLambda 関数をトリガーし、同じアカウントまたは異なるアカウント内の他のルールはこの Lambda 関数をアクティブ化できないことを確認します。
**--source-account**
このフィールドは、 が`1111-1111-1111`アカウントに代わってのみこの Lambda 関数を AWS IoT アクティブ化することを確認します。
**注意事項**
AWS Lambda 関数のコンソールの [**Configuration**] (設定) の下に「ルールが見つかりませんでした」というエラーメッセージが表示される場合は、エラーメッセージを無視して、接続のテストに進みます。
# エラー処理 (エラーアクション)
がデバイスからメッセージ AWS IoT を受信すると、ルールエンジンはメッセージがルールと一致するかどうかを確認します。一致する場合は、そのルールのクエリステートメントが評価され、ルールのアクションがアクティブ化され、クエリステートメントの結果が渡されます。
アクションをアクティブ化するときに問題が発生した場合、ルールエンジンはエラーアクションを呼び出します (ルールに指定されている場合)。次の場合に、この問題が発生することがあります。
+ ルールに Amazon S3 バケットにアクセスする権限がない。
+ ユーザーエラーにより、DynamoDB のプロビジョニングされたスループットを超える。
**注記**
このトピックで説明するエラー処理は、[ルールアクション](iot-rule-actions.md)に関するものです。外部関数を含む SQL の問題をデバッグするには、 AWS IoT ログ記録を設定できます。詳細については、「[AWS IoT ログ記録の設定](configure-logging.md)」を参照してください。
## エラーアクションメッセージ形式
ルールとメッセージごとに 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
エラーアクションをトリガーしたルールの名前。
トピック
元のメッセージが受信されたトピック。
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",
"bucketName" : "message-processing-errors",
"key" : "${replace(topic(), '/', '-') + '-' + timestamp() + '-' + newuuid()}"
}
}
}
```
エラーアクションの SQL ステートメントでは、、[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda)、[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb)、、[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data)、、 [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow) [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret) [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-machine-learning](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-machine-learning)などの外部[関数](iot-sql-functions.md)を含む任意の関数または[置換テンプレート](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html)を使用できます[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64)。エラーアクションで外部関数を呼び出す必要がある場合、エラーアクションを呼び出すと、外部関数に追加の請求が発生する可能性があります。
ルールとエラーアクションを指定する方法の詳細については、[AWS IoT 「ルールの作成](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-rule.html)」を参照してください。
CloudWatch を使用してルールの成功または失敗を監視する方法の詳細については、[AWS IoT メトリクスとディメンション](metrics_dimensions.md) を参照してください。
# 基本的な取り込みによるメッセージングコストの削減
基本的な取り込みを使用して、安全に [メッセージングコスト](https://aws.amazon.com/iot-core/pricing/)を発生させることなく、[AWS IoT ルールアクション](iot-rule-actions.md) でサポートされる AWS のサービス にデバイスデータを送信できます。基本的な取り込みでは、取り込みパスからパブリッシュ/サブスクライブのメッセージブローカーを除外することによってデータフローが最適化されます。
基本的な取り込みでは、デバイスまたはアプリケーションからメッセージを送信できます。メッセージには、最初の 3 つのレベルに `$aws/rules/rule_name` で始まるトピック名があり、ここで `rule_name` は呼び出す AWS IoT ルールの名前です。
基本的な取り込みのプレフィックス (`$aws/rules/rule_name`) を、ルールを呼び出すために使用するメッセージのトピックに追加するだけで、既存のルールを基本的な取り込みで使用することができます。例えば、`Buildings/Building5/Floor2/Room201/Lights` (`"sql": "SELECT * FROM 'Buildings/#'"`) などのトピックでメッセージによって呼び出される `BuildingManager` という名前のルールがある場合、トピック `$aws/rules/BuildingManager/Buildings/Building5/Floor2/Room201/Lights` でメッセージを送信することで、基本的な取り込みで同じルールを呼び出せます。
**注記**
デバイスとルールでは、基本的な取り込みの予約されたトピックをサブスクライブできません。例えば、AWS IoT Device Defender メトリクスの `num-messages-received` メトリクスはトピックのサブスクライブをサポートしていないため、出力されません。詳細については、「[予約済みトピック](reserved-topics.md)」を参照してください。
パブリッシュ/サブスクライブブローカーで複数の受信対象にメッセージを配信することが必要な場合 (たとえば、他のデバイスとルールエンジンにメッセージを配信する場合)、AWS IoT メッセージブローカーを引き続き使用してメッセージ配信を処理する必要があります。しかし、基本的な取り込みトピック以外のトピックにメッセージを公開するようにしてください。
## 基本的な取り込みの使用
基本的な取り込みを使用する前に、デバイスまたはアプリケーションが、`$aws/rules/*` に対する発行アクセス許可を持つ[ポリシー](iot-policies.md)を使用していることを確認してください。または、ポリシーに `$aws/rules/rule_name/*` で個別ルールに対するアクセス許可を指定できます。それ以外の場合は、デバイスとアプリケーションは AWS IoT Core に対して既存の接続を引き続き使用できます。
メッセージがルールエンジンに到達すると、基本的な取り込みから呼び出されたルールと、メッセージブローカーサブスクリプションを通じて呼び出されたルールによる実装またはエラー処理に違いはありません。
基本的な取り込みで使用するためのルールを作成できます。以下に留意してください。
+ 基本的な取り込みトピックの最初のプレフィックス (`$aws/rules/rule_name`) は [topic(10 進数)](iot-sql-functions.md#iot-function-topic) 関数には使用できません。
+ 基本的な取り込みでのみ呼び出されるルールを定義する場合、`FROM` 句は `rule` 定義の `sql` フィールドのオプションです。これは、メッセージブローカーを使用してメッセージを送信する必要がある他のメッセージによりルールが呼び出される場合でも (例えば、他のメッセージが複数の受信対象に配信される必要があるため) 必要になります。詳細については、「[AWS IoT SQL リファレンス](iot-sql-reference.md)」を参照してください。
+ 基本的な取り込みトピックの最初の 3 つのレベル (`$aws/rules/rule_name`) はトピックの 8 つのセグメント長制限または 256 文字の文字数制限にカウントされません。それ以外の場合は、「[AWS IoT の制限](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#limits_iot)」で説明されているように、同じ制限が適用されます。
+ 無効なルールまたは存在しないルールを指定する基本的な取り込みトピックでメッセージが受信された場合は、エラーログは Amazon CloudWatch ログに作成され、デバッグに利用できます。詳細については、「」を参照してください[ルールエンジンのログエントリ](cwl-format.md#rule-engine-logs) `RuleNotFound` メトリクスが表示され、このメトリクスでアラームを作成できます。詳細については、「[ルールのメトリクス](metrics_dimensions.md#rulemetrics)」の「ルールメトリクス」を参照してください。
+ この場合でも、基本的な取り込みトピックに QoS 1 で発行できます。メッセージがルールエンジンに正常に配信された後、PUBACK を受信します。PUBACK の受信はルールのアクションが正常に完了したことを意味するわけではありません。エラーアクションを設定して、アクションの実行中にエラーを処理することができます。詳細については、「」を参照してください[エラー処理 (エラーアクション)](rule-error-handling.md)
# AWS IoT SQL リファレンス
では AWS IoT、ルールは SQL のような構文を使用して定義されます。SQL ステートメントは、次の 3 種類の句で構成されます。
**SET**
(オプション) SQL ステートメントと置換テンプレート全体で再利用できる変数を定義します。式を使用して変数に値を割り当てます。これらの変数は、SELECT 句と WHERE 句、およびアクション置換テンプレートで参照します。
SET 句は、[データ型](iot-sql-data-types.md)、[オペレータ](iot-sql-operators.md)、、[関数](iot-sql-functions.md)[リテラル](iot-sql-literals.md)、[Case ステートメント](iot-sql-case.md)、、[JSON 拡張](iot-sql-json.md)[変数](iot-sql-set.md#iot-sql-set-usage)、および をサポートします[ネストされたオブジェクトのクエリ](iot-sql-nested-queries.md)。
**SELECT**
(必須) 受信メッセージのペイロードから情報を抽出し、その情報に対して変換を実行します。使用するメッセージは、FROM 句で指定された[トピックフィルター](topics.md#topicfilters)によって識別されます。
SELECT 句は、[データ型](iot-sql-data-types.md)、、[オペレータ](iot-sql-operators.md)、[関数](iot-sql-functions.md)、[リテラル](iot-sql-literals.md)[Case ステートメント](iot-sql-case.md)、[JSON 拡張](iot-sql-json.md)、[置換テンプレート](iot-substitution-templates.md)、[変数](iot-sql-set.md#iot-sql-set-usage)、[ネストされたオブジェクトのクエリ](iot-sql-nested-queries.md)、および をサポートします[バイナリペイロード](binary-payloads.md)。
**FROM**
データを抽出するメッセージを識別する MQTT メッセージ[トピックフィルター](topics.md#topicfilters)。ここで指定されたトピックフィルタに一致する MQTT トピックに送信されるメッセージごとに、ルールがアクティブ化されます。メッセージブローカーを通過するメッセージによってアクティブ化されるルールに必要です。[基本的な取り込み](iot-basic-ingest.md)機能を使用してのみアクティブ化されるルールの場合はオプションです。
**WHERE**
(オプション) ルールで指定されたアクションが実行されるかどうかを決定する条件付きロジックを追加します。
WHERE 句は、[データ型](iot-sql-data-types.md)、、[オペレータ](iot-sql-operators.md)、[関数](iot-sql-functions.md)[リテラル](iot-sql-literals.md)、[Case ステートメント](iot-sql-case.md)、[JSON 拡張](iot-sql-json.md)、[変数](iot-sql-set.md#iot-sql-set-usage)、および をサポートします[ネストされたオブジェクトのクエリ](iot-sql-nested-queries.md)。
SQL ステートメントの例は、次のようになります。
```
SELECT color AS rgb FROM 'topic/subtopic' WHERE temperature > 50
```
MQTT メッセージ (入力ペイロードとも呼ばれる) の例は、次のようになります。
```
{
"color":"red",
"temperature":100
}
```
このメッセージが `'topic/subtopic'` トピックに発行された場合、ルールはトリガーされ、SQL ステートメントは評価されます。SQL ステートメントでは、`color` プロパティが 50 より大きい場合は、`"temperature"` プロパティの値を抽出します。WHERE 句は、条件 `temperature > 50` を指定します。`AS` キーワードは `"color"` プロパティの名前を `"rgb"` に変更します。結果は、(*出力ペイロード*とも呼ばれる) 次のようになります。
```
{
"rgb":"red"
}
```
このデータは、さらなる処理のためにデータを送信するルールアクションに転送されます。ルールアクションの詳細については、「[AWS IoT ルールアクション](iot-rule-actions.md)」を参照してください。
**注記**
コメントは、現在 AWS IoT SQL 構文ではサポートされていません。
空白を含む属性名は、SQL ステートメントのフィールド名として使用できません。受信ペイロードにはスペースを含む属性名を使用できますが、SQL ステートメントではそのような名前を使用できません。ただし、ワイルドカード (\$1) フィールド名指定を使用すると、送信ペイロードに渡されます。
# SELECT 句
AWS IoT SELECT 句は基本的に ANSI SQL SELECT 句と同じですが、いくつかの小さな違いがあります。
SELECT 句は、[データ型](iot-sql-data-types.md)、、[オペレータ](iot-sql-operators.md)、[関数](iot-sql-functions.md)[リテラル](iot-sql-literals.md)、[Case ステートメント](iot-sql-case.md)、[JSON 拡張](iot-sql-json.md)、[変数](iot-sql-set.md#iot-sql-set-usage)、[ネストされたオブジェクトのクエリ](iot-sql-nested-queries.md)、および をサポートします[バイナリペイロード](binary-payloads.md)。
SELECT 句を使用して、受信 MQTT メッセージから情報を抽出できます。`SELECT *` を使用して、受信メッセージのペイロード全体を取得することもできます。以下に例を示します。
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL statement: SELECT * FROM 'topic/subtopic'
Outgoing payload: {"color":"red", "temperature":50}
```
ペイロードが JSON オブジェクトの場合、オブジェクトのキーを参照できます。出力ペイロードにはキーと値のペアが含まれます。以下に例を示します。
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL statement: SELECT color FROM 'topic/subtopic'
Outgoing payload: {"color":"red"}
```
AS キーワードを使用してキーの名前を変更できます。以下に例を示します。
```
Incoming payload published on topic 'topic/subtopic':{"color":"red", "temperature":50}
SQL:SELECT color AS my_color FROM 'topic/subtopic'
Outgoing payload: {"my_color":"red"}
```
カンマで区切ることで、複数の項目を選択できます。以下に例を示します。
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL: SELECT color as my_color, temperature as fahrenheit FROM 'topic/subtopic'
Outgoing payload: {"my_color":"red","fahrenheit":50}
```
「\$1」を含む複数の項目を選択して、受信ペイロードに項目を追加できます。以下に例を示します。
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL: SELECT *, 15 as speed FROM 'topic/subtopic'
Outgoing payload: {"color":"red", "temperature":50, "speed":15}
```
`"VALUE"` キーワードを使用して、JSON オブジェクトではない出力ペイロードを作成できます。SQL バージョン `2015-10-08` では、選択できる項目は 1 つのみです。SQL バージョン `2016-03-23` 以降では、最上位オブジェクトとして出力する配列を選択することもできます。
**Example**
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL: SELECT VALUE color FROM 'topic/subtopic'
Outgoing payload: "red"
```
`'.'` 構文を使用して、受信ペイロードで入れ子になっている JSON オブジェクトを詳細に調べることができます。以下に例を示します。
```
Incoming payload published on topic 'topic/subtopic': {"color":{"red":255,"green":0,"blue":0}, "temperature":50}
SQL: SELECT color.red as red_value FROM 'topic/subtopic'
Outgoing payload: {"red_value":255}
```
数字やハイフン (マイナス) 文字などの予約文字を含む JSON オブジェクトおよびプロパティ名の使用方法については、「[JSON 拡張](iot-sql-json.md)」を参照してください。
関数を使用して受信ペイロードを変換できます ([関数](iot-sql-functions.md) を参照)。グループ化するには括弧を使用します。以下に例を示します。
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL: SELECT (temperature - 32) * 5 / 9 AS celsius, upper(color) as my_color FROM 'topic/subtopic'
Outgoing payload: {"celsius":10,"my_color":"RED"}
```
# FROM 句
FROM 句はルールを[トピック](topics.md#topicnames)や[トピックのフィルター](topics.md#topicfilters)に受信登録します。トピックまたはトピックフィルタは、一重引用符 (') で囲みます。ここで指定されたトピックフィルタに一致する MQTT トピックに送信されるメッセージごとに、ルールがトリガーされます。トピックのフィルタを使って、類似のトピックのグループにサブスクライブできます。
**例**:
トピックに公開された受信ペイロード `'topic/subtopic'`: `{temperature: 50}`。
トピックに公開された受信ペイロード `'topic/subtopic-2'`: `{temperature: 50}`。
SQL: `"SELECT temperature AS t FROM 'topic/subtopic'"`。
ルールが `'topic/subtopic'` に受信登録されるため、受信ペイロードがルールに渡されます。ルールアクションに渡される発信ペイロードは、`{t: 50}` です。ルールが `'topic/subtopic-2'` に受信登録されていないので、ルールは `'topic/subtopic-2'` で公開されるメッセージにトリガーされません。
**\$1 ワイルドカードの例:**
「\$1」(複数レベル) ワイルドカード文字を使用して、1 つ以上の特定のパス要素に一致させることができます。
トピックに公開された受信ペイロード `'topic/subtopic'`: `{temperature: 50}`。
トピックに公開された受信ペイロード `'topic/subtopic-2'`: `{temperature: 60}`。
トピックに公開された受信ペイロード `'topic/subtopic-3/details'`: `{temperature: 70}`。
トピックに公開された受信ペイロード `'topic-2/subtopic-x'`: `{temperature: 80}`。
SQL: `"SELECT temperature AS t FROM 'topic/#'"`。
ルールは `'topic'` で始まるすべてのトピックにサブスクライブされるため、3 回実行され、`{t: 50}` (topic/subtopic)、`{t: 60}` (topic/subtopic-2)、および `{t: 70}` (topic/subtopic-3/details) の送信ペイロードがアクションに送信されます。`'topic-2/subtopic-x'` に受信登録されていないので、`{temperature: 80}` のメッセージにルールはトリガーされません。
**\$1 ワイルドカードの例:**
「\$1」(単数レベル) ワイルドカード文字を使用して、1 つの特定のパス要素に一致させることができます。
トピックに公開された受信ペイロード `'topic/subtopic'`: `{temperature: 50}`。
トピックに公開された受信ペイロード `'topic/subtopic-2'`: `{temperature: 60}`。
トピックに公開された受信ペイロード `'topic/subtopic-3/details'`: `{temperature: 70}`。
トピックに公開された受信ペイロード `'topic-2/subtopic-x'`: `{temperature: 80}`。
SQL: `"SELECT temperature AS t FROM 'topic/+'"`。
ルールは、2 つのパス要素のあるすべてのトピックに受信登録されていて、最初の要素は `'topic'` です。ルールは `'topic/subtopic'` および `'topic/subtopic-2'`に送信されたメッセージに対して実行されますが、`'topic/subtopic-3/details'` (トピックフィルターよりも多くのレベルがある) または `'topic-2/subtopic-x'` (`topic` で始まらない) に対しては実行されません。
# SET 句
SET 句を使用して、式の結果を保存する変数を定義します。これらの変数は、SELECT 句と WHERE 句、および置換テンプレートで再利用できます。これにより、複雑な式が重複するのを防ぎ、SQL ステートメント内の関数呼び出しの数を減らすことができます。
SET 句は、[データ型](iot-sql-data-types.md)、[オペレータ](iot-sql-operators.md)、、[関数](iot-sql-functions.md)[リテラル](iot-sql-literals.md)、[Case ステートメント](iot-sql-case.md)、、[JSON 拡張](iot-sql-json.md)[変数](#iot-sql-set-usage)、および をサポートします[ネストされたオブジェクトのクエリ](iot-sql-nested-queries.md)。
## SET 句構文
SET 句は、SQL ステートメントの SELECT 句の前に表示する必要があります。次の構文を使用します。
```
SET @variable_name = expression [, @variable_name2 = expression2]
```
構文ルール:
+ で変数名を開始する `@`
+ 変数名には、文字、数字、アンダースコアを含めることができます
+ 変数名は最大 64 文字です
+ 複数の変数をカンマで区切って 1 つの SET 句に設定できます。
+ 各変数を割り当てることができるのは 1 回のみです (変数はイミュータブルです)
+ SET キーワードは SQL ステートメントごとに 1 回のみ使用できます
## 変数の使用
変数を定義したら、次の場所で使用できます。
+ SELECT 句
+ WHERE 句
+ その他の SET 変数の割り当て
+ アクション置換テンプレート
+ エラーアクション置換テンプレート
+ ネストされた SELECT クエリ
+ 関数パラメータ (roleArn パラメータなどの特定のパラメータ、および のような関数のモードを切り替えるパラメータは変数をサポート`transform("enrichArray", attributes, values)`していません)
変数は、SET 句で使用されるのと同じ`@variable_name`構文を使用して参照されます。JSON 拡張構文を使用して、 などのオブジェクトを含む変数のプロパティにアクセスすることもできます`@variable_name.property`。
## SET 句の例
**基本的な変数の使用法**
次の例は、トピック で公開されたペイロードを示しています`device/data`。 `{"temp_fahrenheit": 75, "humidity": 60}`
SQL ステートメント:
```
SET @temp_celsius = (temp_fahrenheit - 32) * 5 / 9
SELECT @temp_celsius AS celsius, humidity FROM 'device/data'
```
送信ペイロード: `{"celsius": 23.89, "humidity": 60}`
**埋め込み JSON オブジェクトのメンバーにアクセスする **
次の例は、トピック で公開されたペイロードを示しています`device/data`。 `{"device1": {"deviceId":"weather_sensor", "deviceData": {"sensors": {"temp_fahrenheit": 75, "humidity": 60}, "location": [47.606,-122.332]}}}`
SQL ステートメント:
```
SET @device_sensor_data = device1.deviceData.sensors
SELECT @device_sensor_data.temp_fahrenheit AS temp_fahrenheit, @device_sensor_data.humidity as humidity, device1.deviceId as deviceId FROM 'device/data'
```
送信ペイロード: `{"temp_fahrenheit":75,"humidity":60,"deviceId":"weather_sensor"}`
JSON 拡張機能の操作方法の詳細については、「」を参照してください。 [JSON 拡張](iot-sql-json.md)
**重複する関数呼び出しの回避**
SET 変数は、複雑なデコードオペレーションの重複を回避するのに役立ちます。
```
SET @decoded_data = decode(encode(*, 'base64'), 'proto', 'schema', 'schema.desc', 'message.proto', 'Message')
SELECT @decoded_data.sensor_id, @decoded_data.reading FROM 'device/protobuf'
WHERE @decoded_data.reading > 100
```
SET 変数がない場合、関数呼び出し制限を超えるデコード関数を 3 回繰り返す必要があります。
**複数の変数**
複数の変数をカンマで区切ることで、1 つの SET 句で定義できます。
```
SET @user_data = get_user_properties(device_id), @threshold = 50
SELECT @user_data.name, temp_fahrenheit FROM 'sensors/+'
WHERE temp_fahrenheit > @threshold AND @user_data.active = true
```
**置換テンプレートでの変数の使用**
変数はアクション置換テンプレートでも使用できます。これにより、SQL ステートメントとルールアクションの両方で計算された値を再利用できます。
SQL ステートメント:
```
SET @temp_celsius = (temp_fahrenheit - 32) * 5 / 9
SELECT @temp_celsius AS celsius, humidity FROM 'device/data'
```
アクション設定:
```
{
"s3": {
"roleArn": "arn:aws:iam::123456789012:role/testRuleRole",
"bucketName": "bucket",
"key": "temperature-data/${device_id}/temp-${@temp_celsius}C.json"
}
}
```
この例では、SET 変数`@temp_celsius`が置換テンプレートで使用され、S3 アクションのキーフィールドが作成されます。
**JSON 以外のペイロードの使用**
SET 変数は JSON 以外のペイロードを直接サポートしないため、ペイロードは最初にエンコードまたはデコードする必要があります。
```
SET @encoded_payload = encode(*, 'base64')
SELECT @encoded_payload AS raw_data FROM 'device/binary'
```
JSON 以外のペイロードの操作方法の詳細については、「」を参照してください。 [バイナリペイロードの使用](binary-payloads.md)
## SET 句の制限
SET 変数には、次の制限が適用されます。
+ SQL ステートメントあたり最大 10 個の一意の変数
+ 最大変数値サイズは 128 KiB (UTF-8 JSON 文字列の最小化)
+ すべての変数の最大合計値サイズは 128 KiB です
+ 変数名は 64 文字に制限されています
+ 変数は JSON ペイロードをそのまま直接受け入れることができます (JSON 以外のペイロードは最初にエンコード/デコードする必要があります)
# WHERE 句
WHERE 句は、ルールで指定されたアクションが実行されるかどうかを決定します。WHERE 句が true と評価する場合、ルールアクションが実行されます。それ以外の場合、ルールアクションは実行されません。
WHERE 句は、[データ型](iot-sql-data-types.md)、、[オペレータ](iot-sql-operators.md)、[関数](iot-sql-functions.md)[リテラル](iot-sql-literals.md)、[Case ステートメント](iot-sql-case.md)、[JSON 拡張](iot-sql-json.md)、[変数](iot-sql-set.md#iot-sql-set-usage)、および をサポートします[ネストされたオブジェクトのクエリ](iot-sql-nested-queries.md)。
**例**:
`topic/subtopic` に公開された受信ペイロード: `{"color":"red", "temperature":40}`。
SQL: `SELECT color AS my_color FROM 'topic/subtopic' WHERE temperature > 50 AND color <> 'red'`。
この場合、ルールはトリガーされますが、ルールで指定されたアクションは実行されません。出力ペイロードはありません。
WHERE 句の関数と演算子を使用できます。ただし、SELECT に AS キーワードで作成されたエイリアスを参照することはできません。(SELECT が評価されたかどうかを判断するため、WHERE 句は最初に評価されます。)
**非 JSON ペイロードのある例:**
`topic/subtopic` で公開された受信非 JSON ペイロード: `80`
SQL: ``SELECT decode(encode(*, 'base64'), 'base64') AS value FROM 'topic/subtopic' WHERE decode(encode(*, 'base64'), 'base64') > 50`
この場合、ルールはトリガーされますが、ルールで指定されたアクションは実行されません。送信ペイロードは SELECT 句によって JSON ペイロード `{"value":80}` として変換されます。
# データ型
AWS IoT ルールエンジンは、すべての JSON データ型をサポートしています。
**サポートされているデータの種類**
| タイプ | 意味 |
| --- | --- |
| Int | 個別の Int。最大 34 桁。 |
| Decimal | 0 以外の最小サイズ 1E-999 および最大サイズ 9.999...E999 の、精度が 34 桁の `Decimal`。 一部の関数は、34 桁の精度ではなく、倍精度の `Decimal` の値を返します。 SQL V2 (2016-03-23) では、`10.0` などの整数である数値は、想定される `Decimal` 値 (`10.0`) ではなく `Int` 値 (`10`) として処理されます。整数の数値を `Decimal` 値として確実に処理するには、ルールクエリステートメントに SQL V1 (2015-10-08) を使用します。 |
| Boolean | True-または-False |
| String | A UTF-8 文字列。 |
| Array | 同じ型を持つ必要のない一連の値。 |
| Object | キーと値で構成される JSON 値。キーは文字列である必要があります。値は任意のタイプにできます。 |
| Null | Null JSON で定義されます。値がないことを表す、実際の値です。SQL ステートメントの Null キーワードを使用して、Null の値を明示的に作成できます。例: "SELECT NULL AS n FROM 'topic/subtopic'" |
| Undefined | 値ではなく。値を省略しない限り、これは、JSON では明示的には表現できません。たとえば、`{"foo": null}` のオブジェクトでは、キー「foo」は NULL を返しますが、キー「bar」は `Undefined` を返します。内部的には、SQL 言語は、`Undefined` を値として処理しますが、JSON では表現ができないため、JSON にシリアル化される場合は、結果は `Undefined` になります。 {"foo":null, "bar":undefined} JSON に以下のようにシリアル化されます。 {"foo":null} 同様に、単独でシリアル化すると、`Undefined` は空の文字列に変換されます。無効な引数 (例: 間違った種類、間違った数値の引数など) を使用して呼び出された関数は `Undefined` を返します。 |
## 変換
次の表では 1 つのタイプの値が別のタイプに変換されると (正しくない型の値が関数に付与された場合) 結果を表示します。たとえば、絶対値関数「abs」 (`Int` または `Decimal` を想定します) が `String` に与えられると、以下のルールにしたがって、`String` を `Decimal` に変換するように試みます。この場合、「abs("-5.123")」は「abs(-5.123)」として処理されます。
**注記**
`Array`、`Object`、`Null`、`Undefined` へ試みられた変換はありません。
**Decimal に**
| 引数の型 | 結果 |
| --- | --- |
| Int | 小数点のない Decimal。 |
| Decimal | ソース値。 |
| Boolean | Undefined。(キャスト関数を明示的に使用して、true = 1.0、false = 0.0. を変換できます。) |
| String | SQL エンジンは、文字列を Decimal. AWS IoT attempts として解析し、正規表現に一致する文字列を解析しようとします^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1。「0」、「-1.2」、「5E-12」は、Decimal に自動的に変換される文字列の例です。 |
| 配列 | Undefined. |
| オブジェクト | Undefined. |
| Null | Null. |
| 未定義 | Undefined. |
**Int に**
| 引数の型 | 結果 |
| --- | --- |
| Int | ソース値。 |
| Decimal | 最も近い Int に丸められたソース値。 |
| Boolean | Undefined。(キャスト関数を明示的に使用して、true = 1.0、false = 0.0. を変換できます。) |
| String | SQL エンジンは、文字列を Decimal. AWS IoT attempts として解析し、正規表現に一致する文字列を解析しようとします^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1。「0」、「-1.2」、「5E-12」はすべて、 を String に変換するために Decimals. AWS IoT attempts に自動的に変換されDecimal、その小数点以下を切り捨てDecimalて を作成しますInt。 |
| 配列 | Undefined. |
| オブジェクト | Undefined. |
| Null | Null. |
| 未定義 | Undefined. |
**ブールに**
| 引数の型 | 結果 |
| --- | --- |
| Int | Undefined (cast 関数を明示的に使用して、0 = False、any\$1nonzero\$1value = True を変換できます)。 |
| Decimal | Undefined (キャスト関数を明示的に使用して、0 = False、any\$1nonzero\$1value = True を変換できます)。 |
| Boolean | 元の値。 |
| String | "true" = True および "false" = False (大文字小文字の区別なし)。その他の文字列値 = Undefined。 |
| 配列 | Undefined. |
| オブジェクト | Undefined. |
| Null | Undefined. |
| 未定義 | Undefined. |
**文字列に**
| 引数の型 | 結果 |
| --- | --- |
| Int | 標準表記の Int の文字列表現。 |
| Decimal | おそらく科学的表記での Decimal 値の文字列表現。 |
| Boolean | "true" または "false"。すべて小文字。 |
| String | 元の値。 |
| 配列 | JSON にシリアル化された Array。結果として生じる文字列は、角括弧で囲まれたカンマ区切りリストです。String は引用符で囲まれます。Decimal、Int、Boolean、Null は引用符で囲まれません。 |
| オブジェクト | JSON にシリアル化されたオブジェクト。結果として生じる文字列は、キーと値のペアのカンマ区切りリストで、中括弧で開始し、終了します。String は引用符で囲まれます。Decimal、Int、Boolean、Null は引用符で囲まれません。 |
| Null | Undefined. |
| 未定義 | 未定義。 |
# オペレータ
次の演算子は、SELECT 句および WHERE 句で使用できます。
## AND 演算子
`Boolean` の結果を返します。論理 AND 演算を実行します。左右オペランドが true の場合は true を返します｡ それ以外の場合は、false を返します。`Boolean` オペランド、または、大文字小文字を区別しない「true」または「false」文字列オペランドが必要です。
*構文:* ` expression AND expression`
**AND 演算子**
| 左のオペランド | 右のオペランド | 出力 |
| --- | --- | --- |
| Boolean | Boolean | Boolean。両方のオペランドが true の場合は true。それ以外の場合は、false を返します。 |
| String/Boolean | String/Boolean | すべての文字列が「true」または「false」 (大文字と小文字が区別されません) の場合、それらは Boolean に変換され、boolean AND boolean として、正常に処理されます。 |
| その他の値 | その他の値 | Undefined. |
## OR 演算子
`Boolean` の結果を返します。論理 OR 演算を実行します。左または右オペランドのいずれかが true の場合 true を返します。それ以外の場合は、false を返します。`Boolean` オペランド、または、大文字小文字を区別しない「true」または「false」文字列オペランドが必要です。
*構文:* ` expression OR expression`
**OR 演算子**
| 左のオペランド | 右のオペランド | 出力 |
| --- | --- | --- |
| Boolean | Boolean | Boolean。どちらかのオペランドが true の場合は true。それ以外の場合は、false を返します。 |
| String/Boolean | String/Boolean | すべての文字列が「true」または「false」 (大文字と小文字が区別されません) の場合、それらはブール値に変換され、boolean OR boolean として、正常に処理されます。 |
| その他の値 | その他の値 | Undefined. |
## NOT 演算子
`Boolean` の結果を返します。論理 NOT 演算を実行します。オペランドが false の場合は true を返します｡ それ以外の場合は true を返します。`Boolean` オペランド、または、大文字小文字を区別しない「true」または「false」文字列オペランドが必要です。
*構文:* `NOT expression`
**NOT 演算子**
| オペランド | 出力 |
| --- | --- |
| Boolean | Boolean。オペランドが false の場合は true｡ それ以外の場合は、true。 |
| String | 文字列が「true」または「false」 (大文字と小文字は区別されません) の場合は、対応するブール値に変換され、反対の値は返されます。 |
| その他の値 | Undefined. |
## IN 演算子
`Boolean` の結果を返します。WHERE 句の IN 演算子を使用して、値が配列内の値と一致するかどうかを確認できます。一致が見つかった場合は true、それ以外の場合は false を返します。
*構文:* ` expression IN expression`
**IN 演算子**
| 左のオペランド | 右のオペランド | Output |
| --- | --- | --- |
| Int/Decimal/String/Array/Object | Array | Integer/Decimal/String/Array/Object 要素が配列で見つかった場合は true。それ以外の場合は、false を返します。 |
*例*:
```
SQL: "select * from 'a/b' where 3 in arr"
JSON: {"arr":[1, 2, 3, "three", 5.7, null]}
```
この例では、`arr` という名前の配列に 3 が存在するため、条件句 `where 3 in arr` は true に評価されます。したがって、SQL ステートメントでは、`select * from 'a/b'` が実行されます。この例は、配列が異種である可能性も示しています。
## EXISTS 演算子
`Boolean` の結果を返します。EXISTS 演算子を条件句で使用して、サブクエリ内の要素の存在をテストできます。サブクエリが 1 つ以上の要素を返す場合は true を返し、サブクエリが要素を返さない場合は false を返します。
*構文:* ` expression`
*例*:
```
SQL: "select * from 'a/b' where exists (select * from arr as a where a = 3)"
JSON: {"arr":[1, 2, 3]}
```
この例では、`arr` という名前の配列に 3 が存在するため、条件句 `where exists (select * from arr as a where a = 3)` は true に評価されます。したがって、SQL ステートメントでは、`select * from 'a/b'` が実行されます。
*例*:
```
SQL: select * from 'a/b' where exists (select * from e as e where foo = 2)
JSON: {"foo":4,"bar":5,"e":[{"foo":1},{"foo":2}]}
```
この例では、JSON オブジェクト内の配列 `e` にオブジェクト `{"foo":2}` が含まれているため、条件句 `where exists (select * from e as e where foo = 2)` は true に評価されます。したがって、SQL ステートメントでは、`select * from 'a/b'` が実行されます。
## > operator
`Boolean` の結果を返します。左のオペランドが右のオペランドより大きい場合は true を返します。両方のオペランドが、`Decimal` に変換され、比較されます。
*構文:* `expression > expression`
**> operator**
| 左のオペランド | 右のオペランド | 出力 |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean。左のオペランドが右のオペランドより大きい場合は true。それ以外の場合は、false を返します。 |
| String/Int/Decimal | String/Int/Decimal | すべての文字列を Decimal に変換できると、その後は Boolean です。左のオペランドが右のオペランドより大きい場合は true を返します。それ以外の場合は、false を返します。 |
| その他の値 | Undefined. | Undefined. |
## >= operator
`Boolean` の結果を返します。左のオペランドが右のオペランド以上の場合は true を返します。両方のオペランドが、`Decimal` に変換され、比較されます。
*構文:* `expression >= expression`
**>= operator**
| 左のオペランド | 右のオペランド | 出力 |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean。左のオペランドが右のオペランド以上の場合は true。それ以外の場合は、false を返します。 |
| String/Int/Decimal | String/Int/Decimal | すべての文字列を Decimal に変換できると、その後は Boolean です。左のオペランドが右のオペランド以上の場合は true を返します。それ以外の場合は、false を返します。 |
| その他の値 | Undefined. | Undefined. |
## < 演算子
`Boolean` の結果を返します。左のオペランドが右のオペランド未満の場合は true を返します。両方のオペランドが、`Decimal` に変換され、比較されます。
*構文:* `expression < expression`
**< 演算子**
| 左のオペランド | 右のオペランド | 出力 |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean。左のオペランドが右のオペランド未満の場合は true。それ以外の場合は、false を返します。 |
| String/Int/Decimal | String/Int/Decimal | すべての文字列を Decimal に変換できると、その後は Boolean です。左のオペランドが右のオペランド未満の場合は true を返します。それ以外の場合は、false を返します。 |
| その他の値 | Undefined | Undefined |
## <= 演算子
`Boolean` の結果を返します。左のオペランドが右のオペランド以下の場合は true を返します。両方のオペランドが、`Decimal` に変換され、比較されます。
*構文:* `expression <= expression`
**<= 演算子**
| 左のオペランド | 右のオペランド | 出力 |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean。左のオペランドが右のオペランド以下の場合は true。それ以外の場合は、false を返します。 |
| String/Int/Decimal | String/Int/Decimal | すべての文字列を Decimal に変換できると、その後は Boolean です。左のオペランドが右のオペランド以下の場合は true を返します。それ以外の場合は、false を返します。 |
| その他の値 | Undefined | Undefined |
## <> 演算子
`Boolean` の結果を返します。左右オペランドの両方が等しくない場合に true を返します｡ それ以外の場合は、false を返します。
*構文:* ` expression <> expression`
**<> 演算子**
| 左のオペランド | 右のオペランド | 出力 |
| --- | --- | --- |
| Int | Int | 左のオペランドが右のオペランドと等しくなかったら true。それ以外の場合は、false を返します。 |
| Decimal | Decimal | 左のオペランドが右のオペランドと等しくなかったら true。それ以外の場合は、false を返します。Int は比較される前に Decimal に変換されます。 |
| String | String | 左のオペランドが右のオペランドと等しくなかったら true。それ以外の場合は、false を返します。 |
| 配列 | 配列 | 各オペランドの項目が等しくなく、同じ順序でない場合、true。それ以外の場合は、false を返します。 |
| オブジェクト | オブジェクト | 各オペランドのキーと値が等しくなかったら true。それ以外の場合は、false を返します。キーと値の順序は重要でありません。 |
| Null | Null | False。 |
| 任意の値 | Undefined | 未定義。 |
| Undefined | 任意の値 | 未定義。 |
| 不一致の型 | 不一致の型 | True。 |
## = operator
`Boolean` の結果を返します。左右オペランドの両方が等しい場合に true を返します｡ それ以外の場合は、false を返します。
*構文:* ` expression = expression`
**= operator**
| 左のオペランド | 右のオペランド | 出力 |
| --- | --- | --- |
| Int | Int | 左のオペランドが右のオペランドと等しかったら true。それ以外の場合は、false を返します。 |
| Decimal | Decimal | 左のオペランドが右のオペランドと等しかったら true。それ以外の場合は、false を返します。Int は比較される前に Decimal に変換されます。 |
| String | String | 左のオペランドが右のオペランドと等しかったら true。それ以外の場合は、false を返します。 |
| 配列 | 配列 | 各オペランドの項目が等しく、同じ順序の場合、true。それ以外の場合は、false を返します。 |
| オブジェクト | オブジェクト | 各オペランドのキーと値が等しかったら true。それ以外の場合は、false を返します。キーと値の順序は重要でありません。 |
| 任意の値 | Undefined | Undefined. |
| Undefined | 任意の値 | Undefined. |
| 不一致の型 | 不一致の型 | False。 |
## \$1 operator
「\$1」は、オーバーロードされた演算子です。文字列の連結または追加に使用できます。
*構文:* ` expression + expression`
**\$1 operator**
| 左のオペランド | 右のオペランド | 出力 |
| --- | --- | --- |
| String | 任意の値 | 右のオペランドを文字列に変換してから、左のオペランドの末尾に連結します。 |
| 任意の値 | String | 左のオペランドを文字列に変換して、右のオペランドを変換された左のオペランドの末尾に連結します。 |
| Int | Int | Int 値。オペランドを共に追加します。 |
| Int/Decimal | Int/Decimal | Decimal 値。オペランドを共に追加します。 |
| その他の値 | その他の値 | Undefined. |
## - operator
左のオペランドから右のオペランドを減算します。
*構文:* ` expression - expression`
**- operator**
| 左のオペランド | 右のオペランド | 出力 |
| --- | --- | --- |
| Int | Int | Int 値。左のオペランドから右のオペランドを減算します。 |
| Int/Decimal | Int/Decimal | Decimal 値。左のオペランドから右のオペランドを減算します。 |
| String/Int/Decimal | String/Int/Decimal | すべての文字列が小数に正しく変換されると、Decimal の値が返されます。左のオペランドから右のオペランドを減算します。それ以外の場合は Undefined を返します。 |
| その他の値 | その他の値 | Undefined. |
| その他の値 | その他の値 | Undefined. |
## \$1 operator
左のオペランドを右のオペランドで乗算します。
*構文:* ` expression * expression`
**\$1 operator**
| 左のオペランド | 右のオペランド | 出力 |
| --- | --- | --- |
| Int | Int | Int 値。左のオペランドを右のオペランドで乗算します。 |
| Int/Decimal | Int/Decimal | Decimal 値。左のオペランドを右のオペランドで乗算します。 |
| String/Int/Decimal | String/Int/Decimal | すべての文字列が小数に正しく変換されると、Decimal の値が返されます。左のオペランドを右のオペランドで乗算します。それ以外の場合は Undefined を返します。 |
| その他の値 | その他の値 | Undefined. |
## / operator
左のオペランドを右のオペランドで除算します。
*構文:* ` expression / expression`
**/ operator**
| 左のオペランド | 右のオペランド | 出力 |
| --- | --- | --- |
| Int | Int | Int 値。左のオペランドを右のオペランドで除算します。 |
| Int/Decimal | Int/Decimal | Decimal 値。左のオペランドを右のオペランドで除算します。 |
| String/Int/Decimal | String/Int/Decimal | すべての文字列が小数に正しく変換されると、Decimal の値が返されます。左のオペランドを右のオペランドで除算します。それ以外の場合は Undefined を返します。 |
| その他の値 | その他の値 | Undefined. |
## % operator
左のオペランドを右のオペランドで除算した剰余を返します。
*構文:* ` expression % expression`
**% operator**
| 左のオペランド | 右のオペランド | 出力 |
| --- | --- | --- |
| Int | Int | Int 値。左のオペランドを右のオペランドで除算した剰余を返します。 |
| String/Int/Decimal | String/Int/Decimal | すべての文字列が小数に正しく変換されると、Decimal の値が返されます。左のオペランドを右のオペランドで除算した剰余を返します。そうでない場合は、Undefined です。 |
| その他の値 | その他の値 | Undefined. |
# 関数
SQL 式の SELECT 句または WHERE 句では、以下の組み込み関数を使用できます。
次の外部関数は、ルールアクションの関数と同等に請求されます: [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda)、[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb)、[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data)、および [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow)。また、[Protobuf メッセージを JSON にデコード](https://docs.aws.amazon.com//iot/latest/developerguide/binary-payloads.html#binary-payloads-protobuf)している場合にのみ、[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64) 関数に対して課金されます。詳細については、[AWS IoT Core 料金表のページ](https://aws.amazon.com/iot-core/pricing/)を参照してください。
## abs(10 進数)
数値の絶対値を返します。SQL バージョン 2015-10-08 以降でサポートされています。
例: `abs(-5)` は 5 を返します。
****
| 引数の型 | 結果 |
| --- | --- |
| Int | Int、引数の絶対値。 |
| Decimal | Decimal、引数の絶対値。 |
| Boolean | Undefined. |
| String | Decimal。結果は、引数の絶対値です。文字列が変換できない場合、結果は Undefined です。 |
| 配列 | Undefined. |
| オブジェクト | Undefined. |
| Null | Undefined. |
| 未定義 | Undefined. |
## accountid()
`String` としてこのルールを所有するアカウントの ID を返します。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`accountid() ` = "123456789012"
## acos(10 進数)
数値の逆コサインをラジアンで返します。`Decimal` 引数は関数適用の前に倍精度に丸められます。SQL バージョン 2015-10-08 以降でサポートされています。
例: `acos(0)` = 1.5707963267948966
****
| 引数の型 | 結果 |
| --- | --- |
| Int | Decimal 「倍精度で」、引数の逆コサイン。仮想上の結果は、Undefined として返されます。 |
| Decimal | Decimal 「倍精度で」、引数の逆コサイン。仮想上の結果は、Undefined として返されます。 |
| Boolean | Undefined. |
| String | Decimal、引数の逆コサイン。文字列が変換できない場合、結果は Undefined です。仮想上の結果は、Undefined として返されます。 |
| 配列 | Undefined. |
| オブジェクト | Undefined. |
| Null | Undefined. |
| 未定義 | Undefined. |
## asin(10 進数)
数値の逆サインをラジアンで返します。`Decimal` 引数は関数適用の前に倍精度に丸められます。SQL バージョン 2015-10-08 以降でサポートされています。
例: `asin(0)` = 0.0
****
| 引数の型 | 結果 |
| --- | --- |
| Int | Decimal 「倍精度」、引数の逆サイン。仮想上の結果は、Undefined として返されます。 |
| Decimal | Decimal 「倍精度」、引数の逆サイン。仮想上の結果は、Undefined として返されます。 |
| Boolean | Undefined. |
| String | Decimal 「倍精度」、引数の逆サイン。文字列が変換できない場合、結果は Undefined です。仮想上の結果は、Undefined として返されます。 |
| 配列 | Undefined. |
| オブジェクト | Undefined. |
| Null | Undefined. |
| 未定義 | Undefined. |
## atan(10 進数)
数値の逆タンジェントをラジアンで返します。`Decimal` 引数は関数適用の前に倍精度に丸められます。SQL バージョン 2015-10-08 以降でサポートされています。
例: `atan(0)` = 0.0
****
| 引数の型 | 結果 |
| --- | --- |
| Int | Decimal 「倍精度で」、引数の逆タンジェント。仮想上の結果は、Undefined として返されます。 |
| Decimal | Decimal 「倍精度で」、引数の逆タンジェント。仮想上の結果は、Undefined として返されます。 |
| Boolean | Undefined. |
| String | Decimal、引数の逆タンジェント。文字列が変換できない場合、結果は Undefined です。仮想上の結果は、Undefined として返されます。 |
| 配列 | Undefined. |
| オブジェクト | Undefined. |
| Null | Undefined. |
| 未定義 | Undefined. |
## atan2(10 進数、10 進数)
正の X 軸と 2 つの引数で定義された点 (x、y) の間の角度をラジアンで返します。 反時計回りの角度では正で (上半面、y > 0)、時計回りの角度では負です (下反面、y < 0)。`Decimal` 引数は関数適用の前に倍精度に丸められます。SQL バージョン 2015-10-08 以降でサポートされています。
例: `atan2(1, 0)` = 1.5707963267948966
****
| 引数の型 | 引数の型 | 結果 |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Decimal (倍精度で)、X 軸と指定した点 (x、y) の間の角度。 |
| Int/Decimal/String | Int/Decimal/String | Decimal、示された点の逆タンジェント。文字列が変換できない場合、結果は Undefined です。 |
| その他の値 | その他の値 | Undefined. |
## aws\$1lambda(functionArn, inputJson)
`inputJson` を Lambda 関数に渡して指定された Lambda 関数を呼び出し、Lambda 関数で生成された JSON を返します。
**引数**
| 引数 | 説明 |
| --- | --- |
| functionArn | 呼び出す Lambda 関数の ARN。Lambda 関数は JSON データを返す必要があります。 |
| inputJson | Lambda 関数に渡される JSON 入力です｡ ネストされたオブジェクトクエリとリテラルを渡すには、SQL バージョン 2016-03-23 を使用する必要があります。 |
指定された Lambda 関数を呼び出すアクセス許可を付与 AWS IoT `lambda:InvokeFunction`する必要があります。次の例は、`lambda:InvokeFunction` を使用して AWS CLI権限を付与する方法を示しています。
```
aws lambda add-permission --function-name "function_name"
--region "region"
--principal iot.amazonaws.com
--source-arn arn:aws:iot:us-east-1:account_id:rule/rule_name
--source-account "account_id"
--statement-id "unique_id"
--action "lambda:InvokeFunction"
```
以下は、**add-permission** コマンドの引数です。
--function-name
Lambda 関数の名前。関数のリソースポリシーを更新するための新しいアクセス許可を追加します。
--region
AWS リージョン アカウントの 。
--principal
アクセス権限を取得するプリンシパル。これは、Lambda 関数を呼び出す AWS IoT アクセス許可を付与`iot.amazonaws.com`するためです。
--source-arn
ルールの ARN。**get-topic-rule** AWS CLI コマンドを使用して、ルールの ARN を取得できます。
--source-account
AWS アカウント ルールが定義されている 。
--statement-id
一意のステートメント ID。
--action
このステートメントで許可する Lambda アクション。 AWS IoT が Lambda 関数を呼び出すことを許可するには、`lambda:InvokeFunction` を指定します。
**重要**
`source-arn` または を指定せずにプリン AWS IoT シパルのアクセス許可を追加すると`source-account`、Lambda アクションを使用してルールを作成する は AWS アカウント 、Lambda 関数を呼び出すルールをトリガーできます AWS IoT。詳細については、[[Lambda Permission Model](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html)](ラムダのアクセス許可モデル)を参照してください。
次のような JSON メッセージペイロードがあるとします。
```
{
"attribute1": 21,
"attribute2": "value"
}
```
`aws_lambda` 関数は、以下のように Lambda 関数を呼び出すために使用できます。
```
SELECT
aws_lambda("arn:aws:lambda:us-east-1:account_id:function:lambda_function", {"payload":attribute1}) as output FROM 'topic-filter'
```
完全な MQTT メッセージペイロードを渡したい場合は、次の例のように、「\$1」を使用して JSON ペイロードを指定できます。
```
SELECT
aws_lambda("arn:aws:lambda:us-east-1:account_id:function:lambda_function", *) as output FROM 'topic-filter'
```
`payload.inner.element` は、'topic/subtopic' トピックで発行されたメッセージからデータを選択します。
`some.value` は、Lambda 関数によって生成された出力からデータを選択します。
**注記**
ルールエンジンは、Lambda 関数の実行時間を制限します。ルールからの Lambda 関数の呼び出しは、2000 ミリ秒以内に完了する必要があります。
## bitand(Int、Int)
2 つの `Int` (-converted) 引数のビット表現におけるビット単位の AND を実行します。SQL バージョン 2015-10-08 以降でサポートされています。
例: `bitand(13, 5)` = 5
****
| 引数の型 | 引数の型 | 結果 |
| --- | --- | --- |
| Int | Int | Int、2 つの引数のビット単位の AND。 |
| Int/Decimal | Int/Decimal | Int、2 つの引数のビット単位の AND。すべての非 Int 数は、最も近い Int に切り下げられます。いずれかの引数が Int に変換できない場合、結果は Undefined です。 |
| Int/Decimal/String | Int/Decimal/String | Int、2 つの引数のビット単位の AND。すべての文字列は小数に変換され、最も近い Int に切り下げられます。変換が失敗した場合、結果は Undefined です。 |
| その他の値 | その他の値 | Undefined. |
## bitor(Int、Int)
2 つの引数のビット表現のビット単位の OR を実行します。SQL バージョン 2015-10-08 以降でサポートされています。
例: `bitor(8, 5)` = 13
****
| 引数の型 | 引数の型 | 結果 |
| --- | --- | --- |
| Int | Int | Int、2 つの引数のビット単位の OR。 |
| Int/Decimal | Int/Decimal | Int、2 つの引数のビット単位の OR。すべての非 Int 数は、最も近い Int に切り下げられます。変換が失敗した場合、結果は Undefined です。 |
| Int/Decimal/String | Int/Decimal/String | Int、2 つの引数におけるビット単位の OR。すべての文字列は小数に変換され、最も近い Int に切り下げられます。変換が失敗した場合、結果は Undefined です。 |
| その他の値 | その他の値 | Undefined. |
## bitxor(Int、Int)
2 つの `Int` (-converted) 引数のビット表現におけるビット単位の XOR を実行します。SQL バージョン 2015-10-08 以降でサポートされています。
例: `bitor(13, 5)` = 8
****
| 引数の型 | 引数の型 | 結果 |
| --- | --- | --- |
| Int | Int | Int、2 つの引数におけるビット単位の XOR。 |
| Int/Decimal | Int/Decimal | Int、2 つの引数におけるビット単位の XOR。非 Int 数は、最も近い Int に切り下げられます。 |
| Int/Decimal/String | Int/Decimal/String | Int、2 つの引数におけるビット単位の XOR。文字列は小数に変換され、最も近い Int に切り下げられます。いずれかの変換が失敗した場合、結果は Undefined です。 |
| その他の値 | その他の値 | Undefined. |
## bitnot(Int)
`Int` (-converted) 引数のビット表現におけるビット単位の NOT を実行します。SQL バージョン 2015-10-08 以降でサポートされています。
例: `bitnot(13)` = 2
****
| 引数の型 | 結果 |
| --- | --- |
| Int | Int、引数のビット単位の NOT。 |
| Decimal | Int、引数のビット単位の NOT。Decimal の値は、最も近い Int に切り下げられます。 |
| String | Int、引数のビット単位の NOT。文字列は小数に変換され、最も近い Int に切り下げられます。いずれかの変換が失敗した場合、結果は Undefined です。 |
| その他の値 | その他の値。 |
## cast()
値を 1 つのデータ型から別のデータ型へ変換します。cast は通常の変換と同様に動作し、数値をブールへ/からキャストする追加機能があります。が 1 つのタイプを別のタイプにキャストする方法を決定 AWS IoT できない場合、結果は です`Undefined`。SQL バージョン 2015-10-08 以降でサポートされています。形式: cast(*値* as *型*)。
例:
`cast(true as Int) ` = 1
`cast` を呼び出す際、次のキーワードが「as」の後に表示される場合があります。
**SQL バージョン 2015-10-08 および 2016-03-23 向け**
| キーワード | 結果 |
| --- | --- |
| String | 値を String へキャストします。 |
| Nvarchar | 値を String へキャストします。 |
| Text | 値を String へキャストします。 |
| Ntext | 値を String へキャストします。 |
| varchar | 値を String へキャストします。 |
| Int | 値を Int へキャストします。 |
| 整数 | 値を Int へキャストします。 |
| Double | 値を (倍精度で) Decimal にキャストします。 |
**さらに、SQL バージョン 2016-03-23 向け**
| キーワード | 結果 |
| --- | --- |
| Decimal | 値を Decimal へキャストします。 |
| Bool | 値を Boolean へキャストします。 |
| Boolean | 値を Boolean へキャストします。 |
キャストのルール:
**Decimal へのキャスト**
| 引数の型 | 結果 |
| --- | --- |
| Int | 小数点のない Decimal。 |
| Decimal | ソース値。 SQL V2 (2016-03-23) では、`10.0` などの整数である数値は、想定される `Int` 値 (`10`) の代わりに `Decimal` 値 (`10.0`) を返します。整数の数値を `Decimal` 値として確実にキャストするには、ルールクエリステートメントに SQL V1 (2015-10-08) を使用します。 |
| Boolean | true = 1.0, false = 0.0. |
| String | 文字列を Decimal として解析しようとします。 AWS IoT は、正規表現 (^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1) と一致する文字列を解析するよう試みます。「0」、「-1.2」、「5E-12」は、小数に自動的に変換される文字列の例です。 |
| 配列 | Undefined. |
| オブジェクト | Undefined. |
| Null | Undefined. |
| 未定義 | Undefined. |
**Int へのキャスト**
| 引数の型 | 結果 |
| --- | --- |
| Int | ソース値。 |
| Decimal | 最も近い Int へ切り下げられたソース値。 |
| Boolean | true = 1.0, false = 0.0. |
| String | 文字列を Decimal として解析しようとします。 AWS IoT は、正規表現 (^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1) と一致する文字列を解析するよう試みます。「0」「-1.2」「5E-12」はすべて自動的に小数に変換される文字列の例です。 AWS IoT は文字列を Decimal に変換するよう試み、最も近い Int へ切り下げます。 |
| 配列 | Undefined. |
| オブジェクト | Undefined. |
| Null | Undefined. |
| 未定義 | Undefined. |
**`Boolean` へのキャスト**
| 引数の型 | 結果 |
| --- | --- |
| Int | 0 = False, any\$1nonzero\$1value = True。 |
| Decimal | 0 = False, any\$1nonzero\$1value = True。 |
| Boolean | ソース値。 |
| String | "true" = True および "false" = False (大文字小文字の区別なし)。その他の文字列値 = Undefined。 |
| 配列 | Undefined. |
| オブジェクト | Undefined. |
| Null | Undefined. |
| 未定義 | Undefined. |
**String へのキャスト**
| 引数の型 | 結果 |
| --- | --- |
| Int | Int の文字列表現、標準表記。 |
| Decimal | おそらく科学的表記での Decimal 値の文字列表現。 |
| Boolean | 「true」または「false」、すべて小文字。 |
| String | ソース値。 |
| 配列 | JSON へシリアル化された配列。結果の文字列は角括弧で囲まれたカンマ区切りのリストです。String は引用符で囲まれます。Decimal、Int、Boolean は囲まれません。 |
| オブジェクト | JSON にシリアル化されたオブジェクト。JSON 文字列はキーと値のペアのカンマ区切りのリストで、最初と最後に中括弧があります。String は引用符で囲まれます。Decimal、Int、Boolean、Null は囲まれません。 |
| Null | Undefined. |
| 未定義 | Undefined. |
## ceil(10 進数)
指定の `Decimal` を最も近い `Int` に切り上げます。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`ceil(1.2)` = 2
`ceil(-1.2)` = -1
****
| 引数の型 | 結果 |
| --- | --- |
| Int | Int、引数値。 |
| Decimal | Int、最も近い Decimal へ切り上げられたInt 値。 |
| String | Int。文字列は Decimal に変換され、最も近い Int へ切り上げられます。文字列が Decimal に変換できない場合、結果は Undefined です。 |
| その他の値 | Undefined. |
## chr(文字列)
指定の `Int` 引数に対応する ASCII 文字を返します。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`chr(65)` = "A"。
`chr(49)` = "1"。
****
| 引数の型 | 結果 |
| --- | --- |
| Int | 指定された ASCII 値に対応する文字。引数が有効な ASCII 値でない場合、結果は Undefined です。 |
| Decimal | 指定された ASCII 値に対応する文字。Decimal 引数は、最も近い Int に切り下げられます。引数が有効な ASCII 値でない場合、結果は Undefined です。 |
| Boolean | Undefined. |
| String | String が Decimal に変換できる場合、最も近い Int に切り下げられます。引数が有効な ASCII 値でない場合、結果は Undefined です。 |
| 配列 | Undefined. |
| オブジェクト | Undefined. |
| Null | Undefined. |
| その他の値 | Undefined. |
## clientid()
メッセージを送信している MQTT クライアントの ID を返すか、または、メッセージが MQTT クライアント経由で送られていない場合は、`n/a` を返します。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`clientid() ` = "123456789012"
## concat()
配列または文字列を連結します。この関数は、任意の数の引数を受け取り、`String` または `Array` を返します。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`concat() ` = `Undefined`.
`concat(1) ` = "1"。
`concat([1, 2, 3], 4)` = [1, 2, 3, 4]。
`concat([1, 2, 3], "hello")` = [1, 2, 3, "hello"]
`concat("con", "cat")` = "concat"
`concat(1, "hello")` = "1hello"
`concat("he","is","man")` = "heisman"
`concat([1, 2, 3], "hello", [4, 5, 6])` = [1, 2, 3, "hello", 4, 5, 6]
****
| 引数の数 | 結果 |
| --- | --- |
| 0 | Undefined. |
| 1 | 引数は変更されずに返されます。 |
| 2\$1 | 引数が `Array` の場合、結果はすべての引数を含む 1 つの配列です。どの引数も配列ではなく、少なくとも 1 つの引数が `String` の場合、結果はすべての引数の `String` 表現の連結です。引数は、前にリストされた標準変換を使用して、文字列に変換されます。 |
## cos(10 進数)
数値のコサインをラジアンで返します。`Decimal` 引数は関数適用の前に倍精度に丸められます。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`cos(0)` = 1.
****
| 引数の型 | 結果 |
| --- | --- |
| Int | Decimal 「倍精度で」、引数のコサイン。仮想上の結果は、Undefined として返されます。 |
| Decimal | Decimal 「倍精度で」、引数のコサイン。仮想上の結果は、Undefined として返されます。 |
| Boolean | Undefined. |
| String | Decimal 「倍精度で」、引数のコサイン。文字列が Decimal に変換できない場合、結果は Undefined です。仮想上の結果は、Undefined として返されます。 |
| 配列 | Undefined. |
| オブジェクト | Undefined. |
| Null | Undefined. |
| 未定義 | Undefined. |
## cosh(10 進数)
数値のハイパーボリックコサインをラジアンで返します。`Decimal` 引数は関数適用の前に倍精度に丸められます。SQL バージョン 2015-10-08 以降でサポートされています。
例: `cosh(2.3)` = 5.037220649268761。
****
| 引数の型 | 結果 |
| --- | --- |
| Int | Decimal 「倍精度で」、引数の双曲線コサイン。仮想上の結果は、Undefined として返されます。 |
| Decimal | Decimal 「倍精度で」、引数の双曲線コサイン。仮想上の結果は、Undefined として返されます。 |
| Boolean | Undefined. |
| String | Decimal 「倍精度で」、引数の双曲線コサイン。文字列が Decimal に変換できない場合、結果は Undefined です。仮想上の結果は、Undefined として返されます。 |
| 配列 | Undefined. |
| オブジェクト | Undefined. |
| Null | Undefined. |
| 未定義 | Undefined. |
## decode(value, decodingScheme)
`decode` 関数を使用して、エンコードされた値をデコードします。デコードされた文字列が JSON ドキュメントの場合、アドレス指定可能なオブジェクトが返されます。それ以外の場合、デコードされた文字列は文字列として返されます。文字列がデコードできない場合、この関数は NULL を返します。この関数は、base64 でエンコードされた文字列とプロトコルバッファ (protobuf) メッセージ形式のデコードをサポートします。
SQL バージョン 2016-03-23 以降でサポートされています。
値
文字列を返す文字列値、または [AWS IoT SQL リファレンス](iot-sql-reference.md) で定義されている有効な式のいずれか。
decodingScheme
値をデコードするために使用されるスキームを表すリテラル文字列。現在 `'base64'` そして `'proto'` のみがサポートされています。
### base64 でエンコードされた文字列のデコード
この例では、メッセージペイロードにエンコードされた値が含まれています。
```
{
encoded_temp: "eyAidGVtcGVyYXR1cmUiOiAzMyB9Cg=="
}
```
この SQL ステートメントの `decode` 関数は、メッセージペイロードの値をデコードします。
```
SELECT decode(encoded_temp,"base64").temperature AS temp from 'topic/subtopic'
```
`encoded_temp` 値をデコードすると、次の有効な JSON ドキュメントが生成され、SELECT ステートメントで温度値を読み取ることができます。
```
{ "temperature": 33 }
```
この例では、SELECT ステートメントの結果は以下のとおりです。
```
{ "temp": 33 }
```
デコードされた値が有効な JSON ドキュメントでない場合、デコードされた値は文字列として返されます。
### protobuf メッセージペイロードのデコード
decode SQL 関数を使用して、protobuf メッセージペイロードをデコードできるルールを設定できます。詳細については、「[protobuf メッセージペイロードのデコード](binary-payloads.md#binary-payloads-protobuf)」を参照してください。
**重要**
プリン AWS IoT シパルのアクセス許可を設定する`source‐account`ときに `source‐arn`または を省略すると、 は他の AWS IoT ルールを通じてデコード関数を呼び出す AWS アカウント ことができます。関数を保護するには、「*Amazon Simple Storage Service ユーザーガイド*」の「[バケットポリシー](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-policies.html)」を参照してください。
この関数の署名は次のようになります。
```
decode(, 'proto', '', '', '', '')
```
`ENCODED DATA`
デコードする protobuf でエンコードされたデータを指定します。ルールに送信されるメッセージ全体が protobuf でエンコードされたデータである場合は、`*` を使用して raw バイナリ受信ペイロードを参照できます。それ以外の場合は、このフィールドは base-64 でエンコードされた JSON 文字列である必要があり、文字列への参照を直接渡すことができます。
1) raw バイナリ protobuf 受信ペイロードをデコードするには次のように入力します。
```
decode(*, 'proto', ...)
```
2) base64 でエンコードされた文字列「a.b」で表される protobuf エンコードされたメッセージをデコードするには、次のように入力します。
```
decode(a.b, 'proto', ...)
```
`proto`
protobuf メッセージ形式でデコードするデータを指定します。`proto` の代わりに `base64` を指定すると、この関数は base64 でエンコードされた文字列を JSON としてデコードします。
`S3 BUCKET NAME`
`FileDescriptorSet` ファイルをアップロードした Amazon S3 バケットの名前。
`S3 OBJECT KEY`
Amazon S3 バケット内の `FileDescriptorSet` ファイルを指定するオブジェクトキー。
`PROTO NAME`
`FileDescriptorSet` ファイルを生成した `.proto` ファイルの名前 (拡張子を除く)。
`MESSAGE TYPE`
`FileDescriptorSet` ファイル内の protobuf メッセージ構造の名前。デコードするデータはこの構造に従う必要があります。
decode SQL 関数を使用した SQL 式の例は次のようになります。
```
SELECT VALUE decode(*, 'proto', 's3-bucket', 'messageformat.desc', 'myproto', 'messagetype') FROM 'some/topic'
```
+ `*`
`mymessagetype` と呼ばれる protobuf メッセージタイプに準拠するバイナリの受信ペイロードを表します。
+ `messageformat.desc`
`s3-bucket` という名前の Amazon S3 バケットに保存されている `FileDescriptorSet` ファイル。
+ `myproto`
`myproto.proto` という名前の `FileDescriptorSet` ファイルを生成するために使用されたオリジナルの `.proto` ファイル。
+ `messagetype`
`myproto.proto` で定義された `messagetype` と呼ばれるメッセージタイプ (インポートされた依存関係を含む)。
## encode(value, encodingScheme)
エンコードスキームに基づいて、ペイロード (非 JSON データの場合もある) を文字列表現にエンコードするには、`encode` 関数を使用します。SQL バージョン 2016-03-23 以降でサポートされています。
値
[AWS IoT SQL リファレンス](iot-sql-reference.md) で定義されている任意の有効な式。JSON 形式かどうかに関係なくペイロード全体をエンコードするには、\$1 を指定できます。式を指定した場合は、まず評価の結果が文字列に変換され、その後でエンコードされます。
encodingScheme
使用するエンコードスキームを表すリテラル文字列。現在は、`'base64'` のみがサポートされます。
## endswith(文字列、文字列)
`Boolean` を返し、最初の `String` 引数が 2 番目の `String` 引数で終わるかどうかを示します。どちらかの引数が `Null` または `Undefined` の場合、結果は `Undefined` です。SQL バージョン 2015-10-08 以降でサポートされています。
例: `endswith("cat","at")` = true。
****
| 引数の型 1 | 引数の型 2 | 結果 |
| --- | --- | --- |
| String | String | 最初の引数が 2 番目の引数で終わる場合は true。それ以外の場合は、false を返します。 |
| その他の値 | その他の値 | 両方の引数は標準変換ルールを使用して文字列に変換されます。最初の引数が 2 番目の引数で終わる場合は true。それ以外の場合は、false を返します。どちらかの引数が Null または Undefined の場合、結果は Undefined です。 |
## exp(10 進数)
e を `Decimal` 引数の累乗にして返します。`Decimal` 引数は関数適用の前に倍精度に丸められます。SQL バージョン 2015-10-08 以降でサポートされています。
例: `exp(1)` = e。
****
| 引数の型 | 結果 |
| --- | --- |
| Int | Decimal(倍精度で)、e ^ 引数。 |
| Decimal | Decimal(倍精度で)、e ^ 引数。 |
| String | Decimal(倍精度で)、e ^ 引数。String が Decimal に変換できない場合、結果は Undefined です。 |
| その他の値 | Undefined. |
## floor(Decimal)
指定の `Decimal` を最も近い `Int` に切り下げます。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`floor(1.2)` = 1
`floor(-1.2)` = -2
****
| 引数の型 | 結果 |
| --- | --- |
| Int | Int、引数値。 |
| Decimal | Int、最も近い Decimal へ切り下げられた Int 値。 |
| String | Int。文字列は Decimal に変換され、最も近い Int へ切り下げられます。文字列が Decimal に変換できない場合、結果は Undefined です。 |
| その他の値 | Undefined. |
## get
コレクションのような型から値を抽出します (配列、文字列、オブジェクト)。最初の引数に変換は適用されません。テーブルで説明されているように、変換は 2 番目の引数に適用されます。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`get(["a", "b", "c"], 1) ` = "b"
`get({"a":"b"}, "a")` = "b"
`get("abc", 0)` = "a"
****
| 引数の型 1 | 引数の型 2 | 結果 |
| --- | --- | --- |
| 配列 | Any Type (Int に変換) | 2 番目の引数により提供される Array のゼロベースインデックスの項目 (Int に変換)。変換が失敗した場合、結果は Undefined です。インデックスが Array の境界の外にある場合 (negative or >= array.length)、結果は Undefined です。 |
| 文字列 | Any Type (Int に変換) | 2 番目の引数により提供される文字列のゼロベースインデックスの文字 (Int に変換)。変換が失敗した場合、結果は Undefined です。インデックスが文字列の境界の外にある場合 (negative or >= string.length)、結果は Undefined です。 |
| オブジェクト | String (変換の適用なし) | 2 番目の引数として提供される文字列キーに対応する最初の引数のオブジェクトに保存されている値。 |
| その他の値 | 任意の値 | Undefined. |
## get\$1dynamodb (tableName、partitionKeyName、partitionKeyValue、sortKeyName、sortKeyValue, roleArn)
DynamoDB テーブルからデータを取得します。`get_dynamodb()` を使用すると、ルールが評価されている間に DynamoDB テーブルを照会できます。DynamoDB から取得したデータを使用して、メッセージペイロードをフィルタリングまたは拡張できます。SQL バージョン 2016-03-23 以降でサポートされています。
`get_dynamodb()` には以下のパラメータがあります。
tableName
クエリする DynamoDB テーブルの名前。
partitionKeyName
パーティションキーの名前。詳細については、「[DynamoDB Keys](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey)」を参照してください。
partitionKeyValue
レコードを識別するために使用されるパーティションキーの値。詳細については、「[DynamoDB Keys](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey)」を参照してください。
sortKeyName
(オプション) ソートキーの名前。このパラメータは、クエリされた DynamoDB テーブルが複合キーを使用する場合にのみ必要です。詳細については、「[DynamoDB Keys](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey)」を参照してください。
sortKeyValue
(オプション) ソートキーの値。このパラメータは、クエリされた DynamoDB テーブルが複合キーを使用する場合にのみ必要です。詳細については、「[DynamoDB Keys](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey)」を参照してください。
roleArn
DynamoDB テーブルへのアクセスを付与する IAM ロールの ARN。ルールエンジンは、ユーザーに代わって DynamoDB テーブルにアクセスするためにこのロールを引き受けます。過度に許容されるロールの使用は避けてください。ルールで必要なアクセス許可のみをロールに付与します。1 つの DynamoDB テーブルへのアクセスを許可するポリシーの例を次に示します。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "dynamodb:GetItem",
"Resource": "arn:aws:dynamodb:us-east-1:123456789012:table/table-name"
}
]
}
```
`get_dynamodb()` の使用方法の例として、 AWS IoTに接続されているすべてのデバイスのデバイス ID と位置情報を含む DynamoDB テーブルがあるとします。次の SELECT 文は、 `get_dynamodb()` 関数を使用して、指定したデバイス ID の場所を取得します。
`SELECT *, get_dynamodb("InServiceDevices", "deviceId", id, "arn:aws:iam::12345678910:role/getdynamo").location AS location FROM 'some/topic' `
**注記**
1 つの SQL 文につき最大 1 回 `get_dynamodb()` を呼び出すことができます。1 つの SQL 文で `get_dynamodb()` 複数回呼び出すと、アクションを呼び出さずにルールが終了します。
## get\$1mqtt\$1property(name)
次の MQTT5 ヘッダーのいずれかを参照します: `contentType`、`payLoadFormatIndicator`、`responseTopic`、`correlationData`。この関数は、`content_type`、`format_indicator`、`response_topic`、`correlation_data` いうリテラル文字列のいずれかを引数としてとります。詳細については、以下の**関数の引数**表を参照してください。
contentType
文字列: 公開メッセージの内容を説明する UTF-8 でエンコードされた文字列。
payLoadFormatIndicator
文字列: ペイロードが UTF-8 としてフォーマットされているかどうかを示す列挙型文字列の値。有効な値は、`UNSPECIFIED_BYTES` および `UTF8_DATA` です。
responseTopic
文字列: 応答メッセージのトピック名として使用される UTF-8 でエンコードされた文字列。レスポンストピックは、受信者がリクエスト/レスポンスフローの一部として公開すべきトピックを説明するために使用されます。トピックにワイルドカード文字を含めることはできません。
correlationData
文字列: 要求メッセージの送信者によって base64 でエンコードされたバイナリデータで、応答メッセージを受信した際に、それがどの要求に対するものかを識別するために使用されます。
次の表は、`get_mqtt_property` 関数で使用できる関数の引数と、それに関連する戻り値の型を示しています。
**関数の引数**
| SQL | 返されるデータ型 (存在する場合) | 返されるデータ型 (存在しない場合) |
| --- | --- | --- |
| get\$1mqtt\$1property("format\$1indicator") | 文字列 (UNSPECIFIED\$1BYTES または UTF8\$1DATA) | 文字列 (UNSPECIFIED\$1BYTES) |
| get\$1mqtt\$1property("content\$1type") | String | 未定義 |
| get\$1mqtt\$1property("response\$1topic") | String | 未定義 |
| get\$1mqtt\$1property("correlation\$1data") | base64 でエンコードされた文字列 | 未定義 |
| get\$1mqtt\$1property("some\$1invalid\$1name") | 未定義 | 未定義 |
以下の SQL ルール例では、`contentType`、`payLoadFormatIndicator`、`responseTopic`、`correlationData` のいずれかの MQTT5 ヘッダーを参照しています。
```
SELECT *, get_mqtt_property('content_type') as contentType,
get_mqtt_property('format_indicator') as payloadFormatIndicator,
get_mqtt_property('response_topic') as responseTopic,
get_mqtt_property('correlation_data') as correlationData
FROM 'some/topic'
```
## get\$1or\$1default(式、defaultValue)
指定された場合は 2 番目のパラメータのデフォルト値を返します。それ以外の場合は、最初のパラメータの式が null、undefined、または fail を返すときに undefined を返します。SQL バージョン 2016-03-23 以降でサポートされています。
**重要**
`get_or_default` は、JSON 以外のペイロードをそのまま直接サポートしていません。JSON 以外のペイロードを使用している場合は、 `encode`または `decode`関数を使用します。
`get_or_default()` には以下のパラメータがあります。
expression
[データ型](iot-sql-data-types.md)、[関数](#iot-sql-functions)、、[変数](iot-sql-set.md#iot-sql-set-usage)[リテラル](iot-sql-literals.md)、、[ネストされたオブジェクトのクエリ](iot-sql-nested-queries.md)または を含む有効な式[JSON 拡張](iot-sql-json.md)。
defaultValue
(オプション) [データ型](iot-sql-data-types.md)、[関数](#iot-sql-functions)、、[変数](iot-sql-set.md#iot-sql-set-usage)[リテラル](iot-sql-literals.md)、、[ネストされたオブジェクトのクエリ](iot-sql-nested-queries.md)または を含む有効な式[JSON 拡張](iot-sql-json.md)。これは、最初の引数が null、未定義、または失敗を返すたびに返される値です。
get\$1secret、get\$1dynamodb、aws\$1lambda、get\$1thing\$1shadow、decode-protobuf、Machinelearning\$1predict など、顧客所有のリソースからデータを取得する関数は、defaultValue パラメータでは許可されません。
次の表は、各引数と関連する出力に許容される関数引数を示しています。
| 最初の引数 | 2 番目の引数 | Output |
| --- | --- | --- |
| 成功した評価 | 任意の値または指定なし | 最初の引数値。 |
| 未定義、Null、または失敗 | Undefined または Null を含む任意の値 | 2 番目の引数値。 |
| 未定義、Null、または失敗 | 指定されていません | Undefined |
**例:**
例 1:
次の例では、DynamoDB テーブルまたはクエリが失敗した場合の defaultValue 値を示します。
```
SELECT
device_id,
get_or_default(
get_dynamodb("DeviceConfig", "deviceId", nonExistentId, "arn:aws:iam::123456789012:role/ROLE_NAME"),
{"mode": "standard", "timeout": 30, "enabled": true }
) as config
FROM 'device/telemetry'
```
例 2:
次の例では、ステータスが未定義の場合、安全なデフォルト値「UNKNOWN」を示します。
```
SELECT
get_or_default( CASE status
WHEN 'active' THEN 'GOOD'
WHEN 'inactive' THEN 'BAD'/
ELSE 'UNKNOWN'
END, 'UNKNOWN') as status_category
FROM 'topic/subtopic'
```
例 3:
次の例は、単一のパラメータで get\$1or\$1default を使用する方法を示しています。これは、明確なデフォルト値がないが、ルールの実行を失敗させたくない場合に役立ちます。
```
SELECT
get_dynamodb("DeviceConfig", "deviceId", nonExistentId, "arn:aws:iam::123456789012:role/ROLE_NAME") as config
FROM 'device/telemetry'
```
DynamoDB ルックアップが失敗した場合、ルールの実行は失敗し、アクションは実行されません。代わりに次の SQL を使用する場合:
```
SELECT
get_or_default(get_dynamodb("DeviceConfig", "deviceId", nonExistentId, "arn:aws:iam::123456789012:role/ROLE_NAME")) as config
FROM 'device/telemetry'
```
get\$1or\$1default ステートメントは に評価されるため`Undefined`、この例では SELECT ステートメント全体が に評価`{}`され、すべてのルールアクションが試行されます。
**重要**
この機能を使用する際にセキュリティを維持するために、以下のベストプラクティスに従うことをお勧めします。
デフォルト値を含むルール定義でハードコードされたシークレットを使用しない
機密情報の管理 AWS Secrets Manager に使用する
## get\$1registry\$1data(registryAPI, thingName, roleArn)
AWS IoT ルール内の AWS IoT モノのレジストリデータを取得します。レジストリデータ (デバイスが属する属性、モノのタイプ、モノのグループなど) を読み取って、この情報を使用してメッセージをフィルタリング、強化、または動的にルーティングできます。SQL バージョン 2016-03-23 以降でサポートされています。
`get_registry_data()` には以下のパラメータがあります。
registryAPI
呼び出されるレジストリ API。有効な値は、`DescribeThing` および `ListThingGroupsForThing` です。これらの値は定数文字列である必要があります。
thingName
文字列: レジストリデータを取得するモノの名前。
roleArn
文字列: 呼び出される API に基づく`iot:DescribeThing`アクセス許可またはアクセス`iot:ListThingGroupsForThing`許可を持つロール ARN。
`get_registry_data` 関数のレスポンス形式は、 というレジストリ API と同じです。詳細については、[DescribeThing](https://docs.aws.amazon.com//iot/latest/apireference/API_DescribeThing.html) API と [ListThingGroupsForThing](https://docs.aws.amazon.com//iot/latest/apireference/API_ListThingGroupsForThing.html) APIsを参照してください。
例:
モノのタイプ情報を取得して、モノのタイプが であるモノ (モノの名前が MQTT クライアント ID と一致するもの) の AWS IoT Core ライフサイクルイベントメッセージをフィルタリングできます`testenv`。
```
SELECT *
FROM '$aws/events/lifecycle/+'
WHERE
get_registry_data("DescribeThing",clientId,[roleArn]).thingTypeName='testenv'
```
例:
ゲートウェイデバイス によって送信される`sensor1`すべてのメッセージのモノの名前を持つデバイスのモノ属性を取得できます`gateway1`。
```
SELECT *, get_registry_data("DescribeThing","sensor1",[roleArn]).attributes.temperature_threhold AS device1_tempthreshold
FROM home1/gateway1/sensor1/#
```
**注記**
アクションとエラーアクションの SQL ステートメントと置換テンプレートごとに`get_registry_data()`最大 1 回呼び出すことができます。
## get\$1secret(secretId, secretType, key, roleArn)
[AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) の現在のバージョンのシークレットの暗号化された `SecretString` または `SecretBinary` フィールドの値を取得します。シークレットの作成と維持の詳細については、[CreateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_CreateSecret.html)、[UpdateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_UpdateSecret.html)、および [PutSecretValue](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_PutSecretValue.html) を参照してください。
`get_secret()` には以下のパラメータがあります。
secretId
文字列: 取得するシークレットの Amazon リソースネーム (ARN) またはフレンドリ名。
secretType
文字列: シークレットタイプ。有効な値: `SecretString` \$1 `SecretBinary`。
SecretString
+ APIs、、 AWS CLIまたは AWS Secrets Manager コンソールを使用して JSON オブジェクトとして作成するシークレットの場合:
+ `key` パラメータの値を指定すると、この関数は指定されたキーの値を返します。
+ `key` パラメータの値を指定しない場合、この関数は JSON オブジェクト全体を返します。
+ API または AWS CLIを使用して非 JSON オブジェクトとして作成するシークレットについては、以下を実行します。
+ `key` パラメータの値を指定すると、この関数は例外で失敗します。
+ `key` パラメータの値を指定しない場合、この関数はシークレットの内容を返します。
SecretBinary
+ `key` パラメータの値を指定すると、この関数は例外で失敗します。
+ `key` パラメータの値を指定しない場合、この関数は base64 でエンコードされた UTF-8 文字列としてシークレット値を返します。
key
(オプション) 文字列: シークレットの `SecretString` フィールドに保存されている JSON オブジェクト内のキー名。JSON オブジェクト全体ではなく、シークレットに保存されているキーの値のみを取得する場合は、この値を使用します。
このパラメータの値を指定し、シークレットの `SecretString` フィールド内に JSON オブジェクトが含まれていない場合、この関数は例外で失敗します。
roleArn
文字列: `secretsmanager:GetSecretValue` および `secretsmanager:DescribeSecret` アクセス許可を持つロール ARN。
**注記**
この関数は常に、シークレットの現在のバージョン (`AWSCURRENT` タグ付きのバージョン) を返します。 AWS IoT ルールエンジンは、各シークレットを最大 15 分間キャッシュします。その結果、ルールエンジンがシークレットを更新するのに最長で 15 分かかることがあります。つまり、 での更新から最大 15 分後にシークレットを取得した場合 AWS Secrets Manager、この関数は以前のバージョンを返す可能性があります。
この関数は計測されませんが、 AWS Secrets Manager 料金が適用されます。シークレットキャッシュメカニズムにより、ルールエンジンが AWS Secrets Managerを呼び出すことがあります。ルールエンジンは完全に分散されたサービスであるため、15 分のキャッシュウィンドウ中にルールエンジンから複数の Secrets Manager API 呼び出しが実行される場合があります。
例:
次の API キー認証の例のように、HTTPS ルールアクションの認証ヘッダーで `get_secret` 関数を使用できます。
```
"API_KEY": "${get_secret('API_KEY', 'SecretString', 'API_KEY_VALUE', 'arn:aws:iam::12345678910:role/getsecret')}"
```
HTTPS ルールアクションの詳細については、「[HTTP](https-rule-action.md)」を参照してください。
## get\$1thing\$1shadow(thingName、shadowName、roleArn)
指定されたモノの指定されたシャドウを返します。SQL バージョン 2016-03-23 以降でサポートされています。
thingName
文字列: シャドウを取得する対象のモノの名前。
shadowName
(オプション) 文字列: シャドウの名前。このパラメータは、名前の付きのシャドウを参照する場合にのみ必要です。
roleArn
文字列: `iot:GetThingShadow` アクセス権限を持つロール ARN。
例:
名前付きシャドウとともに使用する場合は、`shadowName` パラメータを指定します。
```
SELECT * from 'topic/subtopic'
WHERE
get_thing_shadow("MyThing","MyThingShadow","arn:aws:iam::123456789012:role/AllowsThingShadowAccess")
.state.reported.alarm = 'ON'
```
名前のないシャドウとともに使用する場合は、`shadowName` パラメータを省略します。
```
SELECT * from 'topic/subtopic'
WHERE
get_thing_shadow("MyThing","arn:aws:iam::123456789012:role/AllowsThingShadowAccess")
.state.reported.alarm = 'ON'
```
## get\$1user\$1properties(userPropertyKey)
MQTT5 でサポートされているプロパティヘッダーの一種であるユーザープロパティを参照します。
userProperty
文字列: ユーザープロパティは、キーと値のペアです。この関数は、キーを引数にとり、関連するキーと一致するすべての値の配列を返します。
**関数の引数**
メッセージヘッダー内の以下のユーザープロパティの場合:
| キー | 値 |
| --- | --- |
| あるキー | ある値 |
| 別のキー | 別の値 |
| あるキー | 重複したキーを持つ値 |
次の表に、予想される SQL の動作を示します。
| SQL | 返されるデータ型 | 返されるデータ値 |
| --- | --- | --- |
| get\$1user\$1properties('あるキー') | 文字列の配列 | ['some value', 'value with duplicate key'] |
| get\$1user\$1properties('別のキー') | 文字列の配列 | ['a different value'] |
| get\$1user\$1properties( ) | キーと値のペアのオブジェクトの配列 | [\$1'"some key": "some value"'\$1, \$1"other key": "a different value"\$1, \$1"some key": "value with duplicate key"\$1] |
| get\$1user\$1properties('存在しないキー') | 未定義 | |
以下の SQL ルール例では、ユーザープロパティ (MQTT5 プロパティヘッダーの一種) をペイロードに参照しています。
```
SELECT *, get_user_properties('user defined property key') as userProperty
FROM 'some/topic'
```
## ハッシュ関数
AWS IoT には、次のハッシュ関数が用意されています。
+ md2
+ md5
+ sha1
+ sha224
+ sha256
+ sha384
+ sha512
1 つの文字列引数を除くすべてのハッシュ関数。結果はその文字列のハッシュ値です。標準文字列変換は非文字列引数に適用されます。すべてのハッシュ関数は、SQL バージョン 2015-10-08 以降でサポートされます。
例:
`md2("hello")` = "a9046c73e00331af68917d3804f70655"
`md5("hello")` = "5d41402abc4b2a76b9719d911017c592"
## indexof(文字列、文字列)
最初の引数のサブ文字列として、2 番目の引数の最初のインデックス (ゼロベース) を返します。両方の引数は文字列であることが期待されます。文字列ではない引数は、標準文字列変換ルールに従います。この関数は、配列にではなく、文字列にのみ適用されます。SQL バージョン 2016-03-23 以降でサポートされています。
例:
`indexof("abcd", "bc") ` = 1
## isNull()
引数が `Null` 値である場合は true を返します。SQL バージョン 2016-03-23 以降でサポートされています。
例:
`isNull(5) ` = false。
`isNull(Null) ` = true。
****
| 引数の型 | 結果 |
| --- | --- |
| Int | false |
| Decimal | false |
| Boolean | false |
| String | false |
| Array | false |
| Object | false |
| Null | true |
| Undefined | false |
## isUndefined()
引数が `Undefined` である場合は true を返します。SQL バージョン 2016-03-23 以降でサポートされています。
例:
`isUndefined(5) ` = false。
`isUndefined(floor([1,2,3]))) ` = true。
****
| 引数の型 | 結果 |
| --- | --- |
| Int | false |
| Decimal | false |
| Boolean | false |
| String | false |
| Array | false |
| Object | false |
| Null | false |
| Undefined | true |
## length(文字列)
指定された文字列の文字数を返します。標準変換ルールは、非 `String` 引数に適用されます。SQL バージョン 2016-03-23 以降でサポートされています。
例:
`length("hi")` = 2
`length(false)` = 5
## ln(10 進数)
引数の自然対数を返します。`Decimal` 引数は関数適用の前に倍精度に丸められます。SQL バージョン 2015-10-08 以降でサポートされています。
例: `ln(e)` = 1。
****
| 引数の型 | 結果 |
| --- | --- |
| Int | Decimal (倍精度で)、引数の自然対数。 |
| Decimal | Decimal (倍精度で)、引数の自然対数。 |
| Boolean | Undefined. |
| String | Decimal (倍精度で)、引数の自然対数。文字列が Decimal に変換できない場合、結果は Undefined です。 |
| 配列 | Undefined. |
| オブジェクト | Undefined. |
| Null | Undefined. |
| 未定義 | Undefined. |
## log(10 進数)
引数の 10 を底とする対数を返します。`Decimal` 引数は関数適用の前に倍精度に丸められます。SQL バージョン 2015-10-08 以降でサポートされています。
例: `log(100)` = 2.0。
****
| 引数の型 | 結果 |
| --- | --- |
| Int | Decimal 「倍精度で」、引数の 10 を底とした対数。 |
| Decimal | Decimal 「倍精度で」、引数の 10 を底とした対数。 |
| Boolean | Undefined. |
| String | Decimal 「倍精度で」、引数の 10 を底とした対数。String が Decimal に変換できない場合、結果は Undefined です。 |
| 配列 | Undefined. |
| オブジェクト | Undefined. |
| Null | Undefined. |
| 未定義 | Undefined. |
## lower(文字列)
指定した `String` の小文字バージョンを返します。非文字列引数は標準変換ルールを使用して文字列に変換されます。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`lower("HELLO")` = "hello"。
`lower(["HELLO"])` = "[\$1"hello\$1"]"。
## lpad(文字列、Int)
2 番目の引数で指定された数のスペースを左詰めにした `String` 引数を返します。`Int` 引数は、0 ～ 1000 の間である必要があります。提供された値がこの有効な範囲の外にある場合は、引数は最も近い有効な値に設定されます (0 または 1000)。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`lpad("hello", 2)` = "` hello`".
`lpad(1, 3)` = "` 1`"
****
| 引数の型 1 | 引数の型 2 | 結果 |
| --- | --- | --- |
| String | Int | String、提供された String と同じ数のスペースを左詰めにして提供された Int。 |
| String | Decimal | Decimal 引数は最も近い Int に切り下げられ、String には指定された数のスペースを左詰めにします。 |
| String | String | 2 番目の引数は Decimal に変換され、最も近い Int に切り下げられます。また、String には指定された数のスペースが左詰めにされます。2 番目の引数が Int に変換できない場合、結果は Undefined です。 |
| その他の値 | Int/Decimal/String | 最初の値は、標準変換ルールを使用して String に変換された後、LPAD 関数がその String に適用されます。それが変換できない場合、結果は Undefined です。 |
| 任意の値 | その他の値 | Undefined. |
## ltrim(文字列)
提供される `String` から先頭の空白 (タブとスペース) をすべて削除します。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`Ltrim(" h i ")` = "hi "。
****
| 引数の型 | 結果 |
| --- | --- |
| Int | 先頭の空白がすべて削除された String の Int 表現。 |
| Decimal | 先頭の空白がすべて削除された String の Decimal 表現。 |
| Boolean | 先頭の空白がすべて削除されたブール (「true」または「false」) の String 表現。 |
| String | 先頭の空白がすべて削除された引数。 |
| 配列 | 先頭の空白がすべて削除された String の Array 表現 (標準変換ルールを使用)。 |
| オブジェクト | 先頭の空白がすべて削除されたオブジェクトの String 表現 (標準変換ルールを使用)。 |
| Null | Undefined. |
| 未定義 | Undefined. |
## machinelearning\$1predict (modelId, roleArn, record)
Amazon SageMaker AI モデルに基づいて、MQTT メッセージからのデータを使用して予測を行うには、`machinelearning_predict` 関数を使用します。SQL バージョン 2015-10-08 以降でサポートされています。`machinelearning_predict` 関数の引数は次のとおりです。
modelId
予測を実行する対象となるモデルの ID。このモデルのリアルタイムエンドポイントを有効にしておく必要があります。
roleArn
`machinelearning:Predict` アクセス許可および `machinelearning:GetMLModel` アクセス許可を許可するポリシーが指定され、予測を実行する対象となるモデルへのアクセスを許可する IAM ロール。
record
SageMaker AI Predict API に渡されるデータ。単一レイヤーの JSON オブジェクトとして表す必要があります。record が複数レベルの JSON オブジェクトの場合は、値のシリアル化によって平坦化されます。たとえば、次の JSON の場合:
```
{ "key1": {"innerKey1": "value1"}, "key2": 0}
```
次のようになります。
```
{ "key1": "{\"innerKey1\": \"value1\"}", "key2": 0}
```
この関数では、次のフィールドを持つ JSON オブジェクトが返されます。
predictedLabel
モデルに基づく入力の区分。
details
次の属性が含まれています。
PredictiveModelType
モデルのタイプ。有効な値は、REGRESSION、BINARY、MULTICLASS です。
Algorithm
予測を行うために SageMaker AI で使用されるアルゴリズム。この値は SGD にする必要があります。
predictedScores
各ラベルに対応する、未加工の分類スコアを格納します。
predictedValue
SageMaker AI によって予測された値。
## mod(10 進数、10 進数)
最初の引数を 2 番目の引数で割ったときの剰余を返します。[remainder(Decimal, Decimal)](#iot-func-remainder) と同等です。同じモジュロ機能に挿入演算子として「%」も使用できます。SQL バージョン 2015-10-08 以降でサポートされています。
例: `mod(8, 3)` = 2。
****
| 左のオペランド | 右のオペランド | 出力 |
| --- | --- | --- |
| Int | Int | Int、最初の引数を 2 番目の引数で割ったときの剰余。 |
| Int/Decimal | Int/Decimal | Decimal、最初の引数を 2 番目のオペランドで割ったときの剰余。 |
| String/Int/Decimal | String/Int/Decimal | すべての文字列を小数に変換した場合、結果は、最初の引数を 2 番目の引数で割ったときの剰余です。そうでない場合は、Undefined です。 |
| その他の値 | その他の値 | Undefined. |
## nanvl(AnyValue, AnyValue)
最初の引数が有効な `Decimal` ならば、最初の引数が返されます。それ以外の場合、2 番目の引数が返されます。SQL バージョン 2015-10-08 以降でサポートされています。
例: `Nanvl(8, 3)` = 8。
****
| 引数の型 1 | 引数の型 2 | 出力 |
| --- | --- | --- |
| 未定義 | 任意の値 | 2 番目の引数。 |
| Null | 任意の値 | 2 番目の引数。 |
| Decimal (NaN) | 任意の値 | 2 番目の引数。 |
| Decimal (not NaN) | 任意の値 | 最初の引数。 |
| その他の値 | 任意の値 | 最初の引数。 |
## newuuid()
16 バイトのランダムな UUID を返します。SQL バージョン 2015-10-08 以降でサポートされています。
例: `newuuid()` = `123a4567-b89c-12d3-e456-789012345000`
## numbytes(文字列)
指定された文字列の UTF-8 エンコードのバイト数を返します。標準変換ルールは、非 `String` 引数に適用されます。SQL バージョン 2016-03-23 以降でサポートされています。
例:
`numbytes("hi")` = 2
`numbytes("€") ` = 3
## parse\$1time(String, Long[, String])
`parse_time` 機能を使用して、タイムスタンプを人間が判読可能な日付/時刻形式にフォーマットします。SQL バージョン 2016-03-23 以降でサポートされています。タイムスタンプ文字列をミリ秒に変換するには、「[time\$1to\$1epoch(String, String)](#iot-sql-function-time-to-epoch)」を参照してください。
`parse_time` 関数は次の引数を想定します。
pattern
(文字列) [Joda-Time フォーマット](http://www.joda.org/joda-time/apidocs/org/joda/time/format/DateTimeFormat.html)に従う日付/時刻パターン。
timestamp
(ロング) Unix エポックからミリ秒単位でフォーマットされる時間。関数「[timestamp()](#iot-function-timestamp)」を参照してください。
timezone
(文字列) フォーマットされた日付/時刻のタイムゾーン。デフォルトは「UTC」です。この関数は、「[Joda-Time のタイムゾーン](http://joda-time.sourceforge.net/timezones.html)」をサポートしています。この引数はオプションです。
例:
このメッセージがトピック「A/B」に公開されると、ペイロード `{"ts": "1970.01.01 AD at 21:46:40 CST"}` が S3 バケットに送信されます。
```
{
"ruleArn": "arn:aws:iot:us-east-2:ACCOUNT_ID:rule/RULE_NAME",
"topicRulePayload": {
"sql": "SELECT parse_time(\"yyyy.MM.dd G 'at' HH:mm:ss z\", 100000000, 'America/Belize' ) as ts FROM 'A/B'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"s3": {
"roleArn": "arn:aws:iam::ACCOUNT_ID:rule:role/ROLE_NAME",
"bucketName": "BUCKET_NAME",
"key": "KEY_NAME"
}
}
],
"ruleName": "RULE_NAME"
}
}
```
このメッセージがトピック「A/B」に公開されると、`{"ts": "2017.06.09 AD at 17:19:46 UTC"}` (ただし、現在の日付/時刻) と同様のペイロードが S3 バケットに送信されます。
```
{
"ruleArn": "arn:aws:iot:us-east-2:ACCOUNT_ID:rule/RULE_NAME",
"topicRulePayload": {
"sql": "SELECT parse_time(\"yyyy.MM.dd G 'at' HH:mm:ss z\", timestamp() ) as ts FROM 'A/B'",
"awsIotSqlVersion": "2016-03-23",
"ruleDisabled": false,
"actions": [
{
"s3": {
"roleArn": "arn:aws:iam::ACCOUNT_ID:rule:role/ROLE_NAME",
"bucketName": "BUCKET_NAME",
"key": "KEY_NAME"
}
}
],
"ruleName": "RULE_NAME"
}
}
```
`parse_time()` は、置換テンプレートとしても使用できます。たとえば、このメッセージがトピック「A/B」に公開されると、ペイロードは S3 バケットに key = 「2017」で送信されます。
```
{
"ruleArn": "arn:aws:iot:us-east-2:ACCOUNT_ID:rule/RULE_NAME",
"topicRulePayload": {
"sql": "SELECT * FROM 'A/B'",
"awsIotSqlVersion": "2016-03-23",
"ruleDisabled": false,
"actions": [{
"s3": {
"roleArn": "arn:aws:iam::ACCOUNT_ID:rule:role/ROLE_NAME",
"bucketName": "BUCKET_NAME",
"key": "${parse_time('yyyy', timestamp(), 'UTC')}"
}
}],
"ruleName": "RULE_NAME"
}
}
```
## power(10 進数、10 進数)
最初の引数を 2 番目の引数の累乗にして返します。`Decimal` 引数は関数適用の前に倍精度に丸められます。SQL バージョン 2015-10-08 以降でサポートされています。SQL バージョン 2015-10-08 以降でサポートされています。
例: `power(2, 5)` = 32.0。
****
| 引数の型 1 | 引数の型 2 | 出力 |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Decimal「倍精度で」、最初の引数を 2 番目の引数の累乗にします。 |
| Int/Decimal/String | Int/Decimal/String | Decimal(倍精度で)、最初の引数を 2 番目の引数の累乗にします。すべての文字列は小数に変換されます。いずれかの String が Decimal への変換に失敗したら、結果は Undefined です。 |
| その他の値 | その他の値 | Undefined. |
## principal()
トリガーメッセージの発行方法に基づいて、デバイスが認証に使用するプリンシパルを返します。次の表は、発行方法とプロトコルごとに返されるプリンシパルについて説明しています。
****
| メッセージの発行方法 | プロトコル | 認証情報のタイプ | プリンシパル |
| --- | --- | --- | --- |
| MQTT クライアント | MQTT | X.509 デバイス証明書 | X.509 証明書のサムプリント |
| AWS IoT コンソール MQTT クライアント | MQTT | IAM ユーザーまたはロール | iam-role-id:session-name |
| AWS CLI | HTTP | IAM ユーザーまたはロール | userid |
| AWS IoT デバイス SDK | MQTT | X.509 デバイス証明書 | X.509 証明書のサムプリント |
| AWS IoT デバイス SDK | MQTT over WebSocket | IAM ユーザーまたはロール | userid |
次の例は、`principal()` が返すことができるさまざまなタイプの値を示しています。
+ X.509 証明書のサムプリント: `ba67293af50bf2506f5f93469686da660c7c844e7b3950bfb16813e0d31e9373`
+ IAM ロール ID とセッション名: `ABCD1EFG3HIJK2LMNOP5:my-session-name`
+ ユーザー ID: `ABCD1EFG3HIJK2LMNOP5` を返します
## rand()
0.0 から 1.0 までの間で疑似ランダムで、均等に分散された倍を返します。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`rand()` = 0.8231909191640703
## regexp\$1matches(文字列、文字列)
文字列 (最初の引数) に、正規表現 (2 番目の引数) の一致が含まれている場合は、true を返します。正規表現で `|` を使用する場合は、`()` で使用します。
例:
`regexp_matches("aaaa", "a{2,}") ` = true。
`regexp_matches("aaaa", "b")` = false。
`regexp_matches("aaa", "(aaa|bbb)") ` = true。
`regexp_matches("bbb", "(aaa|bbb)") ` = true。
`regexp_matches("ccc", "(aaa|bbb)") ` = false。
**最初の引数:**
| 引数の型 | 結果 |
| --- | --- |
| Int | String の Int 表現。 |
| Decimal | String の Decimal 表現。 |
| Boolean | ブール (「true」または「false」) の String 表現。 |
| String | 。String |
| 配列 | String の Array 表現 (標準変換ルールを使用)。 |
| オブジェクト | オブジェクトの String 表現 (標準変換ルールを使用)。 |
| Null | Undefined. |
| 未定義 | Undefined. |
*2 番目の引数:*
有効な正規表現の式である必要があります。非文字列型は標準変換ルールを使用して `String` に変換されます。型により、結果として生じる文字列が有効な正規表現でない場合もあります。(変換された) 引数が有効な正規表現でない場合、結果は `Undefined` です。
## regexp\$1replace(文字列、文字列、文字列)
最初の引数にある 2 番目の引数 (正規表現) の出現すべてを 3 番目の引数で置き換えます。「\$1」でキャプチャグループを参照します。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`regexp_replace("abcd", "bc", "x")` = "axd"。
`regexp_replace("abcd", "b(.*)d", "$1")` = "ac"。
**最初の引数:**
| 引数の型 | 結果 |
| --- | --- |
| Int | String の Int 表現。 |
| Decimal | String の Decimal 表現。 |
| Boolean | ブール (「true」または「false」) の String 表現。 |
| String | ソース値。 |
| 配列 | String の Array 表現 (標準変換ルールを使用)。 |
| オブジェクト | オブジェクトの String 表現 (標準変換ルールを使用)。 |
| Null | Undefined. |
| 未定義 | Undefined. |
*2 番目の引数:*
有効な正規表現の式である必要があります。非文字列型は標準変換ルールを使用して `String` に変換されます。型により、結果として生じる文字列が有効な正規表現でない場合もあります。(変換された) 引数が有効な正規表現でない場合、結果は `Undefined` です。
*3 番目の引数:*
有効な正規表現の置換文字列である必要があります。(キャプチャグループを参照できます。) 非文字列型は標準変換ルールを使用して `String` に変換されます。(変換された) 引数が有効な正規表現の置換文字列でない場合、結果は `Undefined` です。
## regexp\$1substr(文字列、文字列)
最初のパラメータにある 2 番目のパラメータ (正規表現) の最初の一致を見つけます。「\$1」でキャプチャグループを参照します。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`regexp_substr("hihihello", "hi")` = "hi"
`regexp_substr("hihihello", "(hi)*")` = "hihi"
**最初の引数:**
| 引数の型 | 結果 |
| --- | --- |
| Int | String の Int 表現。 |
| Decimal | String の Decimal 表現。 |
| Boolean | ブール (「true」または「false」) の String 表現。 |
| String | String引数。 |
| 配列 | String の Array 表現 (標準変換ルールを使用)。 |
| オブジェクト | オブジェクトの String 表現 (標準変換ルールを使用)。 |
| Null | Undefined. |
| 未定義 | Undefined. |
*2 番目の引数:*
有効な正規表現の式である必要があります。非文字列型は標準変換ルールを使用して `String` に変換されます。型により、結果として生じる文字列が有効な正規表現でない場合もあります。(変換された) 引数が有効な正規表現でない場合、結果は `Undefined` です。
## remainder(Decimal, Decimal)
最初の引数を 2 番目の引数で割ったときの剰余を返します。[mod(10 進数、10 進数)](#iot-func-mod) と同等です。同じモジュロ機能に挿入演算子として「%」も使用できます。SQL バージョン 2015-10-08 以降でサポートされています。
例: `remainder(8, 3)` = 2。
****
| 左のオペランド | 右のオペランド | 出力 |
| --- | --- | --- |
| Int | Int | Int、最初の引数を 2 番目の引数で割ったときの剰余。 |
| Int/Decimal | Int/Decimal | Decimal、最初の引数を 2 番目のオペランドで割ったときの剰余。 |
| String/Int/Decimal | String/Int/Decimal | すべての文字列を小数に変換した場合、結果は、最初の引数を 2 番目の引数で割ったときの剰余です。そうでない場合は、Undefined です。 |
| その他の値 | その他の値 | Undefined. |
## replace(String, String, String)
最初の引数にある 2 番目の引数の出現すべてを 3 番目の引数で置き換えます。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`replace("abcd", "bc", "x")` = `"axd"`.
`replace("abcdabcd", "b", "x")` = `"axcdaxcd"`.
**すべての引数**
| 引数の型 | 結果 |
| --- | --- |
| Int | String の Int 表現。 |
| Decimal | String の Decimal 表現。 |
| Boolean | ブール (「true」または「false」) の String 表現。 |
| String | ソース値。 |
| 配列 | String の Array 表現 (標準変換ルールを使用)。 |
| オブジェクト | オブジェクトの String 表現 (標準変換ルールを使用)。 |
| Null | Undefined. |
| 未定義 | Undefined. |
## rpad(文字列、Int)
2 番目の引数で指定された数のスペースを右詰めにした文字列の引数を返します。`Int` 引数は、0 ～ 1000 の間である必要があります。提供された値がこの有効な範囲の外にある場合は、引数は最も近い有効な値に設定されます (0 または 1000)。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`rpad("hello", 2)` = "`hello `".
`rpad(1, 3)` = "`1 `".
****
| 引数の型 1 | 引数の型 2 | 結果 |
| --- | --- | --- |
| String | Int | String は、提供された Int と同じ数のスペースを右詰めにされています。 |
| String | Decimal | Decimal 引数は最も近い Int に切り下げられ、文字列は、提供された Int と同じ数のスペースを右詰めにされています。 |
| String | String | 2 番目の引数は Decimal に変換され、最も近い Int に切り下げられます。String は、Int 値と同じ数のスペースを右詰めにされています。 |
| その他の値 | Int/Decimal/String | 最初の値は、標準変換ルールを使用して String に変換された後、rpad 関数がその String に適用されます。それが変換できない場合、結果は Undefined です。 |
| 任意の値 | その他の値 | Undefined. |
## round(10 進数)
指定の `Decimal` を最も近い `Int` に丸めます。`Decimal` が 2 つの `Int` 値と等距離である場合 (例: 0.5)、`Decimal` は丸められます。SQL バージョン 2015-10-08 以降でサポートされています。
例: `Round(1.2)` = 1。
`Round(1.5)` = 2.
`Round(1.7)` = 2.
`Round(-1.1)` = -1.
`Round(-1.5)` = -2.
****
| 引数の型 | 結果 |
| --- | --- |
| Int | 引数。 |
| Decimal | Decimal は、最も近い Int に切り下げられます。 |
| String | Decimal は、最も近い Int に切り下げられます。文字列が Decimal に変換できない場合、結果は Undefined です。 |
| その他の値 | Undefined. |
## rtrim(文字列)
提供される `String` から末尾の空白 (タブとスペース) をすべて削除します。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`rtrim(" h i ")` = " h i"
****
| 引数の型 | 結果 |
| --- | --- |
| Int | String の Int 表現。 |
| Decimal | String の Decimal 表現。 |
| Boolean | ブール (「true」または「false」) の String 表現。 |
| 配列 | String の Array 表現 (標準変換ルールを使用)。 |
| オブジェクト | オブジェクトの String 表現 (標準変換ルールを使用)。 |
| Null | Undefined. |
| 未定義 | Undefined |
## sign(10 進数)
指定された数値の符号を返します。引数の符号が正の場合、1 を返します。引数の符号が負の場合、-1 を返します。引数が 0 の場合、0 を返します。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`sign(-7)` = -1.
`sign(0)` = 0.
`sign(13)` = 1.
****
| 引数の型 | 結果 |
| --- | --- |
| Int | Int、Int の値の符号。 |
| Decimal | Int、Decimal の値の符号。 |
| String | Int、Decimal の値の符号。文字列は Decimal の値に変換され、Decimal の値の符号が返されます。String が Decimal に変換できない場合、結果は Undefined です。SQL バージョン 2015-10-08 以降でサポートされています。 |
| その他の値 | Undefined. |
## sin(10 進数)
数値のサインをラジアンで返します。`Decimal` 引数は関数適用の前に倍精度に丸められます。SQL バージョン 2015-10-08 以降でサポートされています。
例: `sin(0)` = 0.0
****
| 引数の型 | 結果 |
| --- | --- |
| Int | Decimal 「倍精度で」、引数のサイン。 |
| Decimal | Decimal (倍精度で)、引数のサイン。 |
| Boolean | Undefined. |
| String | Decimal (倍精度で)、引数のサイン。文字列が Decimal に変換できない場合、結果は Undefined です。 |
| 配列 | Undefined. |
| オブジェクト | Undefined. |
| Null | Undefined. |
| Undefined | Undefined. |
## sinh(10 進数)
数値のハイパーボリックサインを返します。`Decimal` 値は関数適用の前に倍精度に丸められます。結果は倍精度の `Decimal` 値です。SQL バージョン 2015-10-08 以降でサポートされています。
例: `sinh(2.3)` = 4.936961805545957
****
| 引数の型 | 結果 |
| --- | --- |
| Int | Decimal (倍精度で)、引数のハイパーボリックサイン。 |
| Decimal | Decimal (倍精度で)、引数のハイパーボリックサイン。 |
| Boolean | Undefined. |
| String | Decimal (倍精度で)、引数のハイパーボリックサイン。文字列が Decimal に変換できない場合、結果は Undefined です。 |
| 配列 | Undefined. |
| オブジェクト | Undefined. |
| Null | Undefined. |
| 未定義 | Undefined. |
## sourceip()
デバイスまたはそれに接続するルーターの IP アドレスを取得します。デバイスがインターネットに直接接続されている場合、この関数はデバイスの送信元 IP アドレスを返します。デバイスがインターネットに接続するルーターに接続されている場合、関数はルーターの送信元 IP アドレスを返します。SQL バージョン 2016-03-23 でサポートされています。`sourceip()` はパラメータを取得しません。
**重要**
デバイスの公開送信元 IP アドレスは、多くの場合、インターネットサービスプロバイダーのルーターやケーブルモデムなどの最新のネットワークアドレス変換 (NAT) ゲートウェイの IP アドレスです。
例:
`sourceip()="192.158.1.38"`
`sourceip()="1.102.103.104"`
`sourceip()="2001:db8:ff00::12ab:34cd"`
SQL 例:
`SELECT *, sourceip() as deviceIp FROM 'some/topic'`
AWS IoT Core ルールアクションで sourceip() 関数を使用する方法の例:
**例 1**
次の例は、[DynamoDB アクション](https://docs.aws.amazon.com//iot/latest/developerguide/dynamodb-rule-action.html)で () 関数を[代替テンプレート](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html)として呼び出す方法を示しています。
```
{
"topicRulePayload": {
"sql": "SELECT * AS message FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"dynamoDB": {
"tableName": "my_ddb_table",
"hashKeyField": "key",
"hashKeyValue": "${sourceip()}",
"rangeKeyField": "timestamp",
"rangeKeyValue": "${timestamp()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDB"
}
}
]
}
}
```
**例 2**
次の例は、[代替テンプレート](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html)を使用して sourceip () 関数を MQTT ユーザープロパティとして追加する方法を示しています。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"topic": "${topic()}/republish",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_republish",
"headers": {
"payloadFormatIndicator": "UTF8_DATA",
"contentType": "rule/contentType",
"correlationData": "cnVsZSBjb3JyZWxhdGlvbiBkYXRh",
"userProperties": [
{
"key": "ruleKey1",
"value": "ruleValue1"
},
{
"key": "sourceip",
"value": "${sourceip()}"
}
]
}
}
}
]
}
}
```
メッセージブローカーと[基本的な取り込み](https://docs.aws.amazon.com//iot/latest/developerguide/iot-basic-ingest.html)パスの両方から AWS IoT Core ルールに渡すメッセージからソース IP アドレスを取得できます。IPv4 と IPv6 の両方のメッセージの両方の送信元 IP アドレスを使用できます。送信元 IP は次のように表示されます。
IPv6: `yyyy:yyyy:yyyy::yyyy:yyyy`
IPv4:`xxx.xxx.xxx.xxx`
**注記**
元の送信元 IP は [Republish アクション](republish-rule-action.md)には渡されません。
## substring(String, Int[, Int])
1 つか 2 つの `String` 値が続く `Int` を予想します。`String` および単一の `Int` 引数では、この関数は提供された `String` インデックス (ゼロベース、包括) から `Int` の端までの提供された `String` のサブストリングを返します。`String` および 2 つの `Int` 引数では、この関数は、最初の `String` インデックス引数 (ゼロベース、包括) から 2 番目の `Int` インデックス引数 (ゼロベース、除外) までの提供された `Int` のサブストリングを返します。ゼロ以下のインデックスはゼロに設定されます。`String` の長さを超過するインデックスは `String` の長さに設定されます。3 つの引数バージョンでは、最初のインデックスが 2 番目インデックスより大きい (または等しい) 場合、結果は空の `String` です。
提供された引数が (*String*, *Int*)、または (*String*, *Int*, *Int*) でない場合、引数に標準変換が適用され、正しい型への変換が試行されます。型が変換できない場合、関数の結果は `Undefined` です。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`substring("012345", 0)` = "012345"。
`substring("012345", 2)` = "2345"。
`substring("012345", 2.745)` = "2345"。
`substring(123, 2)` = "3"。
`substring("012345", -1)` = "012345"。
`substring(true, 1.2)` = "rue"。
`substring(false, -2.411E247)` = "false"。
`substring("012345", 1, 3)` = "12"。
`substring("012345", -50, 50)` = "012345"。
`substring("012345", 3, 1)` = "".
## sql\$1version()
このルールで指定されている SQL バージョンを返します。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`sql_version()` = "2016-03-23"
## sqrt(10 進数)
数値の平方根を返します。`Decimal` 引数は関数適用の前に倍精度に丸められます。SQL バージョン 2015-10-08 以降でサポートされています。
例: `sqrt(9)` = 3.0。
****
| 引数の型 | 結果 |
| --- | --- |
| Int | 引数の平方根。 |
| Decimal | 引数の平方根。 |
| Boolean | Undefined. |
| String | 引数の平方根。文字列が Decimal に変換できない場合、結果は Undefined です。 |
| 配列 | Undefined. |
| オブジェクト | Undefined. |
| Null | Undefined. |
| 未定義 | Undefined. |
## startswith(文字列、文字列)
最初の文字列引数が 2 番目の文字列引数で始まるかどうか、`Boolean` を返します。どちらかの引数が `Null` または `Undefined` の場合、結果は `Undefined` です。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`startswith("ranger","ran")` = true
****
| 引数の型 1 | 引数の型 2 | 結果 |
| --- | --- | --- |
| String | String | 最初の文字列が 2 番目の文字列で始まるかどうか。 |
| その他の値 | その他の値 | 両方の引数は標準変換ルールを使用して文字列に変換されます。最初の文字列が 2 番目の文字列で始まる場合は true を返します。どちらかの引数が Null または Undefined の場合、結果は Undefined です。 |
## tan(10 進数)
数値のタンジェントをラジアンで返します。`Decimal` 値は関数適用の前に倍精度に丸められます。SQL バージョン 2015-10-08 以降でサポートされています。
例: `tan(3)` = -0.1425465430742778
****
| 引数の型 | 結果 |
| --- | --- |
| Int | Decimal 「倍精度で」、引数のタンジェント。 |
| Decimal | Decimal 「倍精度で」、引数のタンジェント。 |
| Boolean | Undefined. |
| String | Decimal 「倍精度で」、引数のタンジェント。文字列が Decimal に変換できない場合、結果は Undefined です。 |
| 配列 | Undefined. |
| オブジェクト | Undefined. |
| Null | Undefined. |
| 未定義 | Undefined. |
## tanh(10 進数)
数値のハイパーボリックタンジェントをラジアンで返します。`Decimal` 値は関数適用の前に倍精度に丸められます。SQL バージョン 2015-10-08 以降でサポートされています。
例: `tanh(2.3)` = 0.9800963962661914
****
| 引数の型 | 結果 |
| --- | --- |
| Int | Decimal 「倍精度で」、引数の双曲線タンジェント。 |
| Decimal | Decimal 「倍精度で」、引数の双曲線タンジェント。 |
| Boolean | Undefined. |
| String | Decimal 「倍精度で」、引数の双曲線タンジェント。文字列が Decimal に変換できない場合、結果は Undefined です。 |
| 配列 | Undefined. |
| オブジェクト | Undefined. |
| Null | Undefined. |
| 未定義 | Undefined. |
## time\$1to\$1epoch(String, String)
`time_to_epoch` 関数を使用して、タイムスタンプ文字列を Unix エポック時間のミリ秒数に変換します。SQL バージョン 2016-03-23 以降でサポートされています。ミリ秒をフォーマットされたタイムスタンプ文字列に変換するには、「[parse\$1time(String, Long[, String])](#iot-sql-function-parse-time)」を参照してください。
`time_to_epoch` 関数は次の引数を想定します。
timestamp
(文字列) Unix エポックからミリ秒に変換されるタイムスタンプ文字列。タイムスタンプ文字列がタイムゾーンを指定しない場合、関数は UTC タイムゾーンを使用します。
pattern
(文字列) [JDK11 Time フォーマット](http://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html)に従う日付/時刻パターン。
例:
`time_to_epoch("2020-04-03 09:45:18 UTC+01:00", "yyyy-MM-dd HH:mm:ss VV")` = 1585903518000
`time_to_epoch("18 December 2015", "dd MMMM yyyy")` = 1450396800000
`time_to_epoch("2007-12-03 10:15:30.592 America/Los_Angeles", "yyyy-MM-dd HH:mm:ss.SSS z")` = 1196705730592
## timestamp()
AWS IoT ルールエンジンによって観測された 1970 年 1 月 1 日木曜日の協定世界時 (UTC) からの現在のタイムスタンプをミリ秒単位で返します。SQL バージョン 2015-10-08 以降でサポートされています。
例: `timestamp()` = `1481825251155`
## topic(10 進数)
ルールをトリガーしたメッセージが送信されたトピックを返します。パラメータが指定されていない場合、トピック全体が返されます。`Decimal` パラメータは、特定のトピックセグメントを指定するために使用され、1 は最初のセグメントを表します。`foo/bar/baz` トピックでは、topic(1) は `foo` を返し、topic(2) は `bar` を返す、と続いていきます。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`topic()` = "things/myThings/thingOne"
`topic(1)` = "things"
[基本的な取り込み](iot-basic-ingest.md)が使用されている場合、トピック (`$aws/rules/rule-name`) の最初のプレフィックスは topic() 関数では使用できません。たとえば、次のトピックがあるとします。
`$aws/rules/BuildingManager/Buildings/Building5/Floor2/Room201/Lights`
`topic()` = "Buildings/Building5/Floor2/Room201/Lights"
`topic(3)` = "Floor2"
## traceid()
MQTT メッセージのトレース ID (UUID) を返すか、または、メッセージが MQTT 経由で送信されなかった場合は `Undefined` を返します。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`traceid() ` = "12345678-1234-1234-1234-123456789012"
## transform(String, Object, Array)
`Array` パラメータの `Object` パラメータの指定された変換の結果を含むオブジェクトの配列を返します。
SQL バージョン 2016-03-23 以降でサポートされています。
文字列
使用する変換モード。サポートされている変換モードと、`Object` および `Array` パラメータから `Result` を作成する方法については、次の表を参照してください。
オブジェクト
`Array` の各要素に適用する属性を含むオブジェクト。
配列
`Object` の属性が適用されるオブジェクトの配列。
この配列内の各オブジェクトは、関数の応答内のオブジェクトに対応します。関数の応答の各オブジェクトには、元のオブジェクトに存在する属性と、`String` で指定された変換モードによって決定される `Object` によって提供される属性が含まれます。
| `String` パラメータ | `Object` パラメータ | `Array` パラメータ | 結果 |
| --- | --- | --- | --- |
| `enrichArray` | オブジェクト | オブジェクトの配列 | 各オブジェクトに `Array` パラメータの要素の属性と `Object` パラメータの属性が含まれるオブジェクトの配列。 |
| その他の値 | 任意の値 | 任意の値 | 未定義 |
**注記**
この関数によって返される配列は 128 KiB に制限されています。
### 変換関数の例 1
この例では、**transform()** 関数がデータオブジェクトと配列からオブジェクトの単一の配列を生成する方法を示します。
この例では、次のメッセージが MQTT トピック `A/B` に発行されます。
```
{
"attributes": {
"data1": 1,
"data2": 2
},
"values": [
{
"a": 3
},
{
"b": 4
},
{
"c": 5
}
]
}
```
トピックルールアクションのこの SQL ステートメントでは、`String` 値が `enrichArray` である **transform()** 関数を使用します。この例では、`Object` はメッセージペイロードの `attributes` プロパティで、`Array` は 3 つのオブジェクトを含む `values` 配列です。
```
select value transform("enrichArray", attributes, values) from 'A/B'
```
メッセージペイロードを受信すると、SQL ステートメントは次の応答と評価されます。
```
[
{
"a": 3,
"data1": 1,
"data2": 2
},
{
"b": 4,
"data1": 1,
"data2": 2
},
{
"c": 5,
"data1": 1,
"data2": 2
}
]
```
### 変換関数の例 2
この例では、**transform()** 関数がリテラル値を使用して、メッセージペイロードの個々の属性を含めて、名前を変更する方法を示します。
この例では、次のメッセージが MQTT トピック `A/B` に発行されます。これは [変換関数の例 1](#iot-func-transform-example1) で使用されたメッセージと同じものです。
```
{
"attributes": {
"data1": 1,
"data2": 2
},
"values": [
{
"a": 3
},
{
"b": 4
},
{
"c": 5
}
]
}
```
トピックルールアクションのこの SQL ステートメントでは、`String` 値が `enrichArray` である **transform()** 関数を使用します。**transform()** 関数の `Object` にはメッセージペイロードの値が `attributes.data1` である `key` という単一属性が含まれており、`Array` は、前述の例で使用されたものと同じ 3 つのオブジェクトを含む `values` 配列です。
```
select value transform("enrichArray", {"key": attributes.data1}, values) from 'A/B'
```
メッセージペイロードを受信すると、SQL ステートメントは次の応答と評価されます。応答で `data1` プロパティの名前が `key` になっていることに注意してください。
```
[
{
"a": 3,
"key": 1
},
{
"b": 4,
"key": 1
},
{
"c": 5,
"key": 1
}
]
```
### 変換関数の例 3
この例では、ネストされた SELECT 句で **transform()** 関数を使用して、複数の属性を選択し、後続の処理のために新しいオブジェクトを作成する方法を示します。
この例では、次のメッセージが MQTT トピック `A/B` に発行されます。
```
{
"data1": "example",
"data2": {
"a": "first attribute",
"b": "second attribute",
"c": [
{
"x": {
"someInt": 5,
"someString": "hello"
},
"y": true
},
{
"x": {
"someInt": 10,
"someString": "world"
},
"y": false
}
]
}
}
```
この変換関数の `Object` は、メッセージの `data2` オブジェクトの `a` 要素と `b` 要素を含む SELECT ステートメントによって返されるオブジェクトです。`Array` パラメータは、元のメッセージの `data2.c` 配列の 2 つのオブジェクトで構成されます。
```
select value transform('enrichArray', (select a, b from data2), (select value c from data2)) from 'A/B'
```
前述のメッセージにより、SQL ステートメントは次の応答に評価されます。
```
[
{
"x": {
"someInt": 5,
"someString": "hello"
},
"y": true,
"a": "first attribute",
"b": "second attribute"
},
{
"x": {
"someInt": 10,
"someString": "world"
},
"y": false,
"a": "first attribute",
"b": "second attribute"
}
]
```
この応答で返される配列は、`batchMode` をサポートするトピックルールアクションで使用できます。
## trim(文字列)
提供された `String` から、すべての先頭および末尾の空白を削除します。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`Trim(" hi ") ` = "hi"
****
| 引数の型 | 結果 |
| --- | --- |
| Int | すべての先頭および末尾の空白が削除された String の Int 表現。 |
| Decimal | すべての先頭および末尾の空白が削除された String の Decimal 表現。 |
| Boolean | すべての先頭および末尾の空白が削除された String (「true」または「false」) の Boolean 表現。 |
| String | すべての先頭および末尾の空白が削除された String。 |
| 配列 | 標準変換ルールを使用した String の Array 表現。 |
| オブジェクト | 標準変換ルールを使用したオブジェクトの String 表現。 |
| Null | Undefined. |
| 未定義 | Undefined. |
## trunc(10 進数、Int)
2 番目の引数で指定された `Decimal` の場所の数で最初の引数を切り捨てます。2 番目の引数がゼロよりより少ない場合は、ゼロに設定されます。2 番目の引数が 34 より大きい場合は、34 に設定されます。末尾のゼロは結果から省かれます。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`trunc(2.3, 0)` = 2.
`trunc(2.3123, 2)` = 2.31.
`trunc(2.888, 2)` = 2.88.
`trunc(2.00, 5)` = 2.
****
| 引数の型 1 | 引数の型 2 | 結果 |
| --- | --- | --- |
| Int | Int | ソース値。 |
| Int/Decimal | Int/Decimal | 最初の引数は 2 番目の引数で説明された長さに切り捨てられます。2 番目の引数は、Int でなければ、最も近い Int に切り下げられます。 |
| Int/Decimal/String | Int/Decimal | 最初の引数は 2 番目の引数で説明された長さに切り捨てられます。2 番目の引数は、Int でなければ、最も近い Int に切り下げられます。String は Decimal 値に変換されます。文字列変換が失敗した場合、結果は Undefined です。 |
| その他の値 | | Undefined. |
## upper(文字列)
指定した `String` の大文字バージョンを返します。非 `String` 引数は標準変換のルールを使用して `String` に変換されます。SQL バージョン 2015-10-08 以降でサポートされています。
例:
`upper("hello")` = "HELLO"
`upper(["hello"])` = "[\$1"HELLO\$1"]"
# リテラル
ルール SQL の SELECT および WHERE 句で直接リテラルオブジェクトを指定でき、情報を渡すのに役立ちます。
**注記**
リテラルは SQL バージョン 2016-03-23 以降を使用する場合にのみ利用可能です。
JSON オブジェクトの構文が使用されています (キーと値のペア、カンマ区切り、キーが文字列で値が JSON 値なら波括弧 \$1\$1 で囲む)。以下に例を示します。
トピックに公開された受信ペイロード `topic/subtopic`: `{"lat_long": [47.606,-122.332]}`
SQL ステートメント: `SELECT {'latitude': get(lat_long, 0),'longitude':get(lat_long, 1)} as lat_long FROM 'topic/subtopic'`
結果の出力ペイロードは次のとおりです: `{"lat_long":{"latitude":47.606,"longitude":-122.332}}`。
ルール SQL の SELECT および WHERE 句で直接配列を指定でき、情報をグループ化できます。JSON の構文が使用されています (カンマ区切りの項目を角括弧 [] でラップし、配列リテラルを作成する)。以下に例を示します。
トピックに公開された受信ペイロード `topic/subtopic`: `{"lat": 47.696, "long": -122.332}`
SQL ステートメント: `SELECT [lat,long] as lat_long FROM 'topic/subtopic'`
結果の出力ペイロードは次のとおりです: `{"lat_long": [47.606,-122.332]}`。
# Case ステートメント
Case ステートメントを使用して、switch ステートメントと同様に、実行のブランチができます。
構文:
```
CASE v WHEN t[1] THEN r[1]
WHEN t[2] THEN r[2] ...
WHEN t[n] THEN r[n]
ELSE r[e] END
```
*`v`* 式が評価され、各 `WHEN` 句の *`t[i]`* 値と等しいかどうか照合されます。一致がある場合は、対応する *`r[i]`* 式が `CASE` ステートメントの結果になります。`WHEN` 句は順番に評価され、一致する句が複数ある場合、最初に一致した句の結果が `CASE` ステートメントの結果になります。一致するものがない場合は、`ELSE` 句の *`r[e]`* が結果です。一致するものがなく、`ELSE` 句もない場合、結果は `Undefined` です。
`CASE` ステートメントには少なくとも 1 つの `WHEN` 句が必要です。`ELSE` 句はオプションです。
例:
トピック `topic/subtopic` に公開された受信ペイロード:
```
{
"color":"yellow"
}
```
SQL ステートメント:
```
SELECT CASE color
WHEN 'green' THEN 'go'
WHEN 'yellow' THEN 'caution'
WHEN 'red' THEN 'stop'
ELSE 'you are not at a stop light' END as instructions
FROM 'topic/subtopic'
```
結果の出力ペイロードは次のとおりです。
```
{
"instructions":"caution"
}
```
**注記**
*`v`* が `Undefined` の場合、CASE ステートメントの結果は `Undefined` です。
# JSON 拡張
入れ子になった JSON オブジェクトに対応するには、次に示す ANSI SQL 構文への拡張を使用できます。
"." 演算子
この演算子は、埋め込み JSON オブジェクトのメンバーにアクセスします。ANSI SQL や JavaScript の場合と同じ機能があります。以下に例を示します。
```
SELECT foo.bar AS bar.baz FROM 'topic/subtopic'
```
`topic/subtopic` トピックに送信される次のメッセージペイロードから、`foo` オブジェクト内の `bar` プロパティの値を選択します。
```
{
"foo": {
"bar": "RED",
"bar1": "GREEN",
"bar2": "BLUE"
}
}
```
JSON プロパティ名にハイフン文字または数字が含まれている場合、「ドット」表記は機能しません。代わりに、[get 関数](iot-sql-functions.md#iot-sql-function-get)を使用してプロパティの値を抽出します。
この例では、次のメッセージが `iot/rules` トピックに送信されます。
```
{
"mydata": {
"item2": {
"0": {
"my-key": "myValue"
}
}
}
}
```
通常、`my-key` の値はこのクエリのように識別されます。
```
SELECT * from iot/rules WHERE mydata.item2.0.my-key= "myValue"
```
ただし、プロパティ名`my-key` にはハイフンが含まれ、`item2`には数字が含まれるため、次のクエリが示すように [get 関数](iot-sql-functions.md#iot-sql-function-get)を使用する必要があります。
```
SELECT * from 'iot/rules' WHERE get(get(get(mydata,"item2"),"0"),"my-key") = "myValue"
```
`*` 演算子
ANSI SQL の `*` ワイルドカードと同じ機能があります。SELECT 句のみで使用され、メッセージデータを含む新しい JSON オブジェクトを作成します。メッセージペイロードが JSON 形式でない場合、`*` はメッセージペイロード全体を raw バイトとして返します。以下に例を示します。
```
SELECT * FROM 'topic/subtopic'
```
**属性値に対する関数の適用**
以下に、デバイスから発行される JSON ペイロードの例を示します。
```
{
"deviceid" : "iot123",
"temp" : 54.98,
"humidity" : 32.43,
"coords" : {
"latitude" : 47.615694,
"longitude" : -122.3359976
}
}
```
次の例では、JSON ペイロード内の属性値に関数を適用しています。
```
SELECT temp, md5(deviceid) AS hashed_id FROM topic/#
```
このクエリの結果は、次の JSON オブジェクトです。
```
{
"temp": 54.98,
"hashed_id": "e37f81fb397e595c4aeb5645b8cbbbd1"
}
```
# 置換テンプレート
代替テンプレートを使用して、ルールがトリガーされてアクションを実行したときに返 AWS IoT される JSON データを拡張できます。置換テンプレートの構文は`${`*式*`}`です。*式*は、SELECT 句、WHERE 句、および AWS IoT で でサポートされている任意の式にすることができます[AWS IoT ルールアクション](iot-rule-actions.md)。この式をルールのアクションフィールドに接続して、アクションを動的に構成できます。実際には、この機能はアクションの情報の一部を置き換えます。これには、関数、演算子、および元のメッセージペイロードに存在する情報が該当します。
**重要**
置換テンプレート内の式は "SELECT..." ステートメントとは独立して評価されるため、AS 句を使用して作成されたエイリアスを参照することはできません。元のペイロード、[関数](iot-sql-functions.md)、および[演算子](iot-sql-operators.md)に存在する情報のみを参照できます。
サポートされる式の詳細については、「[AWS IoT SQL リファレンス](iot-sql-reference.md)」を参照してください。
次のルールアクションは、置換テンプレートをサポートします。各アクションは、置換可能なさまざまなフィールドをサポートしています。
+ [Apache Kafka](apache-kafka-rule-action.md)
+ [CloudWatch アラーム](cloudwatch-alarms-rule-action.md)
+ [CloudWatch Logs](cloudwatch-logs-rule-action.md)
+ [CloudWatch メトリクス](cloudwatch-metrics-rule-action.md)
+ [DynamoDB](dynamodb-rule-action.md)
+ [DynamoDBv2](dynamodb-v2-rule-action.md)
+ [Elasticsearch](elasticsearch-rule-action.md)
+ [HTTP](https-rule-action.md)
+ [AWS IoT Events](iotevents-rule-action.md)
+ [AWS IoT SiteWise](iotsitewise-rule-action.md)
+ [Kinesis Data Streams](kinesis-rule-action.md)
+ [Firehose](kinesis-firehose-rule-action.md)
+ [Lambda](lambda-rule-action.md)
+ [ロケーション](location-rule-action.md)
+ [OpenSearch](opensearch-rule-action.md)
+ [再発行](republish-rule-action.md)
+ [S3](s3-rule-action.md)
+ [SNS](sns-rule-action.md)
+ [SQS](sqs-rule-action.md)
+ [ステップ関数](stepfunctions-rule-action.md)
+ [Timestream](timestream-rule-action.md)
置換テンプレートは、ルール内のアクションパラメータに表示されます。
```
{
"sql": "SELECT *, timestamp() AS timestamp FROM 'my/iot/topic'",
"ruleDisabled": false,
"actions": [{
"republish": {
"topic": "${topic()}/republish",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}]
}
```
このルールが `my/iot/topic` に発行された次の JSON によってトリガーされた場合:
```
{
"deviceid": "iot123",
"temp": 54.98,
"humidity": 32.43,
"coords": {
"latitude": 47.615694,
"longitude": -122.3359976
}
}
```
次に`my/iot/topic/republish`、このルールは次の JSON を に発行します。これは から AWS IoT 置き換えられます`${topic()}/republish`。
```
{
"deviceid": "iot123",
"temp": 54.98,
"humidity": 32.43,
"coords": {
"latitude": 47.615694,
"longitude": -122.3359976
},
"timestamp": 1579637878451
}
```
# ネストされたオブジェクトのクエリ
ネストされた SELECT 句を使用して、配列および内部 JSON オブジェクト内の属性を照会できます。SQL バージョン 2016-03-23 以降でサポートされています。
次の 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 }
]
}
```
**Example**
次のルールを使用して、値を新しい配列に変換できます。
```
SELECT (SELECT VALUE n FROM e) as sensors FROM 'my/topic'
```
この場合、ルールにより、次の出力が生成されます。
```
{
"sensors": [
"temperature",
"light",
"acidity"
]
}
```
**Example**
同じ MQTT メッセージを使用して、次のルールを使い、ネストされたオブジェクト内の特定の値を照会することもできます。
```
SELECT (SELECT v FROM e WHERE n = 'temperature') as temperature FROM 'my/topic'
```
この場合、ルールにより、次の出力が生成されます。
```
{
"temperature": [
{
"v": 22.5
}
]
}
```
**Example**
また、より複雑なルールで出力を平坦化することもできます。
```
SELECT get((SELECT v FROM e WHERE n = 'temperature'), 0).v as temperature FROM 'topic'
```
この場合、ルールにより、次の出力が生成されます。
```
{
"temperature": 22.5
}
```
# バイナリペイロードの使用
メッセージのペイロードを raw バイナリデータとして (JSON オブジェクトではなく) 処理するには、\$1 演算子を使用して SELECT 句で参照できます。
**Topics**
+ [バイナリペイロードの例](#binary-payloads-examples)
+ [protobuf メッセージペイロードのデコード](#binary-payloads-protobuf)
## バイナリペイロードの例
メッセージペイロードを raw バイナリデータとして参照するために \$1 を使用するときは、ルールにデータを追加できます。空のペイロードまたは JSON ペイロードがある場合、結果のペイロードには、ルールを使用してデータを追加できます。以下は、サポートされる `SELECT` 句の例です
+ バイナリペイロードに \$1 のみを使用した以下の `SELECT` 句を使用できます。
+
```
SELECT * FROM 'topic/subtopic'
```
+
```
SELECT * FROM 'topic/subtopic' WHERE timestamp() % 12 = 0
```
+ データを追加して、以下の `SELECT` 句を使用することもできます。
+
```
SELECT *, principal() as principal, timestamp() as time FROM 'topic/subtopic'
```
+
```
SELECT encode(*, 'base64') AS data, timestamp() AS ts FROM 'topic/subtopic'
```
+ これらの `SELECT` 句をバイナリペイロードと使用することもできます。
+ 以下は、WHERE 句の `device_type` を参照します。
```
SELECT * FROM 'topic/subtopic' WHERE device_type = 'thermostat'
```
+ 以下もサポートされています。
```
{
"sql": "SELECT * FROM 'topic/subtopic'",
"actions": [
{
"republish": {
"topic": "device/${device_id}"
}
}
]
}
```
次のルールアクションはバイナリペイロードをサポートしていないので、それらをデコードする必要があります。
+ [Lambdaアクション](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rule-actions.html#lambda-rule)など、バイナリペイロード入力をサポートしないルールアクションの場合は、バイナリペイロードをデコードする必要があります。Lambda ルールアクションは、base64 エンコード済みで JSON ペイロードの場合、バイナリデータを受け取ることができます。ルールを以下のように変更することで、これを実行できます。
```
SELECT encode(*, 'base64') AS data FROM 'my_topic'
```
+ SQL ステートメントは、文字列を入力としてサポートしていません。文字列入力を JSON に変換するには、次のコマンドが実行できます。
```
SELECT decode(encode(*, 'base64'), 'base64') AS payload FROM 'topic'
```
## protobuf メッセージペイロードのデコード
[プロトコルバッファ (protobuf)](https://developers.google.com/protocol-buffers) は、構造化データをコンパクトなバイナリ形式でシリアル化するために使用されるオープンソースのデータ形式です。データをネットワーク経由で送信したり、ファイルに保存したりするために使用されます。Protobuf を使用すると、小さなパケットサイズで他のメッセージング形式よりも高速にデータを送信できます。 AWS IoT Core ルールは、[decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) SQL 関数を提供することで protobuf をサポートします。これにより、protobuf エンコードされたメッセージペイロードを JSON 形式にデコードし、ダウンストリームサービスにルーティングできます。このセクションでは、 AWS IoT Core ルールで protobuf デコードを設定する手順について、順を追って説明します。
**Topics**
+ [前提条件](#binary-payloads-protobuf-prerequisites)
+ [記述子ファイルの作成](#binary-payloads-protobuf-descriptor-steps)
+ [記述子ファイルを S3 バケットにアップロードする](#binary-payloads-protobuf-s3-steps)
+ [ルールで protobuf デコードを設定する](#binary-payloads-protobuf-steps)
+ [制限事項](#binary-payloads-protobuf-limitations)
+ [ベストプラクティス](#binary-payloads-protobuf-bestpractices)
### 前提条件
+ [プロトコルバッファ (protobuf)](https://developers.google.com/protocol-buffers) に関する基本事項の理解
+ メッセージタイプと関連する依存関係を定義する [`.proto` ファイル](https://developers.google.com/protocol-buffers/docs/proto3)
+ システムへの [protobuf コンパイラ (protoc)](https://github.com/protocolbuffers/protobuf/releases) のインストール
### 記述子ファイルの作成
記述子ファイルが既にある場合は、このステップを省略できます。記述子ファイル (`.desc`) は `.proto` ファイルのコンパイル版で、protobuf のシリアル化で使用されるデータ構造とメッセージタイプを定義するテキストファイルです。記述子ファイルを生成するには、`.proto` ファイルを定義し、[protoc](https://github.com/protocolbuffers/protobuf/releases) コンパイラを使用してそれをコンパイルする必要があります。
1. メッセージタイプを定義する `.proto` ファイルを作成します。`.proto` ファイルの例として、以下のようなものがあります。
```
syntax = "proto3";
message Person {
optional string name = 1;
optional int32 id = 2;
optional string email = 3;
}
```
この例の `.proto` ファイルでは、proto3 構文を使用してメッセージタイプ `Person` を定義します。`Person` メッセージ定義では、3 つのフィールド (名前、ID、E メール) を指定します。`.proto` ファイルメッセージ形式の詳細については、[言語ガイド (proto3)](https://developers.google.com/protocol-buffers/docs/proto3)を参照してください。
1. [protoc](https://github.com/protocolbuffers/protobuf/releases) コンパイラを使用して、`.proto` ファイルをコンパイルし、記述子ファイルを生成します。descriptor (`.desc`) ファイルを作成するコマンドの例として、次のものがあります。
```
protoc --descriptor_set_out=.desc \
--proto_path= \
--include_imports \
.proto
```
このコマンド例では、記述子ファイル を生成します。このファイル を使用して`.desc`、 AWS IoT Core で定義されたデータ構造に準拠する protobuf ペイロードをデコードできます`.proto`。
+ `--descriptor_set_out`
生成する記述子ファイル (`.desc`) の名前を指定します。
+ `--proto_path`
コンパイル中の `.proto` ファイルから参照するインポートされたファイルの場所を指定します。インポートされた `.proto` ファイルの場所が異なる場合は、フラグを複数回指定できます。
+ `--include_imports`
インポートされた `.proto` ファイルもすべてコンパイルして、`.desc` 記述ファイルに含めるように指定します。
+ `.proto`
コンパイルする `.proto` ファイルの名前を指定します。
protoc リファレンスの詳細については、[API リファレンス](https://developers.google.com/protocol-buffers/docs/reference/overview)を参照してください。
### 記述子ファイルを S3 バケットにアップロードする
記述子ファイル を作成したら`.desc`、 AWS API、 AWS SDK、または を使用して、記述子ファイルを `.desc` Amazon S3 バケットにアップロードします AWS マネジメントコンソール。
**重要な考慮事項**
+ ルールを設定する AWS リージョン のと同じ AWS アカウント の Amazon S3 バケットに記述子ファイルをアップロードしてください。
+ S3 `FileDescriptorSet`から を読み取る AWS IoT Core ためのアクセス許可を必ず付与してください。S3 バケットでサーバー側の暗号化が無効になっている場合、または S3 バケットが Amazon S3 管理キー (SSE-S3) を使用して暗号化されている場合、追加のポリシー設定は必要ありません。これは、バケットポリシーの例で実現できます。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Statement1",
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "s3:Get*",
"Resource": "arn:aws:s3:::/.desc"
}
]
}
```
+ S3 バケットが AWS Key Management Service キー (SSE-KMS) を使用して暗号化されている場合は、S3 バケットにアクセスするときにキーを使用するアクセス AWS IoT Core 許可を付与してください。そのためには、次のステートメントをキーポリシーに追加してください。
```
{
"Sid": "Statement1",
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey*",
"kms:DescribeKey"
],
"Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
```
### ルールで protobuf デコードを設定する
記述子ファイルを S3 バケットにアップロードしたら、[decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) SQL 関数を使用して、protobuf メッセージペイロード形式をデコードできる[ルール](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-rule.html)を設定します。詳細な関数の署名と例は、「*AWS IoT SQL リファレンス*」の「[decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) SQL 関数」に記載されています。
[decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) 関数を使用する SQL 式の例としては、次のようなものがあります。
```
SELECT VALUE decode(*, 'proto', '', '.desc', '', '') FROM ''
```
この式の例:
+ [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) SQL 関数を使用して、`*` から参照されるバイナリメッセージペイロードをデコードします。これは、protobuf でエンコードされたバイナリのペイロード、または base64 でエンコードされた protobuf ペイロードを表す JSON 文字列です。
+ 提供されたメッセージペイロードは、`PROTO_FILENAME.proto` で定義されている `Person` メッセージタイプを使用してエンコードされます。
+ `BUCKET NAME` という名前の Amazon S3 バケットには、`PROTO_FILENAME.proto` から生成された `FILENAME.desc` が含まれます。
設定が完了したら、ルールがサブスクライブされているトピック AWS IoT Core のメッセージを に発行します。
### 制限事項
AWS IoT Core ルールは protobuf をサポートしていますが、以下の制限があります。
+ [置換テンプレート](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html)内の protobuf メッセージペイロードのデコードはサポートされていません。
+ protobuf メッセージペイロードをデコードする場合、1 つの SQL 式内で [decode SQL 関数](iot-sql-functions.md#iot-sql-decode-base64)を最大 2 回使用できます。
+ インバウンドペイロードの最大サイズは 128 KiB (1KiB = 1024 バイト)、アウトバウンドペイロードの最大サイズは 128 KiB、Amazon S3 バケットに保存される `FileDescriptorSet` オブジェクトの最大サイズは 32 KiB です。
+ SSE-C 暗号化を使用して暗号化された Amazon S3 バケットはサポートされていません。
### ベストプラクティス
ここでは、ベストプラクティスおよびトラブルシューティングのヒントを説明します。
+ Amazon S3 バケットに proto ファイルをバックアップする。
問題が発生した場合に備えて、proto ファイルをバックアップすることをお勧めします。例えば、protoc の実行中にバックアップせずに proto ファイルを誤って変更すると、本稼働スタックで問題が発生する可能性があります。Amazon S3 バケットのファイルをバックアップする方法は複数あります。例えば、[S3 バケットでバージョニングを使用](https://docs.aws.amazon.com//AmazonS3/latest/userguide/Versioning.html)できます。Amazon S3 バケット内のファイルをバックアップする方法の詳細については、「*[Amazon S3 デベロッパーガイド](https://docs.aws.amazon.com//aws-backup/latest/devguide/recovery-points.html)*」を参照してください。
+ AWS IoT ログエントリを表示するようにログ記録を設定します。
CloudWatch でアカウントの AWS IoT ログをチェックできるように、 AWS IoT ログ記録を設定することをお勧めします。ルールの SQL クエリが外部関数を呼び出すと、 AWS IoT Core Rules は `eventType`の を持つログエントリを生成します。これには`FunctionExecution`、障害のトラブルシューティングに役立つ理由フィールドが含まれます。Amazon S3 オブジェクトが見つからない、または無効な protobuf ファイル記述子が含まれていることが考えられます。 AWS IoT ロギングを設定する方法とログエントリを確認する方法の詳細については、「[AWS IoT ロギングの設定](https://docs.aws.amazon.com//iot/latest/developerguide/configure-logging.html)」と「[ルールエンジンのログエントリ](https://docs.aws.amazon.com//iot/latest/developerguide/cwl-format.html#log-rules-fn-exec)」を参照してください。
+ 新しいオブジェクトキーを使用して `FileDescriptorSet` を更新し、ルール内のオブジェクトキーを更新する。
更新された記述子ファイルを Amazon S3 バケットにアップロードすることで `FileDescriptorSet` を更新できます。`FileDescriptorSet` への更新が反映されるまで、最大 15 分かかる場合があります。この遅延を避けるため、新しいオブジェクトキーを使用して更新した `FileDescriptorSet` をアップロードし、ルール内のオブジェクトキーを更新することをお勧めします。
# SQL バージョン
AWS IoT ルールエンジンは、SQL のような構文を使用して MQTT メッセージからデータを選択します。SQL ステートメントは、ルールが記述されている JSON ドキュメント内の `awsIotSqlVersion` プロパティで指定された SQL バージョンに基づいて解釈されます。JSON ルールドキュメントの構造については、「[ルールの作成](iot-create-rule.md)」を参照してください。`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"
}
}]
}
```
AWS IoT は現在、次の SQL バージョンをサポートしています。
+ `2016-03-23` – 2016 年 3 月 23 日にビルドされた SQL バージョン (推奨)。
+ `2015-10-08` – 2015 年 10 月 8 日にビルドされた元の SQL バージョン。
+ `beta` – 最新のベータ SQL バージョン。このバージョンでは、ルールへの変更が必要になる場合があります。
## SQL ルールエンジン 2016-03-23 バージョンの最新情報
+ 入れ子になっている JSON オブジェクトの選択が修正されました。
+ 配列クエリに関する修正が行われました。
+ オブジェクト間でのクエリがサポートされるようになりました。詳細については、「[ネストされたオブジェクトのクエリ](iot-sql-nested-queries.md)」を参照してください。
+ 最上位レベルのオブジェクトとして配列を出力できるようになりました。
+ JSON および非 JSON 形式のデータに適用できる `encode(value, encodingScheme)` 関数の追加。詳細については、「[encode 関数](iot-sql-functions.md#iot-sql-encode-payload)」を参照してください。
### 最上位レベルのオブジェクトとして `Array` を出力する
この機能を使用すると、ルールから、最上位レベルのオブジェクトとして配列を返すことができます。たとえば、次の MQTT メッセージの場合:
```
{
"a": {"b":"c"},
"arr":[1,2,3,4]
}
```
次のルールを使用します。
```
SELECT VALUE arr FROM 'topic'
```
この場合、ルールにより、次の出力が生成されます。
```
[1,2,3,4]
```