Amazon EventBridge Pipes 輸入轉換 - Amazon EventBridge

本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。

Amazon EventBridge Pipes 輸入轉換

Amazon EventBridge Pipes 在將資料傳遞至擴充功能和目標時,支援選用的輸入轉換器。您可以使用輸入轉換器來重塑JSON事件輸入承載,以滿足擴充或目標服務的需求。對於 Amazon API Gateway 和API目的地,這是您將輸入事件塑造為 RESTful模型的方式API。輸入轉換器被建模為 InputTemplate 參數。可以是任意文字、事件承載的JSON路徑,或包含事件承載內嵌JSON路徑的JSON物件。對於擴充,事件裝載來自來源。針對目標,如果在管道上設定,則事件有效負載是從擴充傳回。除了事件承載中的服務特定資料之外,您還可以在您的 InputTemplate 中使用保留變數來參考管道的資料。

若要存取陣列中的項目,請使用方括號標記法。

注意

EventBridge 不支援所有 JSON Path 語法,並在執行階段對其進行評估。支援的語法包括:

  • 點符號 (例如 $.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 Resource Name (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>:輸入變壓器所收到事件的時間。這是 ISO 8601 時間戳記。此時間對於擴充輸入變壓器和目標輸入變壓器而有所不同,具體取決於擴充完成處理事件的時間。

  • <aws.pipes.event>:輸入變壓器所收到的事件。

    對於擴充輸入變壓器,這是來源的事件。這包含來源的原始裝載,加上額外的服務特定中繼資料。如需服務的特定範例,請參閱 Amazon EventBridge 管道來源 中的主題。

    對於目標輸入轉換器,如果已設定,則這是擴充所傳回的事件,不含其他中繼資料。因此,擴充傳回的承載可能是非 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 } }

隱式主體資料解析

傳入承載中的下列欄位可能會JSON逸出,例如 Amazon SQS body 物件或 base64 編碼,例如 Kinesis data 物件。對於篩選和輸入轉換, 會將這些欄位 EventBridge 轉換為有效,JSON以便可以直接參考子值。例如,<$.data.someKey> 針對 Kinesis。

若要讓目標在沒有任何其他中繼資料的情況下接收原始有效負載,請使用輸入轉換器與特定於源的主體資料。例如,<$.body>適用於 Amazon SQS,或<$.data>適用於 Kinesis。如果原始承載是有效的JSON字串 (例如 {"key": "value"}),則將輸入轉換器與來源特定內文資料搭配使用會導致移除原始來源承載中的引號。例如,{"key": "value"} 傳送至目標時會變成 "{key: value}"。如果您的目標需要有效的JSON承載 (例如 EventBridge Lambda 或 Step Functions),這會導致交付失敗。若要讓目標在不產生無效 的情況下接收原始來源資料JSON,請在 中包裝來源內文資料輸入轉換器JSON。例如:{"data": <$.data>}

隱含主體剖析也可用於動態填入大多數管道目標或擴充參數的值。如需詳細資訊,請參閱 動態路徑參數

注意

如果原始承載有效 JSON,此欄位將包含未逸出、非base64 編碼的 JSON。不過,如果承載對下列欄位無效JSON, EventBridge 則base64 編碼為無效,但 Amazon 除外SQS。

  • 作用中的 MQdata

  • kinesisdata

  • Amazon MSKkeyvalue

  • Rabbit MQdata

  • 自我管理的 Apache Kafka;keyvalue

  • Amazon SQSbody

轉換輸入的常見問題

以下是轉換 EventBridge 管道輸入時的一些常見問題:

  • 針對字串,引號是必要的。

  • 為範本建立JSON路徑時,不會進行驗證。

  • 如果您指定變數以符合事件中不存在的JSON路徑,則不會建立該變數,也不會出現在輸出中。

  • JSON 像 這樣的屬性aws.pipes.event.json只能用作JSON欄位的值,不能在其他字串中內嵌。

  • EventBridge 在填入目標的輸入範本時, 不會逸出由輸入路徑 擷取的值。

  • 如果JSON路徑參考JSON物件或陣列,但在字串中參考變數, 會 EventBridge 移除任何內部引號,以確保有效的字串。例如,「Body is <$.body>」將導致從物件 EventBridge 中移除引號。

    因此,如果您想要根據單一JSON路徑變數輸出JSON物件,則必須將物件放置為金鑰。在此範例中,{"body": <$.body>}

  • 代表字串的變數不需要引號。它們是允許的,但 EventBridge 管道會在轉換期間自動將引號新增至字串變數值,以確保轉換輸出有效JSON。 EventBridge 管道不會將引號新增至代表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陣列形式將批次交付至目標。不過,輸入轉換器仍會套用至JSON陣列中的個別記錄,而不是陣列整體。如需詳細資訊,請參閱Amazon EventBridge 管道批處理和並發