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

# 使用 Internet Monitor 查詢介面
<a name="CloudWatch-IM-view-cw-tools-cwim-query"></a>

進一步了解 AWS 應用程式網際網路流量的選項是使用網路監視器*查詢界面*。若要使用查詢介面，請使用您選擇的資料篩選條件來建立查詢，然後執行查詢，以傳回網路監視器資料的子集。探索查詢傳回的資料，這可讓您深入了解應用程式在網際網路上的執行情況。

您可查詢並探索網路監視器使用監視器擷取的所有指標，包括可用性和效能分數、傳輸的位元組、往返時間和第一個位元組的時間 (TTFB)。

網路監視器使用查詢介面來提供您可在網路監視器主控台儀表板中探索的資料。使用儀表板中的搜尋選項 (位於**分析**頁面或**最佳化**頁面)，您可以查詢和篩選應用程式的網際網路資料。

如果您想要比儀表板更靈活地探索和篩選資料，您可以自行使用查詢界面，方法是搭配 AWS Command Line Interface 或 AWS SDK 使用網路監視器 API 操作。本節會介紹可與查詢介面搭配使用的查詢類型，以及您可指定用於建立資料子集的篩選條件，以取得應用程式網際網路流量的相關洞察。

**Topics**
+ [如何使用查詢介面](#CloudWatch-IM-view-cw-tools-cwim-query-use-query)
+ [查詢範例](#CloudWatch-IM-view-cw-tools-cwim-query-example-queries)
+ [取得查詢結果](#CloudWatch-IM-view-cw-tools-cwim-query-get-data)
+ [疑難排解](#CloudWatch-IM-view-cw-tools-cwim-query-troubleshooting)

## 如何使用查詢介面
<a name="CloudWatch-IM-view-cw-tools-cwim-query-use-query"></a>

您可選擇*查詢類型*，然後指定篩選值，以使用查詢介面建立查詢，進而傳回所需的特定日誌檔案資料子集。然後，您可使用資料子集，進一步篩選和排序、建立報告等等。

查詢運作程序如下：

1. 當您執行查詢時，網路監視器會傳回對查詢而言不重複的 `query ID`。本節會描述可用的查詢類型，以及在查詢中篩選資料的選項。若要了解運作方式，您還可檢閱[查詢範例](#IMQueryInterfaceExamples)章節。

1. 您可使用 [GetQueryResults](https://docs.aws.amazon.com/internet-monitor/latest/api/API_GetQueryResults.html) API 操作，指定監視器名稱的查詢 ID，以傳回查詢的資料結果。每個查詢類型都會傳回不同的資料集欄位。若要進一步了解，請參閱[取得查詢結果](#IMGetQueryData)。

查詢介面提供以下種查詢類型。每個查詢類型都會從日誌檔案傳回有關流量的不同資訊集，如下所示。
+ **度量結果：**每隔 5 分鐘提供一次可用性分數、效能分數、總流量和往返時間。
+ **最佳位置：**針對您監控的最佳位置與 ASN 組合 (依流量計)，提供可用性評分、效能評分、總流量及第一個位元組時間 (TTFB) 資訊。
+ **最佳位置詳細資訊：**每隔 1 小時提供一次 Amazon CloudFront 的 TTFB、您目前的組態，以及效能最佳的 Amazon EC2 組態。
+ **整體流量建議：**針對每個受監控 AWS 位置中的所有流量，使用 30 天的加權平均值提供 TTFB。
+ **整體流量建議詳細資訊：**針對提議 AWS 的位置，使用每個最高位置的 30 天加權平均值提供 TTFB。
+ **路由建議：**提供從 IP 字首到 DNS 解析程式 AWS 位置的預測平均往返時間 (RTT)。RTT 的計算間隔為一小時，期間為一小時。

您可以透過特定條件進一步篩選資料。對於大多數查詢類型，除了路由建議之外，可以透過指定下列一或多個條件進行篩選：
+ location**AWS ：**對於 AWS 位置，您可以指定 CloudFront 或 AWS 區域，例如 `us-east-2`。
+ **ASN：**指定 DNS 解析程式 (通常是 ISP) 的自治系統編號 (ASN)，例如 4225。
+ **用戶端位置：**針對位置，請指定城市、都會區、行政區或國家/地區。
+ **建議 AWS 的位置：**指定 AWS 區域，例如 `us-east-2`或 AWS Local Zone。您可以將此篩選條件與整體流量建議詳細資訊查詢類型搭配使用。
+ **地理：**針對某些查詢指定 `geo`。這對於使用 `Top locations` 查詢類型的查詢為必要，但對於其他查詢類型則不允許。若要了解何時指定 `geo` 來篩選參數，請參閱[查詢範例](#IMQueryInterfaceExamples)章節。

對於路由建議查詢類型，可以指定下列一個或多個條件來進一步篩選資料：
+ **目前 AWS 位置：**指定 AWS 區域，例如 `us-east-2`。
+ **建議 AWS 的位置：**指定 AWS 區域，例如 `us-east-2`或 AWS Local Zone。
+ **IPv4 字首：**以標準格式指定 IPv4 字首，類似於 `192.0.2.0/24`。
+ **監視器 ARN：**指定特定監視器的 ARN。
+ **DNS 解析程式 IP：**指定 DNS 解析程式的 IP 位址。
+ **DNS 解析程式 ISP：**指定 DNS 解析程式的名稱 (通常是 ISP)，例如 `Cloudflare`。
+ **DNS 解析程式 ASN：**指定 DNS 解析程式的自治系統編號 (ASN)，例如 4225。

您可用來篩選資料的運算子為 `EQUALS` 和 `NOT_EQUALS`。如需篩選參數的詳細資訊，請參閱 [FilterParameter](https://docs.aws.amazon.com/internet-monitor/latest/api/API_FilterParameter.html) API 操作。

若要檢視查詢介面操作的詳細資訊，請參閱《Internet Monitor API 參考指南》中的下列 API 操作：
+ 若要建立和執行查詢，請參閱 [StartQuery](https://docs.aws.amazon.com/internet-monitor/latest/api/API_StartQuery.html) API 操作。
+ 若要停止查詢，請參閱 [StopQuery](https://docs.aws.amazon.com/internet-monitor/latest/api/API_StopQuery.html) API 操作。
+ 若要傳回已建立查詢的資料，請參閱 [GetQueryResults](https://docs.aws.amazon.com/internet-monitor/latest/api/API_GetQueryResults.html) API 操作。
+ 若要擷取查詢的狀態，請參閱 [GetQueryStatus](https://docs.aws.amazon.com/internet-monitor/latest/api/API_GetQueryStatus.html) API 操作。

## 查詢範例
<a name="CloudWatch-IM-view-cw-tools-cwim-query-example-queries"></a>

若要建立您可用於從監視器日誌檔案擷取篩選資料集的查詢，請使用 [StartQuery](https://docs.aws.amazon.com/internet-monitor/latest/api/API_StartQuery.html) API 操作。您可指定查詢的查詢類型和篩選參數。然後，當您使用網路監視器查詢介面 API 操作，藉由查詢來取得查詢結果時，它會擷取您想要使用的資料子集。

為了說明查詢類型和篩選參數的運作方式，我們來看一些範例。

**範例 1**

假設您想要擷取特定國家/地區 (一個城市除外) 的所有監視器日誌資料。下列範例顯示了您可針對此案例，使用 `StartQuery` 操作建立查詢的篩選參數。

```
{
   MonitorName: "TestMonitor"
   StartTime: "2023-07-12T20:00:00Z"
   EndTime: "2023-07-12T21:00:00Z"
   QueryType: "MEASUREMENTS"
   FilterParameters: [
      {
       Field: "country",
       Operator: "EQUALS",
       Values: ["Germany"]
      },
      {
       Field: "city",
       Operator: "NOT_EQUALS",
       Values: ["Berlin"]
      },
    ]
}
```

**範例 2**

另舉一例，假設您想要按都會區查看熱門位置。您可針對此案例使用下列範例查詢。

```
{
   MonitorName: "TestMonitor"
   StartTime: "2023-07-12T20:00:00Z"
   EndTime: "2023-07-12T21:00:00Z"
   QueryType: "TOP_LOCATIONS"
   FilterParameters: [
      {
       Field: "geo",
       Operator: "EQUALS",
       Values: ["metro"]
      },
    ]
}
```

**範例 3**

現在，假設您想要看到洛杉磯都會區的熱門城市網路組合。若要執行此操作，請指定 `geo=city`，然後將 `metro` 設定為洛杉磯。現在，該查詢會傳回洛杉磯都會區的熱門城市網路，而不是整個熱門的都會區 \+ 網路。

以下是您可使用的範例查詢：

```
{
   MonitorName: "TestMonitor"
   StartTime: "2023-07-12T20:00:00Z"
   EndTime: "2023-07-12T21:00:00Z"
   QueryType: "TOP_LOCATIONS"
   FilterParameters: [
      {
       Field: "geo",
       Operator: "EQUALS",
       Values: ["city"]
      },
      {
       Field: "metro",
       Operator: "EQUALS",
       Values: ["Los Angeles"]
      }
    ]
}
```

**範例 4**

接下來，假設您想要擷取特定行政區 (例如，美國的一個州) 的 TTFB 資料。

以下是此案例的範例查詢：

```
{
   MonitorName: "TestMonitor"
   StartTime: "2023-07-12T20:00:00Z"
   EndTime: "2023-07-12T21:00:00Z"
   QueryType: "TOP_LOCATION_DETAILS"
   FilterParameters: [
      {
       Field: "subdivision",
       Operator: "EQUALS",
       Values: ["California"]
      },
    ]
}
```

**範例 5**

現在，假設針對應用程式具有用戶端流量的每個位置，您想要擷取其 TTFB。

以下是此案例的範例查詢：

```
{
   MonitorName: "TestMonitor"
   StartTime: "2023-07-12T20:00:00Z"
   EndTime: "2023-07-12T21:00:00Z"
   QueryType: "OVERALL_TRAFFIC_SUGGESTIONS"
   FilterParameters: []
}

Results:
[us-east-1, 40, us-west-2, 30],
[us-east-1, 40, us-west-1, 35],
[us-east-1, 40, us-east-1, 44],
[us-east-1, 40, CloudFront, 22],
...
[us-east-2, 44, us-west-2, 30],
[us-east-2, 44, us-west-1, 35],
...
```

**範例 6**

假設您想要擷取特定新 的 TTFB 資料 AWS 區域。

以下是此案例的範例查詢：

```
{
   MonitorName: "TestMonitor"
   StartTime: "2023-07-12T20:00:00Z"
   EndTime: "2023-07-12T21:00:00Z"
   QueryType: "OVERALL_TRAFFIC_SUGGESTIONS_DETAILS"
   FilterParameters: [
      {
       Field: "proposed_aws_location",
       Operator: "EQUALS",
       Values: ["us-west-2"]
      },
   ]
}

Results:
[San Jose, San Jose-Santa Clara, California, United States, 7922, us-east-1, 40, 350, 350, us-west-2, 45]
[San Jose, San Jose-Santa Clara, California, United States, 7922, us-west-1, 35, 450, 450, us-west-2, 45]
```

**範例 7**

最後一個範例是擷取特定 DNS 解析程式的資料。

以下是此案例的範例查詢：

```
{
   MonitorName: "TestMonitor"
   StartTime: "2023-07-12T20:00:00Z"
   EndTime: "2023-07-12T21:00:00Z"
   QueryType: "ROUTING_SUGGESTIONS"
   FilterParameters: [
      {
       Field: "proposed_aws_location",
       Operator: "EQUALS",
       Values: ["us-east-1"]
      },
   ]
}

Results:
[162.158.180.245, 13335, Cloudflare, [5.4.0.0/14], us-east-2, 200.0, us-east-1, 160.0]
[162.158.180.243, 13313, Cloudflare, [5.4.0.0/10], us-east-2, 150.0, us-east-1, 125.0]
```

## 取得查詢結果
<a name="CloudWatch-IM-view-cw-tools-cwim-query-get-data"></a>

在定義查詢之後，您可執行另一項網路監視器 API 操作 [GetQueryResults](https://docs.aws.amazon.com/internet-monitor/latest/api/API_GetQueryResults.html)，傳回查詢的結果集。執行 `GetQueryResults` 時，您可指定已定義查詢的查詢 ID，以及監視器的名稱。`GetQueryResults` 會將指定查詢的資料擷取至結果集。

執行查詢時，請確定查詢已完成執行，然後再使用 `GetQueryResults` 來查看結果。您可使用 [GetQueryStatus](https://docs.aws.amazon.com/internet-monitor/latest/api/API_GetQueryStatus.html) API 操作來判斷查詢是否已完成。當查詢的 `Status` 為 `SUCCEEDED` 時，您可繼續檢閱結果。

查詢完成後，您可使用下列資訊來協助您檢閱結果。您用於建立查詢的每個查詢類型都包括日誌檔案中不重複的資料集欄位，如下列清單所述：

**測量值**  
`measurements` 查詢類型會傳回下列資料：  
`timestamp, availability, performance, bytes_in, bytes_out, rtt_p50, rtt_p90, rtt_p95`

**熱門位置**  
`top locations` 查詢類型會依位置對資料分組，並提供一段時間的平均資料。傳回的資料包含下列內容：  
`aws_location, city, metro, subdivision, country, asn, availability, performance, bytes_in, bytes_out, current_fbl, best_ec2, best_ec2_region, best_cf_fbl`  
請注意，只有在您針對 `geo` 欄位選擇該位置類型時，才會傳回 `city`、`metro` 和 `subdivision`。視乎您為 `geo` 指定的位置類型會傳回下列位置欄位：  

```
city = city, metro, subdivision, country
metro = metro, subdivision, country
subdivision = subdivision, country
country = country
```

**熱門位置詳細資訊**  
`top locations details` 查詢類型會傳回依小時分組的資料。查詢會傳回下列資料：  
`timestamp, current_service, current_fbl, best_ec2_fbl, best_ec2_region, best_cf_fbl`

**整體流量建議**  
`overall traffic suggestions` 查詢類型會傳回依小時分組的資料。查詢會傳回下列資料：  
`current_aws_location, proposed_aws_location, average_fbl, traffic, optimized_traffic_excluding_cf, optimized_traffic_including_cf`

**整體流量建議詳細資訊**  
`overall traffic suggestions details` 查詢類型會傳回依小時分組的資料。查詢會傳回下列資料：  
`aws_location, city, metro, subdivision, country, asn, traffic, current_aws_location, fbl_data`

**路由建議**  
`routing suggestions` 查詢類型會傳回依小時分組的資料。查詢會傳回下列資料：  
`dns_resolver_ip, dns_resolver_asn, dns_resolver_isp, ipv4_prefixes, current_aws_location, current_latency, proposed_aws_location, proposed_latency`

當您執行 `GetQueryResults` API 操作時，網路監視器會在回應中傳回下列項目：
+ 包含查詢傳回結果的*資料字串陣列*。資訊會在與 `Fields` 欄位相符的陣列中傳回，也會透過 API 呼叫傳回。使用 `Fields` 欄位，您可剖析 `Data` 儲存器中的資訊，然後根據您的用途進一步篩選或排序。
+ *欄位陣列*會列出查詢傳回資料的欄位 (在 `Data` 欄位回應中)。陣列中的每個項目都是一個名稱-資料類型對，例如 `availability_score`-`float`。

## 疑難排解
<a name="CloudWatch-IM-view-cw-tools-cwim-query-troubleshooting"></a>

如果您在使用查詢介面 API 操作時傳回錯誤，則請確認您具有使用 Internet Monitor 的必要許可。特別確認您具有下列許可：

```
internetmonitor:StartQuery
internetmonitor:GetQueryStatus
internetmonitor:GetQueryResults
internetmonitor:StopQuery
```

這些許可包含在建議的 AWS Identity and Access Management 政策中，以在 主控台中使用網路監視器儀表板。如需詳細資訊，請參閱[AWS 網路監視器的 受管政策](CloudWatch-IM-permissions.md)。