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

# CloudWatch 中的 Contributor Insights 規則語法
<a name="ContributorInsights-RuleSyntax"></a>

本節說明 Contributor Insights 規則的語法。請只在您透過輸入 JSON 區塊來建立規則時使用此語法。如果您使用精靈建立規則，您便不需要了解語法。如需使用精靈建立規則的詳細資訊，請參閱 [在 CloudWatch 中建立 Contributor Insights 規則](ContributorInsights-CreateRule.md)。

所有規則與日誌事件欄位名稱及值進行的比對都區分大小寫。

以下範例示範 JSON 日誌的語法。

```
{
    "Schema": {
        "Name": "CloudWatchLogRule",
        "Version": 1
    },
    "LogGroupNames": [
        "API-Gateway-Access-Logs*",
        "Log-group-name2"
    ],
    "LogFormat": "JSON",
    "Contribution": {
        "Keys": [
            "$.ip"
        ],
        "ValueOf": "$.requestBytes",
        "Filters": [
            {
                "Match": "$.httpMethod",
                "In": [
                    "PUT"
                ]
            }
        ]
    },
    "AggregateOn": "Sum"
}
```Contributor Insights 規則中的欄位

結構描述  
 分析 CloudWatch Logs 資料之規則的 `Schema` 值必須總是為 `{"Name": "CloudWatchLogRule", "Version": 1}` 

LogGroupNames  
 字串陣列。針對陣列中的每個元素，您可以選擇在字串的結尾使用 `*` 來包含所有名稱開頭為該字首的日誌群組。  
