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

# 布林值、比較、數值、日期時間和其他函數
<a name="CWL_QuerySyntax-operations-functions"></a>

 CloudWatch Logs Insights 支援查詢中的許多其他操作和函數，如以下各節所述。

**Topics**
+ [算術運算子](#CWL_QuerySyntax-operations-arithmetic)
+ [布林值運算子](#CWL_QuerySyntax-operations-Boolean)
+ [比較運算子](#CWL_QuerySyntax-operations-comparison)
+ [數值運算子](#CWL_QuerySyntax-operations-numeric)
+ [結構類型](#CWL_QuerySyntax-structure-types)
+ [日期時間函數](#CWL_QuerySyntax-datetime)
+ [一般函數](#CWL_QuerySyntax-general-functions)
+ [JSON 函數](#CWL_QuerySyntax-json-functions)
+ [IP 地址字串函數](#CWL_QuerySyntax-IPaddress-functions)
+ [字串函數](#CWL_QuerySyntax-string-functions)

## 算術運算子
<a name="CWL_QuerySyntax-operations-arithmetic"></a>

 算術運算子可接受以數值資料類型作為引數，而且會傳回數值結果。算術運算子可用於 `filter` 和 `fields` 命令，也可以作為其他函數的引數使用。


| 作業 | Description | 
| --- | --- | 
|  `a + b` |  加法  | 
|  `a - b` |  減法  | 
|  `a * b` |  乘法  | 
|  `a / b` |  除法  | 
|  `a ^ b` |   指數 (`2 ^ 3` 傳回 `8`)   | 
|  `a % b` |   餘數或模數 (`10 % 3` 傳回 `1`)   | 

## 布林值運算子
<a name="CWL_QuerySyntax-operations-Boolean"></a>

 使用布林值運算子 `and`、`or` 和 `not`。

**注意**  
 布林值運算子僅限用於會傳回 **TRUE** 或 **FALSE** 的函數。

## 比較運算子
<a name="CWL_QuerySyntax-operations-comparison"></a>

 比較運算子可接受以所有資料類型作為引數，而且會傳回布林值結果。比較運算子可用於 `filter` 命令，也可以作為其他函數的引數使用。


| 運算子 | Description | 
| --- | --- | 
|   `=`   |   等於   | 
|   `!=`   |   不等於   | 
|   `<`   |   Less than   | 
|  `>` |   Greater than   | 
|  `<=` |   小於或等於   | 
|   `>=`   |   大於或等於   | 

## 數值運算子
<a name="CWL_QuerySyntax-operations-numeric"></a>

 數值運算接受數值資料類型作為引數，並傳回數值結果。數值運算可用於 `filter` 和 `fields` 命令，也可以作為其他函數的引數使用。


| 作業 | 結果類型 | Description | 
| --- | --- | --- | 
|   `abs(a: number)`   |   number   |   絕對值   | 
|   `ceil(a: number)`   |   number   |   無條件進位到上限 (大於 `a` 值的最小整數)   | 
|   `floor(a: number)`   |  number |   無條件捨去到下限 (小於 `a` 值的最大整數)   | 
|   `greatest(a: number, ...numbers: number[])`   |   number   |   傳回最大值   | 
|   `least(a: number, ...numbers: number[])`   |  number |   傳回最小值   | 
|   `log(a: number)`   |   number   |   自然對數   | 
|   `sqrt(a: number)`   |   number   |   平方根   | 

## 結構類型
<a name="CWL_QuerySyntax-structure-types"></a>

 地圖或清單是 CloudWatch Logs Insights 中的結構類型，可讓您存取和使用查詢的屬性。

**範例：取得地圖或清單**  
 使用 `jsonParse`將 json 字串的欄位剖析為映射或清單。

```
fields jsonParse(@message) as json_message
```

**範例：存取屬性**  
 使用點存取運算子 (map.attribute) 來存取映射中的項目。如果地圖中的屬性包含特殊字元，請使用反引號括住屬性名稱 (map.attributes.`special.char`)。

```
fields jsonParse(@message) as json_message
| stats count() by json_message.status_code
```

 使用括號存取運算子 (list【index】) 擷取清單中特定位置的項目。

```
fields jsonParse(@message) as json_message
| filter json_message.users[1].action = "PutData"
```

 當金鑰名稱中存在特殊字元時，以反引號 (``) 包裝特殊字元。

```
fields jsonParse(@message) as json_message
| filter json_message.`user.id` = "123"
```

**範例：空的結果**  
 地圖和清單會被視為字串、數字和日期時間函數的 null。

```
fields jsonParse(@message) as json_message
| display toupper(json_message)
```

 比較映射和清單到任何其他欄位會導致 `false`。

**注意**  
 `stats` 不支援在 `dedup`、`sort`、 和 `pattern`中使用地圖和清單。

## 日期時間函數
<a name="CWL_QuerySyntax-datetime"></a>

 **日期時間函數** 

 日期時間函數可用於 `fields` 和 `filter` 命令，也可以作為其他函數的引數使用。如果查詢中使用了彙總函數，您可以使用這些函數來建立時段。使用由數字和下列其中一項組成的時段：
+ `ms` 毫秒 
+ `s` 持續 秒 
+ `m` 持續 分鐘 
+ `h` 小時 

 例如，`10m` 是 10 分鐘，`1h` 是 1 小時。

**注意**  
為您的日期時間函數使用最適當的時間單位。CloudWatch Logs 會根據您選擇的時間單位來限制您的請求。例如，它以 60 為上限，作為使用 的任何請求的最大值`s`。因此，如果您指定 `bin(300s)`，CloudWatch Logs 實際上會將其實作為 60 秒，因為 60 是一分鐘的秒數，因此 CloudWatch Logs 不會搭配 使用高於 60 的數字`s`。若要建立 5 分鐘的儲存貯體，請`bin(5m)`改用 。  
的上限為 `ms` 1000、 `s`和 的上限為 `m` 60，而 的上限為 `h` 24。

下表列出您可以在查詢命令中使用的不同日期時間函數。該表列出了每個函式的結果類型，並包含對每個函式的說明。

**提示**  
 建立查詢命令時，您可以使用時間間隔選擇器，來選取您要查詢的時間段。例如：您可以設定 5 分鐘到 30 分鐘的間隔；1 小時、3 小時和 12 小時的間隔；或是自訂的時間範圍。您也可以在特定日期之間設定時間段。


| 函式 | 結果類型 | Description | 
| --- | --- | --- | 
|  `bin(period: Period)` |  時間戳記 |  將 `@timestamp` 的值四捨五入到指定時間段，然後截斷。例如，`bin(5m)` 將 `@timestamp` 的值四捨五入至最接近的 5 分鐘。 您可以使用此操作在查詢中將多筆日誌條目分組在一起。以下範例傳回每小時的例外情況計數。 <pre>filter @message like /Exception/ <br />    | stats count(*) as exceptionCount by bin(1h)<br />    | sort exceptionCount desc</pre> `bin` 函數支援以下時間單位和縮寫。對於包含多個字元的所有單位和縮寫，支援加上 s 來表示複數。所以 `hr` 和 `hrs` 皆可用來指定時數。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/AmazonCloudWatch/latest/logs/CWL_QuerySyntax-operations-functions.html)  | 
|  `datefloor(timestamp: Timestamp, period: Period)` |  時間戳記 |  將時間戳記截斷為指定的期間。例如，`datefloor(@timestamp, 1h)` 將 `@timestamp` 的所有值截斷為半點小時。  | 
|  `dateceil(timestamp: Timestamp, period: Period)` |  時間戳記 |  將時間戳記無條件進位到指定期間，然後截斷。例如，`dateceil(@timestamp, 1h)` 將 `@timestamp` 的所有值截斷為整點小時。  | 
|  `fromMillis(fieldName: number)` |  時間戳記 |  解譯輸入欄位為自 Unix epoch 以來的毫秒數，並將其轉換為時間戳記。  | 
|  `toMillis(fieldName: Timestamp)` |  number |  將指定欄位中找到的時間戳記轉換為數字，代表自 Unix epoch 以來的毫秒數。例如：`toMillis(@timestamp)` 會將時間戳記 `2022-01-14T13:18:031.000-08:00` 轉換為 `1642195111000`。  | 
|  `now()`  |  number  |  以 epoch 秒為單位，傳回查詢處理開始的時間。此函數不採用引數。 您可以使用此值，根據目前時間篩選查詢結果。 例如，下列查詢會傳回過去兩個小時內所有 4xx 個錯誤： <pre>parse @message "Status Code: *;" as statusCode\n <br />| filter statusCode >= 400 and statusCode <= 499  \n <br />| filter toMillis(@timestamp) >= (now() * 1000 - 7200000)</pre> 下列範例會傳回過去五小時內包含單字 `error`或 的所有日誌項目 `failure` <pre>fields @timestamp, @message <br />| filter @message like /(?i)(error|failure)/ <br />| filter toMillis(@timestamp) >= (now() * 1000 - 18000000)</pre>  | 

**注意**  
 目前 CloudWatch Logs Insights 不支援使用人類可讀時間戳記篩選日誌。

## 一般函數
<a name="CWL_QuerySyntax-general-functions"></a>

 **一般函數** 

 一般函數可用於 `fields` 和 `filter` 命令，也可以作為其他函數的引數使用。


| 函式 | 結果類型 | Description | 
| --- | --- | --- | 
|   `ispresent(fieldName: LogField)`   |   Boolean   |   如果欄位存在，傳回 `true`   | 
|   `coalesce(fieldName: LogField, ...fieldNames: LogField[])`   |   LogField   |   傳回清單中的第一個非空值   | 

## JSON 函數
<a name="CWL_QuerySyntax-json-functions"></a>

 **JSON 函數** 

 在 `fields`和 `filter`命令中使用 JSON 函數，並做為其他函數的引數。


| 函式 | 結果類型 | Description | 
| --- | --- | --- | 
|   `jsonParse(fieldName: string)`   |   映射 \$1 清單 \$1 空白   |   當輸入是 JSON 物件或 JSON 陣列的字串表示法時，傳回映射或清單。如果輸入不是其中一個表示法，則傳回空值。  | 
|   `jsonStringify(fieldName: Map \| List)`   |   String   |   從映射或清單資料傳回 JSON 字串。  | 

## IP 地址字串函數
<a name="CWL_QuerySyntax-IPaddress-functions"></a>

 **IP 地址字串函數** 

 IP 地址字串函數可用於 `filter` 和 `fields` 命令，也可以作為其他函數的引數使用。


| 函式 | 結果類型 | Description | 
| --- | --- | --- | 
|  `isValidIp(fieldName: string)` |  boolean |  如果欄位是有效的 IPv4 或 IPv6 地址，則會傳回 `true`。  | 
|  `isValidIpV4(fieldName: string)` |  boolean |  如果欄位是有效的 IPv4 地址，則傳回 `true`。  | 
|  `isValidIpV6(fieldName: string)` |  boolean |  如果欄位是有效的 IPv6 地址，則傳回 `true`。  | 
|  `isIpInSubnet(fieldName: string, subnet: string)` |  boolean |  如果欄位是指定 v4 或 v6 子網路內的有效 IPv4 或 IPv6 地址，則傳回 `true`。指定子網路時，請使用 CIDR 標記法，例如 `192.0.2.0/24` 或 `2001:db8::/32`，其中 `192.0.2.0` 或 `2001:db8::` 是 CIDR 區塊的起始位置。  | 
|  `isIpv4InSubnet(fieldName: string, subnet: string)` |  boolean |  如果欄位是指定 v4 子網路內的有效 IPv4 地址，則傳回 `true`。指定子網路時，請使用 CIDR 標記法，例如 `192.0.2.0/24`，其中 `192.0.2.0` 是 CIDR 區塊的起始位置。  | 
|  `isIpv6InSubnet(fieldName: string, subnet: string)` |  boolean |  如果欄位是指定 v6 子網路內的有效 IPv6 地址，則傳回 `true`。指定子網路時，請使用 CIDR 標記法，例如 `2001:db8::/32`，其中 `2001:db8::` 是 CIDR 區塊的起始位置。  | 

## 字串函數
<a name="CWL_QuerySyntax-string-functions"></a>

 **字串函數** 

 字串函數可用於 `fields` 和 `filter` 命令，也可以作為其他函數的引數使用。


| 函式 | 結果類型 | Description | 
| --- | --- | --- | 
|  `isempty(fieldName: string)` |  Number |  如果欄位遺失或是空白字串，傳回 `1`。  | 
|  `isblank(fieldName: string)` |  Number |  如果欄位遺失、是空白字串或只包含空格，傳回 `1`。  | 
|  `concat(str: string, ...strings: string[])` |  string |  串連字串。  | 
|  `ltrim(str: string)` `ltrim(str: string, trimChars: string)` |  string |  如果函數沒有第二個引數，則會移除字串左側的空格。如果函數有第二個字串引數，則不會移除空格。而是從 `str` 左側移除 `trimChars` 中的字元。例如，`ltrim("xyZxyfooxyZ","xyZ")` 傳回 `"fooxyZ"`。  | 
|  `rtrim(str: string)` `rtrim(str: string, trimChars: string)` |  string |  如果函數沒有第二個引數，則會移除字串右側的空格。如果函數有第二個字串引數，則不會移除空格。而是從 `str` 右側移除 `trimChars` 的字元。例如，`rtrim("xyZfooxyxyZ","xyZ")` 傳回 `"xyZfoo"`。  | 
|  `trim(str: string)` `trim(str: string, trimChars: string)` |  string |  如果函數沒有第二個引數，則會移除字串兩側的空格。如果函數有第二個字串引數，則不會移除空格。而是從 `str` 兩側移除 `trimChars` 的字元。例如，`trim("xyZxyfooxyxyZ","xyZ")` 傳回 `"foo"`。  | 
|  `strlen(str: string)` |  number |  以 Unicode 字碼指標傳回字串的長度。  | 
|  `toupper(str: string)` |  string |  將字串轉換成大寫。  | 
|  `tolower(str: string)` |  string |  將字串轉換成小寫。  | 
|  `substr(str: string, startIndex: number)` `substr(str: string, startIndex: number, length: number)` |  string |  傳回從數字引數指定的索引到字串結尾的子字串。如果函數有第二個數字引數，則是包含要擷取的子字串長度。例如，`substr("xyZfooxyZ",3, 3)` 傳回 `"foo"`。  | 
|  `replace(fieldName: string, searchValue: string, replaceValue: string)` |  string |  以 `replaceValue` 取代 `fieldName: string` 中出現的所有 `searchValue`。 例如：函式 `replace(logGroup,"smoke_test","Smoke")` 搜尋欄位 `logGroup` 中包含字串值 `smoke_test` 的日誌事件，並將值替換為字串 `Smoke`。  | 
|  `strcontains(str: string, searchValue: string)` |  number |  如果 `str` 包含 `searchValue`，則傳回 1，否則傳回 0。  |