Amazon EventBridge Pipes の入力変換 - Amazon EventBridge

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

Amazon EventBridge Pipes の入力変換

Amazon EventBridge Pipes では、データをエンリッチメントとターゲットに渡すときに、オプションで Input Transformer を使用できます。Input Transformer を使用すると、エンリッチメントサービスまたはターゲットサービスのニーズに対応するように JSON イベント入力ペイロードを再構成できます。Amazon API Gateway と API 送信先では、このようにして入力イベントを API の RESTful モデルに合わせて調整します。Input Transformer は InputTemplate パラメータとしてモデル化されます。フリーテキスト、イベントペイロードへの JSON パス、またはイベントペイロードへのインライン JSON パスを含む JSON オブジェクトを使用できます。エンリッチメントの場合、イベントペイロードはソースから送信されます。ターゲットの場合、イベントペイロードはエンリッチメントから返されるものです(パイプ上に設定されている場合)。イベントペイロード内のサービス固有のデータに加えて、InputTemplate予約変数を使用してパイプのデータを参照できます。

配列内の項目にアクセスするには、角括弧表記を使用します。

注記

EventBridge ですべての JSON パス構文がサポートされているわけではなく、構文は実行時に評価されます。サポートされている構文には以下が含まれます。

  • ドット表記 ($.detail など)

  • ダッシュ

  • 下線

  • アルファベットの文字

  • 配列インデックス

  • ワイルドカード (*)

Amazon SQS イベントペイロードを参照するサンプル InputTemplate パラメータは次のとおりです。

静的文字列

InputTemplate: "Hello, sender"

JSON パス

InputTemplate: <$.attributes.SenderId>

動的文字列

InputTemplate: "Hello, <$.attributes.SenderId>"

静的 JSON

InputTemplate: > { "key1": "value1", "key2": "value2", "key3": "value3", }

動的 JSON

InputTemplate: > { "key1": "value1" "key2": <$.body.key>, "d": <aws.pipes.event.ingestion-time> }

角括弧表記を使用して配列内の項目にアクセスします。

InputTemplate: > { "key1": "value1" "key2": <$.body.Records[3]>, "d": <aws.pipes.event.ingestion-time> }
注記

EventBridge では実行時に入力トランスフォーマーを置き換えることで、有効な JSON 出力を確保します。このため、JSON パスパラメータを参照する変数は、引用符で囲んでください。JSON オブジェクトまたは配列を参照する変数は、引用符で囲まないでください。

予約変数

入力テンプレートは次の予約変数を使用できます。

  • <aws.pipes.pipe-arn> – パイプの Amazon リソースネーム (ARN)。

  • <aws.pipes.pipe-name>— パイプの名前。

  • <aws.pipes.source-arn>— パイプのイベントソースの ARN。

  • <aws.pipes.enrichment-arn>— パイプのエンリッチメントの ARN。

  • <aws.pipes.target-arn>— パイプのターゲットの ARN。

  • <aws.pipes.event.ingestion-time>— Input Transformer によってイベントが受信された時間。これは ISO 8601 タイムスタンプです。この時間は、エンリッチメントがイベントの処理をいつ完了したかによって、エンリッチメント Input Transformer とターゲット Input Transformer で異なります。

  • <aws.pipes.event> — Input Transformerが受信したイベント。

    エンリッチメント Input Transformer の場合、これはソースからのイベントです。これには、ソースからの元のペイロードに加え、追加のサービス固有のメタデータが含まれます。このサービスに固有の例については、「Amazon EventBridge Pipes ソース」のトピックを参照してください。

    ターゲット Input Transformer の場合、これはエンリッチメントによって返されるイベントです (設定されている場合)。追加のメタデータはありません。そのため、エンリッチメントで返されるペイロードは JSON 以外の場合があります。パイプにエンリッチメントが設定されていない場合、これはメタデータを含むソースからのイベントです。

  • <aws.pipes.event.json>aws.pipes.event と同じですが、変数に値があるのは、ソースまたはエンリッチメントによって返された元のペイロードが JSON の場合に限られます。パイプに Amazon SQS body フィールドや Kinesis data などのエンコードされたフィールドがある場合、それらのフィールドはデコードされ、有効な JSON に変換されます。エスケープされないため、変数は JSON フィールドの値としてのみ使用できます。詳細については、「暗示的な本文データ解析」を参照してください。

入力変換の例

サンプルイベントとして使用できる Amazon EC2 イベントの例を次に示します。

{ "version": "0", "id": "7bf73129-1428-4cd3-a780-95db273d1602", "detail-type": "EC2 Instance State-change Notification", "source": "aws.ec2", "account": "123456789012", "time": "2015-11-11T21:29:54Z", "region": "us-east-1", "resources": [ "arn:aws:ec2:us-east-1:123456789012:instance/i-abcd1111" ], "detail": { "instance-id": "i-0123456789", "state": "RUNNING" } }

