Amazon EventBridge 管道輸入轉換 - Amazon EventBridge
預留變數輸入轉換範例隱式主體數據解析轉換輸入的常見問題

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

Amazon EventBridge 管道輸入轉換

Amazon EventBridge 管道在將資料傳遞至擴充功能和目標時，支援選用的輸入轉換器。您可以使用輸入轉換器來重塑 JSON 事件輸入裝載，以滿足擴充或目標服務的需求。對於 Amazon API Gateway 和 API 目的地，這是您將輸入事件塑造為 API 的 RESTful 模型的方式。輸入轉換器被建模為 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 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 作為我們的轉換器。

{
  "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 除外。

  • 作用中的 MQ：data

  • kinesis：data

  • Amazon MSK：key 和 value

  • Rabbit MQ：data

  • 自我管理的 Apache Kafka;：key 和 value

  • Amazon SQS：body

轉換輸入的常見問題

這些是在 EventBridge 管道中轉換輸入時的一些常見問題：

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

  • 為您的範本建立 JSON 路徑時沒有驗證。

  • 如果您指定變數對應不存在於事件中的 JSON 路徑，則該變數不會建立，且不會出現在輸出中。

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

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

  • 如果 JSON 路徑參考 JSON 物件或陣列，但該變數在字串中參照，EventBridge 會移除任何內部引號，以確保有效的字串。例如，「主體為 <$ .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 Array 中的單個記錄，而不是整個數組。如需更多詳細資訊，請參閱 Amazon EventBridge 管道批處理和並發。