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

# Amazon EventBridge 管道輸入轉換
<a name="eb-pipes-input-transformation"></a>

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

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

**注意**  
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 物件或陣列的變數周圍加上引號。

## 預留變數
<a name="input-transform-reserved"></a>

輸入範本可以使用以下預留變數：
+ `<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 管道來源](eb-pipes-event-source.md) 中的主題。

  對於目標輸入轉換器，如果已設定，則這是擴充所傳回的事件，不含其他中繼資料。因此，擴充傳回的承載可能是非 JSON。如果管道上未設定擴充，則這是來自具有中繼資料的來源的事件。
+ `<aws.pipes.event.json>`：與 `aws.pipes.event` 相同，但如果来自源或由擴充傳回的原始有效負載為 JSON，則該變數才有值。如果管道具有編碼欄位，例如 Amazon SQS `body` 欄位或 Kinesis `data`，則會將這些欄位解碼並轉換為有效的 JSON。因為它不會逸出，因此變數只能用作 JSON 欄位的值。如需詳細資訊，請參閱[隱式主體資料解析](#input-transform-implicit)。

## 輸入轉換範例
<a name="input-transform-example"></a>

以下是我們可以用作範例事件的 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
  }
}
```

## 隱式主體資料解析
<a name="input-transform-implicit"></a>

傳入裝載中的下列欄位可能是 JSON 逸出，例如 Amazon SQS `body` 物件，或是以 base64 編碼的欄位，例如 Kinesis `data` 物件。針對[篩選](eb-pipes-event-filtering.md)和輸入轉換，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>}`。

隱含主體剖析也可用於動態填入大多數管道目標或擴充參數的值。如需詳細資訊，請參閱[動態路徑參數](eb-pipes-event-target.md#pipes-targets-dynamic-parms)

**注意**  
如果原始承載是有效的 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`

## 轉換輸入的常見問題
<a name="eb-pipes-transform-input-issues"></a>

這些是在 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 管道批次處理和並行](eb-pipes-batching-concurrency.md)。
+ 輸入轉換器和篩選可以擷取字串編碼一次的 JSON 值，但不能擷取字串編碼兩次的值。這通常發生在 Amazon SNS 訊息傳送到 Amazon SQS 時。當 Amazon SQS 收到 Amazon SNS 訊息時，它會將整個訊息字串化。當 Pipes 接著收到此 Amazon SQS 訊息時，Amazon SNS 訊息內容會出現在 `body` 欄位中且可供存取。不過，如果 Amazon SNS `Message` 欄位本身包含字串化 JSON，則該巢狀內容會進行雙重編碼，且輸入轉換器或篩選條件無法存取。例如， `<$.body.TopicArn>` 是可存取的，但如果 `Message` 欄位包含字串化 JSON，例如 則`<$.body.Message.operation>`不會`"{\\\"operation\\\":\\\"UPDATE\\\",\\\"email\\\":\\\"user@example.com\\\"}"`。

  若要解決此限制，請使用 Lambda 函數的擴充步驟來剖析雙編碼內容並擷取巢狀值。如需擴充功能的詳細資訊，請參閱 [擴充](pipes-enrichment.md)。