以下の JSON をTransformer として使用してみましょう。

{ "instance" : <$.detail.instance-id>, "state": <$.detail.state>, "pipeArn" : <aws.pipes.pipe-arn>, "pipeName" : <aws.pipes.pipe-name>, "originalEvent" : <aws.pipes.event.json> }

次はその出力です。

{ "instance" : "i-0123456789", "state": "RUNNING", "pipeArn" : "arn:aws:pipe:us-east-1:123456789012:pipe/example", "pipeName" : "example", "originalEvent" : { ... // commented for brevity } }

暗示的な本文データ解析

受信ペイロードの以下のフィールドは、Amazon SQS body オブジェクトのように JSON エスケープすることも、Kinesis data オブジェクトのように base64 でエンコードすることもできます。フィルタリングと入力変換の両方で、EventBridge はこれらのフィールドを有効な JSON に変換するので、サブ値を直接参照できます。例えば、<$.data.someKey> は Kinesis 場合です。

追加のメタデータなしでターゲットが元のペイロードを受け取れるようにするには、ソース固有のこの本文データを含む Input Transformer を使用します。例えば、Amazon SQS では <$.body>、Kinesis では <$.data> です。元のペイロードが有効な JSON 文字列 (例えば {"key": "value"}) の場合、ソース固有の本文データで Input Transformer を使用すると、元のソースペイロード内の引用符が削除されます。例えば、{"key": "value"} は、ターゲットに配信されたとき "{key: value}" になります。ターゲットに有効な JSON ペイロード (EventBridge Lambda や Step Functions など) が必要な場合、配信が失敗します。無効な JSON を生成せずにターゲットが元のソースデータを受信できるようにするには、ソース本文データ Input Transformer を JSON でラップします。例えば、{"data": <$.data>} と指定します。

また、暗示的な本文解析を使用すると、ほとんどのパイプターゲットまたはエンリッチメントパラメータの値を動的に入力することができます。詳細については、「動的パスパラメータ」を参照してください。

注記

元のペイロードが有効な JSON の場合、このフィールドには、エスケープされていない base64 でエンコードされていない JSON が含まれます。ただし、ペイロードが有効な JSON でない場合、EventBridge は Amazon SQS を除き、以下に示すフィールドを base64 でエンコードします。

  • Active MQdata

  • Kinesisdata

  • Amazon MSKkey および value

  • Rabbit MQdata

  • セルフマネージド Apache Kafkakey および value

  • Amazon SQSbody

入力変換に関する一般的な問題

これらは、EventBridge パイプで入力を変換するときの一般的な問題です。

  • 文字列の場合は、引用符が必要です。

  • テンプレートの JSON パスを作成する場合、検証は行われません。

  • 指定した変数と一致する JSON パスがイベントに存在しない場合、その変数は作成されず、出力にも表示されません。

  • aws.pipes.event.json のような JSON プロパティは JSON フィールドの値としてのみ使用でき、他の文字列に埋め込んで使用することはできません。

  • EventBridge は、ターゲットの入力テンプレートに入力する際に、入力パスによって抽出される値をエスケープしません。

  • JSON パスが JSON オブジェクトまたは配列を参照しているにもかかわらず、文字列では変数が参照されている場合、EventBridge は内部の引用符をすべて削除して文字列が有効であることを確認します。例えば、"Body is <$.body>" が作成されると、EventBridge はオブジェクトから引用符を削除します。

    したがって、単一の JSON パス変数に基づいて JSON オブジェクトを出力する場合、それをキーとして配置する必要があります。この例では、{"body": <$.body>} です。

  • 文字列を表す変数に引用符は必要ありません。使用することはできますが、EventBridge Pipes では、変換出力が有効な JSON になるように、変換中に文字列変数の値に自動的に引用符を追加します。EventBridge Pipes は JSON オブジェクトや配列を表す変数に引用符を追加しません。JSON オブジェクトや配列を表す変数に引用符を追加しないでください。

    たとえば、次の入力テンプレートには、文字列と JSON オブジェクトの両方を表す変数が含まれています。

    { "pipeArn" : <aws.pipes.pipe-arn>, "pipeName" : <aws.pipes.pipe-name>, "originalEvent" : <aws.pipes.event.json> }

    正しい引用符で囲まれた有効な JSON が生成されます。

    { "pipeArn" : "arn:aws:events:us-east-2:123456789012:pipe/example", "pipeName" : "example", "originalEvent" : { ... // commented for brevity } }
  • Lambda または Step Functions エンリッチメントまたはターゲットの場合、バッチサイズが 1 であっても、バッチは JSON 配列としてターゲットに配信されます。ただし、Input Transformers は引き続き JSON 配列の個々のレコードに適用され、配列全体には適用されません。詳細については、「Amazon EventBridge Pipes のバッチ処理と同時実行」を参照してください。