使用 API Explorer

本指南介绍如何使用 API Explorer 来试用 Cloud Monitoring API 方法。API Explorer 是附加到方法的 REST API 参考页面的微件。它会显示为一个面板，标题为试用此 API。以下屏幕截图显示了仅包含一个参数 name 的方法所显示的面板：

API Explorer 是在 Cloud Monitoring API 中试用方法的绝佳方法，无需编写任何代码。该微件会显示一个表单，其中显示每种方法的参数。填写表单，点击执行按钮，然后查看结果。

您也可以通过点击 close 按钮隐藏微件，或点击 fullscreen 按钮将微件展开至全屏。

试试看！按钮

在文档中，您可能会看到试试看！按钮，如下所示：

点击该按钮后，系统会在该方法的参考页面上打开 API Explorer。通常，系统会填充适合示例的一些参数；但是，您可能需要修改某些参数以与您自己的项目匹配，例如 [PROJECT_ID] 的值。

如需了解如何避免错误和修复错误，请参阅问题排查。

访问 API Explorer

API Explorer 会附加到每种 REST API 方法的参考页面。如需查找微件，请参阅方法的参考页面，例如，请参阅 metricDescriptors.list。

执行请求

大多数方法都有一些必需参数和一些可选参数。系统会用红色条标记必填项，直到填充完毕。为所有必需参数提供值后，便可以执行请求了。

如需执行 metricDescriptors.list 方法，请执行以下操作：

1. 点击试试看！
2. 在 name 参数中，使用 projects/[PROJECT_ID] 格式输入项目的 ID。请务必将 [PROJECT_ID] 替换为您的项目 ID。
3. 点击执行。为了执行该命令，API Explorer 需要访问您的账号。出现提示时，选择一个账号并点击允许。访问权限仅在有限的时间段内有效，并且仅限于您要执行的 API 方法。

方法调用的结果显示在具有绿色或红色标题的框中。请求成功后，框会显示绿色标题，其中包含 HTTP 状态代码 200。调用的结果显示在框中：

标题为红色时，包含 HTTP 失败代码，且框中包含错误消息。如需了解如何解决错误，请参阅问题排查。

提供其他参数

您看到的参数列表取决于 API Explorer 微件的附加方法。例如，metricDescriptors.list 方法含有除 name 参数以外的其他参数，但是 name 是唯一的必需参数。

仅提供项目名称时，您将获得项目中所有可用的指标描述符，并且有很多指标描述符。如需将检索限制为较小的集合，请使用 filter 参数。

例如，如需仅列出名称以 utilization 结尾的指标类型，请执行以下操作：

1. 点击试试看！

2. 在 name 参数中，使用 projects/[PROJECT_ID] 格式输入项目的 ID。请务必将 [PROJECT_ID] 替换为您的项目 ID。

3. 确保 filter 参数的值为 metric.type=ends_with("utilization")

4. 点击执行并完成授权对话框。

标准参数

默认情况下，API Explorer 显示的参数集与关联方法的参数相对应。但是，API Explorer 微件还具有一组不于该方法本身的额外参数。如需显示额外参数，请点击显示标准参数：

如需隐藏额外参数（不显示它们），请点击隐藏标准参数。

最有用的标准参数是 fields 参数。此参数可让您在返回的输出中选择要查看的字段。

例如，列出以 utilization 结尾的指标的描述符仍然返回许多结果。如果您只想知道指标类型的名称及其描述，则可以使用 fields 参数指定此限制。

如需查看设置 fields 参数的结果，请执行以下操作：

1. 点击试试看！

2. 在 name 参数中，使用 projects/[PROJECT_ID] 格式输入项目的 ID。请务必将 [PROJECT_ID] 替换为您的项目 ID。

3. 确保 filter 参数的值为 metric.type=ends_with("utilization")

4. 点击显示标准参数，然后验证 fields 参数的值是否为 metricDescriptors.type,metricDescriptors.description

5. 点击执行并完成授权对话框。

执行此请求仅返回每个指标的 type（简称）及其 description。

问题排查

本部分介绍了使用 API Explorer 时的常见问题。

过滤条件语法无效

您复制了多行表达式并将其粘贴到 API Explorer 中显示的字段中，但 API Explorer 显示了错误消息。

正确做法：确保字符串位于单行中。

"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | within 5m"

不应：复制和粘贴行尾符号或换行符。

例如，如果您向 timeSeries.query 方法添加以下代码，API Explorer 会显示错误消息 Select an underlined section to see more details：

"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count
          | within 5m"

项目标识符无效

如果项目标识符无效，则 API 请求将失败，并显示 HTTP 错误 400。

如需解决此问题，请验证文本 [PROJECT_ID] 是否已替换为您的项目 ID。

表单值无效

如果您的 API 请求失败或返回非预期值，请检查所有表单参数。

API Explorer 参数需要特定格式。格式错误可能会导致错误，或者在 API 方法中它们可能会被接受但可能会被视为拼写错误：

• 请勿在任何类型的参数值前后加上引号。

• 除非需要保护子字符串，否则请勿使用反斜杠。

  例如，以下示例是一个 API 方法，在该方法中，您以 JSON 格式输入内容，而不是填写个别表单参数。由于 filter 的值是一个字符串，因此子字符串 k8s_cluster 受反斜杠保护：

    {
      "resourceNames": [...],
      "filter": "resource.type = \"k8s_cluster\""
    }

• 使用英文引号括住出现在过滤条件中的字符串。使用英文双引号 (")，而不是使用单引号 (')。如需查看示例，请参阅提供其他参数。

• 请勿在表单中使用网址编码。如果 API 方法需要网址编码，则微件会在您执行该方法时执行转换。

返回的数据过多

如需限制返回的结果数，请在 pageSize 参数中输入一个值，例如 2。pageSize 参数定义返回的最大结果数，可用于大多数 API 方法。

如需选择要返回的特定字段，请使用 fields 参数。如需了解详情，请参阅标准参数。

身份验证

API Explorer 页面上有一个凭据部分。我们建议您将这些字段保留为默认值。默认的身份验证机制是 Google OAuth 2.0。

如需查找该方法所需的 API 范围，请点击显示范围。默认情况下，系统会授予所有必要的范围。

如需详细了解这些概念，请参阅使用 Identity and Access Management 控制访问权限。