# 网络监测仪查询接口
<a name="CloudWatch-IM-view-cw-tools-cwim-query"></a>

要详细了解 Amazon 应用程序的互联网流量，可以选择使用网络监测仪*查询接口*。要使用该查询接口，您需要使用所选数据筛选条件创建查询，然后运行查询以返回网络监测仪数据的子集。浏览查询返回的数据可以让您深入了解应用程序在互联网上的表现。

您可以查询和探索网络监测仪使用监测仪捕获的所有指标，包括可用性和性能分数、传输的字节数、往返时间和首字节时间（TTFB）。

网络监测仪使用查询接口提供您可以在网络监测仪控制台控制面板中探索的数据。通过使用控制面板中的搜索选项（在**分析**页面或**优化**页面上），您可以查询和筛选应用程序的互联网数据。

如果您想要比控制面板更灵活的数据探索和筛选方式，则可以通过将网络监测仪 API 操作与 Amazon Command Line Interface 或 Amazon SDK 配合使用，自行使用查询接口。本部分介绍可与查询接口一起使用的查询类型，以及为创建数据子集可指定的筛选条件器，以便深入了解应用程序的互联网流量。

**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.amazonaws.cn/internet-monitor/latest/api/API_GetQueryResults.html) API 操作来指定查询 ID，以返回查询的数据结果。每种查询类型都会返回不同的数据字段集。要了解更多信息，请参阅[获取查询结果](#IMGetQueryData)。

查询接口提供以下查询类型。每种查询类型都会从日志文件中返回一组不同的流量信息，如下所示。
+ **测量数据：**以 5 分钟为间隔提供可用性分数、性能分数、总流量和往返时间。
+ **排名靠前的位置：**按流量提供您正在监测的“排名靠前的位置 \$1 ASN”组合的可用性分数、性能分数、总流量和首字节时间（TTFB）信息。
+ **排名靠前的位置详情：**以 1 小时为间隔提供 Amazon CloudFront 的 TTFB、您当前的配置以及性能最佳的 Amazon EC2 配置。
+ **总体流量建议：**提供每个受监测 Amazon 位置的所有流量的 TTFB（基于 30 天加权平均值）。
+ **总体流量建议详细信息：**提供了每个主要位置以及建议的 Amazon 位置的 TTFB（基于 30 天加权平均值）。
+ **路由建议：**为 DNS 解析程序提供从 IP 前缀到 Amazon 位置的预测平均往返时间（RTT）。RTT 以一小时为间隔计算，计算周期为一小时。

您可以使用特定条件对数据进行更多筛选。对于大多数查询类型，除了路由建议，您可以通过指定以下一个或多个条件进行筛选：
+ **Amazon 位置：**对于 Amazon 位置，您可以指定 CloudFront 或 Amazon Web Services 区域，例如 `us-east-2`。
+ **ASN：**指定 DNS 解析程序（通常为 ISP）的自治系统编号（ASN），例如 4225。
+ **客户端位置：**对于位置，请指定城市、都会区、分区或国家/地区。
+ **建议的 Amazon 位置：**指定 Amazon Web Services 区域（例如 `us-east-2`）或 Amazon 本地区域。您可以将此筛选器与总体流量建议详细信息查询类型一起使用。
+ **地理位置：**为某些查询指定 `geo`。对于使用 `Top locations` 查询类型的查询，此为必需项，但不允许用于其他查询类型。要了解何时为筛选参数指定 `geo`，请参阅 [Query examples](#IMQueryInterfaceExamples) 部分。

对于路由建议查询类型，您可以通过指定以下一个或多个条件，对数据进行更多筛选：
+ **当前 Amazon 位置：**指定一个 Amazon Web Services 区域，例如 `us-east-2`。
+ **建议的 Amazon 位置：**指定 Amazon Web Services 区域（例如 `us-east-2`）或 Amazon 本地区域。
+ **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.amazonaws.cn/internet-monitor/latest/api/API_FilterParameter.html) API 操作。

要查看有关查询接口操作的详细信息，请参阅《Internet Monitor API Reference Guide》中的以下 API 操作：
+ 要创建和运行查询，请参阅 [StartQuery](https://docs.amazonaws.cn/internet-monitor/latest/api/API_StartQuery.html) API 操作。
+ 要停止查询，请参阅 [StopQuery](https://docs.amazonaws.cn/internet-monitor/latest/api/API_StopQuery.html) API 操作。
+ 要为您创建的查询返回数据，请参阅 [GetQueryResults](https://docs.amazonaws.cn/internet-monitor/latest/api/API_GetQueryResults.html) API 操作。
+ 要检索查询的状态，请参阅 [GetQueryStatus](https://docs.amazonaws.cn/internet-monitor/latest/api/API_GetQueryStatus.html) API 操作。

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

要创建可用于从监测仪日志文件中检索经过筛选的数据集的查询，可以使用 [StartQuery](https://docs.amazonaws.cn/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` 设置为“洛杉矶”。现在，该查询返回的是洛杉矶都会区排名靠前的城市网络，而不是总体上排名靠前的都会区\$1网络。

以下是您可以使用的示例查询：

```
{
   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**

假设您要检索特定新 Amazon Web Services 区域的 TTFB 数据。

您可以为此场景使用以下示例查询：

```
{
   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.amazonaws.cn/internet-monitor/latest/api/API_GetQueryResults.html) 来返回一组查询结果。运行 `GetQueryResults` 时 ，您可以为已定义的查询指定查询 ID 以及监测仪名称。`GetQueryResults` 会将指定查询的数据检索到结果集中。

运行查询时，请确保查询已完成运行，然后再使用 `GetQueryResults` 查看结果。您可以使用 [GetQueryStatus](https://docs.amazonaws.cn/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 操作时返回错误，请确认您拥有使用网络监测仪所需的权限。具体而言，请确保您拥有以下权限：

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

这些权限包含在推荐 Amazon Identity and Access Management 策略中，以便在控制台中使用网络监测仪控制面板。有关更多信息，请参阅 [网络监测仪的 Amazon 托管策略](CloudWatch-IM-permissions.md)。