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

# 使用 代理程式預先處理資料
<a name="pre-processing"></a>

代理程式可以預先處理從受監控檔案剖析的記錄，然後再將其傳送到 Firehose 串流。您可以將 `dataProcessingOptions` 組態設定新增到您的檔案流程以啟用此功能。可新增一個或多個處理選項，這些選項將依照指定的順序執行。

代理程式支援以下處理選項。由於代理程式是開放原始碼，因此您可進一步開發和擴展其處理選項。您可以從 [Kinesis 代理程式](https://github.com/awslabs/amazon-kinesis-agent)下載代理程式。處理選項

`SINGLELINE`  
移除換行字元、前方空格及結尾空格，藉此將多列記錄轉換為單列記錄。  

```
{
    "optionName": "SINGLELINE"
}
```

`CSVTOJSON`  
將記錄從分隔符號區隔格式轉換為 JSON 格式。  

```
{
    "optionName": "CSVTOJSON",
    "customFieldNames": [ "field1", "field2", ... ],
    "delimiter": "yourdelimiter"
}
```  
`customFieldNames`  
[必要] 欄位名稱在每個 JSON 鍵值對中做為鍵。例如，如果您指定 `["f1", "f2"]`，記錄「v1、v2」將轉換為 `{"f1":"v1","f2":"v2"}`。  
`delimiter`  
在記錄做為分隔符號的字串。預設為逗號 (,)。

`LOGTOJSON`  
將記錄從日誌格式轉換為 JSON 格式。支援的日誌格式為 **Apache Common Log**、**Apache Combined Log**、**Apache Error Log**、以及 **RFC3164 Syslog**。  

```
{
    "optionName": "LOGTOJSON",
    "logFormat": "logformat",
    "matchPattern": "yourregexpattern",
    "customFieldNames": [ "field1", "field2", … ]
}
```  
`logFormat`  
[必要] 日誌項目格式。以下是可能的值：  
+ `COMMONAPACHELOG` – Apache Common Log 格式。根據預設，每個日誌項目皆有以下模式：「`%{host} %{ident} %{authuser} [%{datetime}] \"%{request}\" %{response} %{bytes}`」。
+ `COMBINEDAPACHELOG` – Apache Combined Log 格式。根據預設，每個日誌項目皆有以下模式：「`%{host} %{ident} %{authuser} [%{datetime}] \"%{request}\" %{response} %{bytes} %{referrer} %{agent}`」。
+ `APACHEERRORLOG` – Apache Error Log 格式。根據預設，每個日誌項目皆有以下模式：「`[%{timestamp}] [%{module}:%{severity}] [pid %{processid}:tid %{threadid}] [client: %{client}] %{message}`」。
+ `SYSLOG` – RFC3164 Syslog 格式。根據預設，每個日誌項目皆有以下模式：「`%{timestamp} %{hostname} %{program}[%{processid}]: %{message}`」。  
`matchPattern`  
覆寫指定日誌格式的預設模式。如果日誌項目使用自訂格式，則使用此設定從日誌項目擷取值。若您指定 `matchPattern`，您也必須指定 `customFieldNames`。  
`customFieldNames`  
自訂欄位名稱在每個 JSON 鍵值對中做為鍵。您可以使用此設定來定義從 `matchPattern` 擷取的值的欄位名稱，或覆寫預先定義的日誌格式的預設欄位名稱。

**Example ：LOGTOJSON 組態**  <a name="example-logtojson"></a>
這裡提供一個 Apache Common Log 項目轉換為 JSON 格式的 `LOGTOJSON` 組態範例：  

```
{
    "optionName": "LOGTOJSON",
    "logFormat": "COMMONAPACHELOG"
}
```
轉換前：  

```
64.242.88.10 - - [07/Mar/2004:16:10:02 -0800] "GET /mailman/listinfo/hsdivision HTTP/1.1" 200 6291
```
轉換後：  

```
{"host":"64.242.88.10","ident":null,"authuser":null,"datetime":"07/Mar/2004:16:10:02 -0800","request":"GET /mailman/listinfo/hsdivision HTTP/1.1","response":"200","bytes":"6291"}
```

**Example ：使用自訂欄位的 LOGTOJSON 組態**  <a name="example-logtojson-custom-fields"></a>
以下是另一個 `LOGTOJSON` 組態範例：  

```
{
    "optionName": "LOGTOJSON",
    "logFormat": "COMMONAPACHELOG",
    "customFieldNames": ["f1", "f2", "f3", "f4", "f5", "f6", "f7"]
}
```
使用此組態設定，前一個範例的相同 Apache Common Log 項目轉換為 JSON 格式如下：  

```
{"f1":"64.242.88.10","f2":null,"f3":null,"f4":"07/Mar/2004:16:10:02 -0800","f5":"GET /mailman/listinfo/hsdivision HTTP/1.1","f6":"200","f7":"6291"}
```

**Example ：轉換 Apache Common Log 項目**  <a name="example-apache-common-log-entry"></a>
下列流程組態將 Apache Common Log 項目轉換為 JSON 格式的單列記錄：  

```
{ 
    "flows": [
        {
            "filePattern": "/tmp/app.log*", 
            "deliveryStream": "my-delivery-stream",
            "dataProcessingOptions": [
                {
                    "optionName": "LOGTOJSON",
                    "logFormat": "COMMONAPACHELOG"
                }
            ]
        }
    ] 
}
```

**Example ：轉換多列記錄**  <a name="example-convert-multi-line"></a>
以下流程組態剖析第一行從「`[SEQUENCE=`」開始的多列記錄。每筆記錄都會先轉換為單列記錄。然後，根據定位鍵分隔符號從記錄中擷取值。擷取的值會對應到指定的 `customFieldNames` 值以形成 JSON 格式的單列記錄。  

```
{ 
    "flows": [
        {
            "filePattern": "/tmp/app.log*", 
            "deliveryStream": "my-delivery-stream",
            "multiLineStartPattern": "\\[SEQUENCE=",
            "dataProcessingOptions": [
                {
                    "optionName": "SINGLELINE"
                },
                {
                    "optionName": "CSVTOJSON",
                    "customFieldNames": [ "field1", "field2", "field3" ],
                    "delimiter": "\\t"
                }
            ]
        }
    ] 
}
```

**Example ：使用匹配模式的 LOGTOJSON 組態**  <a name="example-logtojson-match-pattern"></a>
以下是 Apache Common Log 項目轉換為 JSON 格式的 `LOGTOJSON` 組態範例，省略最後欄位 (位元組)：  

```
{
    "optionName": "LOGTOJSON",
    "logFormat": "COMMONAPACHELOG",
    "matchPattern": "^([\\d.]+) (\\S+) (\\S+) \\[([\\w:/]+\\s[+\\-]\\d{4})\\] \"(.+?)\" (\\d{3})",
    "customFieldNames": ["host", "ident", "authuser", "datetime", "request", "response"]
}
```
轉換前：  

```
123.45.67.89 - - [27/Oct/2000:09:27:09 -0400] "GET /java/javaResources.html HTTP/1.0" 200
```
轉換後：  

```
{"host":"123.45.67.89","ident":null,"authuser":null,"datetime":"27/Oct/2000:09:27:09 -0400","request":"GET /java/javaResources.html HTTP/1.0","response":"200"}
```