翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
バイナリペイロードの使用
メッセージのペイロードを raw バイナリデータとして (JSON オブジェクトではなく) 処理するには、* 演算子を使用して SELECT 句で参照できます。
このトピックの内容
バイナリペイロードの例
メッセージペイロードを raw バイナリデータとして参照するために * を使用するときは、ルールにデータを追加できます。空のペイロードまたは JSON ペイロードがある場合、結果のペイロードには、ルールを使用してデータを追加できます。以下は、サポートされる SELECT 句の例です
-
バイナリペイロードに * のみを使用した以下の
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アクションなど、バイナリペイロード入力をサポートしないルールアクションの場合は、バイナリペイロードをデコードする必要があります。Lambda ルールアクションは、base64 エンコード済みで JSON ペイロードの場合、バイナリデータを受け取ることができます。ルールを以下のように変更することで、これを実行できます。
SELECT encode(*, 'base64') AS data FROM 'my_topic' -
SQL ステートメントは、文字列を入力としてサポートしていません。文字列入力を JSON に変換するには、次のコマンドが実行できます。
SELECT decode(encode(*, 'base64'), 'base64') AS payload FROM 'topic'
protobuf メッセージペイロードのデコード
プロトコルバッファ (protobuf)
前提条件
-
プロトコルバッファ (protobuf)
に関する基本事項の理解 -
メッセージタイプと関連する依存関係を定義する
.protoファイル -
システムへの protobuf コンパイラ (protoc)
のインストール
記述子ファイルの作成
記述子ファイルが既にある場合は、このステップを省略できます。記述子ファイル (.desc) は .proto ファイルのコンパイル版で、protobuf のシリアル化で使用されるデータ構造とメッセージタイプを定義するテキストファイルです。記述子ファイルを生成するには、.proto ファイルを定義し、protoc
-
メッセージタイプを定義する
.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)を参照してください。 -
protoc
コンパイラを使用して、 .protoファイルをコンパイルし、記述子ファイルを生成します。descriptor (.desc) ファイルを作成するコマンドの例として、次のものがあります。protoc --descriptor_set_out=<FILENAME>.desc \ --proto_path=<PATH_TO_IMPORTS_DIRECTORY> \ --include_imports \ <PROTO_FILENAME>.protoこのコマンド例では、記述子ファイル を生成します。このファイル は
<FILENAME>.desc、 AWS IoT Core ルールが で定義されているデータ構造に準拠する protobuf ペイロードをデコードするために使用できます<PROTO_FILENAME>.proto。-
--descriptor_set_out生成する記述子ファイル (
<FILENAME>.desc) の名前を指定します。 -
--proto_pathコンパイル中の
.protoファイルから参照するインポートされたファイルの場所を指定します。インポートされた.protoファイルの場所が異なる場合は、フラグを複数回指定できます。 -
--include_importsインポートされた
.protoファイルもすべてコンパイルして、<FILENAME>.desc記述ファイルに含めるように指定します。 -
<PROTO_FILENAME>.protoコンパイルする
.protoファイルの名前を指定します。
protoc リファレンスの詳細については、API リファレンス
を参照してください。 -
記述子ファイルを S3 バケットにアップロードする
記述子ファイル を作成したら<FILENAME>.desc、 AWS API、 AWS SDK、または を使用して、Amazon <FILENAME>.desc Amazon S3 バケットに記述子ファイルをアップロードします AWS Management Console。
重要な考慮事項
-
記述子ファイルは、ルールを設定する 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:::<BUCKET NAME>/<FILENAME>.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) SQL 関数を使用して、protobuf メッセージペイロード形式をデコードできるルールを設定します。詳細な関数の署名と例は、「AWS IoT SQL リファレンス」の「decode(value, decodingScheme) SQL 関数」に記載されています。
decode(value, decodingScheme) 関数を使用する SQL 式の例としては、次のようなものがあります。
SELECT VALUE decode(*, 'proto', '<BUCKET NAME>, '<FILENAME>.desc', '<PROTO_FILENAME>', '<PROTO_MESSAGE_TYPE>') FROM '<MY_TOPIC>'
この式の例:
-
decode(value, decodingScheme) 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 をサポートしていますが、以下の制限があります。
-
置換テンプレート内の protobuf メッセージペイロードのデコードはサポートされていません。
-
protobuf メッセージペイロードをデコードする場合、1 つの SQL 式内で decode SQL 関数を最大 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 バケットでバージョニングを使用できます。Amazon S3 バケット内のファイルをバックアップする方法の詳細については、Amazon S3 開発者ガイドを参照してください。
-
AWS IoT ログエントリを表示するようにログ記録を設定します。
でアカウントの AWS IoT ログを確認できるように、 AWS IoT ログ記録を設定することをお勧めします CloudWatch。ルールの SQL クエリが外部関数を呼び出すと、 AWS IoT Core Rules は
eventTypeのログエントリを生成します。これにはFunctionExecution、失敗のトラブルシューティングに役立つ理由フィールドが含まれています。Amazon S3 オブジェクトが見つからない、または無効な protobuf ファイル記述子が含まれていることが考えられます。 AWS IoT ロギングを設定する方法とログエントリを確認する方法の詳細については、「AWS IoT ロギングの設定」と「ルールエンジンのログエントリ」を参照してください。 -
新しいオブジェクトキーを使用して
FileDescriptorSetを更新し、ルール内のオブジェクトキーを更新する。更新された記述子ファイルを Amazon S3 バケットにアップロードすることで
FileDescriptorSetを更新できます。FileDescriptorSetへの更新が反映されるまで、最大 15 分かかる場合があります。この遅延を避けるため、新しいオブジェクトキーを使用して更新したFileDescriptorSetをアップロードし、ルール内のオブジェクトキーを更新することをお勧めします。