請小心搭配日誌群組名稱使用萬用字元。每個符合規則的日誌事件都會產生費用。如果您不小心搜尋了比您預期數量更多的日誌群組，您可能會產生未預期的費用。如需詳細資訊，請參閱 [Amazon CloudWatch 定價](https://aws.amazon.com/cloudwatch/pricing)。

LogGroupARNs  
如果您要在 CloudWatch 跨帳戶觀察功能的監控帳戶中建立此規則，則可以使用 `LogGroupARNs` 來指定與監控帳戶連結之來源帳戶中的日誌群組，還可以指定監控帳戶自身中的日誌群組。您必須在規則中指定 `LogGroupNames` 或 `LogGroupARNs`，但不能同時指定兩者。  
 `LogGroupARNs` 是字串陣列。對於陣列中的每個元素，您可以在某些情況下選擇使用 `*` 作為萬用字元。例如，您可以指定 `arn:aws:logs:us-west-1:*:log-group/MyLogGroupName2`，以指定美國西部 (加利佛尼亞北部) 區域中所有來源帳戶以及監控帳戶中命名為 `MyLogGroupName2` 的日誌群組。您也可以指定 `arn:aws:logs:us-west-1:111122223333:log-group/GroupNamePrefix*`，來指定 111122223333 帳戶在美國西部 (加利佛尼亞北部) 中名稱以 `GroupNamePrefix` 開頭的所有日誌群組。  
您無法指定部分 AWS 帳戶 ID 做為萬用字元的字首。  
將萬用字元用於日誌群組 ARN 用時應小心。每個符合規則的日誌事件都會產生費用。如果您不小心搜尋了比您預期數量更多的日誌群組，您可能會產生未預期的費用。如需詳細資訊，請參閱 [Amazon CloudWatch 定價](https://aws.amazon.com/cloudwatch/pricing)。

LogFormat  
 有效值為 `JSON` 和 `CLF`。

Contribution  
 此物件包含 `Keys` 陣列 (其中最多可以有四個成員)、選用的單一 `ValueOf`，以及其中最多可包含四個 `Filters` 的選用陣列。

金鑰  
 最多四個日誌欄位的陣列，會用來作為分類參與者的維度。如果您輸入的索引鍵超過一個，索引鍵值的每個唯一組合都會計為唯一的參與者。欄位必須使用 JSON 屬性格式表示法指定。

ValueOf  
 (選用) 請只在您指定 `Sum` 作為 `AggregateOn` 的值時才使用此項目。`ValueOf` 會使用數值指定日誌欄位。在這種規則類型中，參與者會根據此欄位值的總和進行排名，而非在日誌項目中發生的次數。例如，如果您想要根據其在特定期間內的總 `BytesSent` 排名參與者，您可將 `ValueOf` 設為 `BytesSent`，並為 `AggregateOn` 指定 `Sum`。

篩選條件  
 指定最多四個篩選條件的陣列，縮小包含在報告中的日誌事件。如果您指定了多個篩選條件，Contributor Insights 會使用邏輯 AND 運算子進行評估。您可以使用此項目來在您的搜尋中篩選掉不相關的日誌事件，或是您可以用來選取單一參與者以分析其行為。  
陣列中的每個成員都必須包含 `Match` 欄位，以及一個指出要使用比對運算子類型的欄位。  
`Match` 欄位會指定要在篩選條件中評估的日誌欄位。日誌欄位是使用 JSON 屬性格式表示法指定。  
比對運算子欄位必須是以下其中一個：`In`、`NotIn`、`StartsWith`、`GreaterThan`、`LessThan`、`EqualTo`、`NotEqualTo` 或 `IsPresent`。如果運算子欄位是 `In`、`NotIn` 或 `StartsWith`，其後會跟隨一個要檢查的字串值陣列。Contributor Insights 會使用 OR 運算子評估字串值陣列。陣列最多可包含 10 個字串值。  
如果運算子欄位是 `GreaterThan`、`LessThan`、`EqualTo` 或 `NotEqualTo`，其後會跟隨要比較的單一數值。  
如果運算子欄位是 `IsPresent`，其後會跟隨 `true` 或 `false`。此運算子會根據日誌事件中是否存在指定的日誌欄位來比對日誌事件。`isPresent` 只能搭配 JSON 屬性分葉節點中的值運作。例如，尋找與 `c-count` 相符的篩選條件不會評估值為 `details.c-count.c1` 的日誌事件。  
請參閱以下四個篩選條件範例：  

```
{"Match": "$.httpMethod", "In": [ "PUT", ] }
{"Match": "$.StatusCode", "EqualTo": 200 }
{"Match": "$.BytesReceived", "GreaterThan": 10000}
{"Match": "$.eventSource", "StartsWith": [ "ec2", "ecs" ] }
```

AggregateOn  
 有效值為 `Count` 和 `Sum`。指定是要根據發生計數彙整報告，還是在 `ValueOf` 欄位中指定的欄位值總和彙整報告。

**JSON 屬性格式表示法**

`Keys`、`ValueOf` 和 `Match` 欄位允許使用點表示法的 JSON 屬性格式，其中 `$` 表示 JSON 物件的根。其後會跟隨一個句點，然後是包含子屬性名稱的英數字串。其支援多個屬性層級。

字串的第一個字元只能是 A-Z 或 a-z。字串的後續字元可以是 A-Z、a-z 或 0-9。

以下清單示範 JSON 屬性格式的有效範例：

```
$.userAgent
$.endpoints[0]
$.users[1].name
$.requestParameters.instanceId
```

**CLF 日誌規則中的其他欄位**

通用日誌格式 (CLF) 日誌事件不會跟 JSON 一樣包含欄位的名稱。如要提供欄位以用於 Contributor Insights 規則，CLF 日誌事件可以視為索引從 `1` 開始的陣列處理。您可以將第一個欄位指定為 **"1"**，將第二個欄位指定為 **"2"**，以此類推。

如要讓 CLF 日誌的規則更容易閱讀，您可以使用 `Fields`。這可以讓您為 CLF 欄位位置提供命名別名。例如，您可以指定位置 "4" 是一個 IP 位址。指定之後，`IpAddress` 便可以用來在規則的 `Keys`、`ValueOf` 和 `Filters` 中作為屬性。

以下是使用 `Fields` 欄位的 CLF 日誌規則範例。

```
{
    "Schema": {
        "Name": "CloudWatchLogRule",
        "Version": 1
    },
    "LogGroupNames": [
        "API-Gateway-Access-Logs*"
    ],
    "LogFormat": "CLF",
    "Fields": {
        "4": "IpAddress",
        "7": "StatusCode"
    },
    "Contribution": {
        "Keys": [
            "IpAddress"
        ],
        "Filters": [
            {
                "Match": "StatusCode",
                "EqualTo": 200
            }
        ]
    },
    "AggregateOn": "Count"
}
```