使用 API Explorer

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

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

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

试试看！按钮

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

试试看！

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

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

访问 API Explorer

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

执行请求

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

metricDescriptors.list 方法会返回项目中所有可用指标类型的描述符。唯一的必需参数是 name 参数。

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

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

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

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

提供其他参数

您看到的参数列表取决于 API Explorer 微件的附加方法。例如，metricDescriptors.list 方法包含的不仅仅是 name 参数，但 name 是唯一的必需参数。

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

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

点击试试看！
在 name 参数中，使用 projects/[PROJECT_ID] 格式输入项目的 ID。请务必将 [PROJECT_ID] 替换为您的项目 ID。
确保 filter 参数的值为 metric.type=ends_with("utilization")
点击执行并完成授权对话框。

标准参数

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

显示标准参数切换开关。

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

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

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

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

点击试试看！
在 name 参数中，使用 projects/[PROJECT_ID] 格式输入项目的 ID。请务必将 [PROJECT_ID] 替换为您的项目 ID。
确保 filter 参数的值为 metric.type=ends_with("utilization")
点击显示标准参数，然后验证 fields 参数的值为 metricDescriptors.type,metricDescriptors.description
点击执行并完成授权对话框。

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

问题排查

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

如需详细了解如何使用 Cloud Monitoring API，请参阅排查 Cloud Monitoring API 问题。

过滤条件语法无效

复制多行表达式并将其粘贴到 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 参数。如需了解详情，请参阅标准参数。

Authentication

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

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

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