使用 API Explorer

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

API Explorer 微件。

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

您也可以通过点击面板顶部的 按钮来隐藏微件,或点击 按钮将其展开至全屏。

试试看!按钮

在文档中,您将看到试试看!按钮,如下面的一些示例所示:

试试看!

点击该按钮后,系统会在相应的参考页面上显示 API Explorer,并根据示例填充相应字段。您必须修改一些字段以匹配您自己的项目,例如 [PROJECT_ID] 的值。

如需详细了解如何避免错误和纠错,请参阅提示

访问 API Explorer

API Explorer 会附加到每种 REST API 方法的参考页面。要查找微件,请转到相应方法的参考页面,例如 monitoring.projects.metricDescriptors.list 的参考页面

执行最小请求

大多数方法都有一些必需参数和一些可选参数。系统会用红色条标记必填项,直到填充完毕。您只需提供必需参数即可执行最小请求。

metricDescriptors.list 方法会返回项目中所有可用指标类型的描述符。唯一的必需字段是 name 字段。要检索项目的此列表,请使用 projects/[PROJECT_ID] 形式提供项目名称作为 name

请点击下面的按钮进行尝试,但在点击表单上的执行按钮之前,您需要将 [PROJECT_ID] 更改为项目的标识符:

试试看!

方法调用的结果显示在执行按钮下方的框中。通常,该框会包含一个绿色标头,其中包含 HTTP 状态代码 200,表示请求成功。调用的结果显示在框中:

成功调用方法的结果。

如果标头为红色且包含 HTTP 失败代码,则该框中包含错误消息。请参阅提示,了解有关解决错误的一些提示。

提供其他参数

您看到的参数列表取决于 API Explorer 微件的附加方法。metricDescriptors.list 方法不止有 name 参数,但 name 是唯一必需参数。

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

例如,填写 metricsDescriptor.list 页面上的以下字段。使用您的项目 ID 替代 [PROJECT_ID],但提供另一个值,如下所示:

  • 名称projects/[PROJECT_ID]
  • 过滤条件metric.type=ends_with("utilization")

执行此请求仅返回名称以 utilization 结尾的指标类型的描述符。

试试看!

使用字段进一步限制输出

默认情况下,API Explorer 显示的参数集与关联方法的参数相对应。但是,API Explorer 微件还具有一组额外字段,这些字段无法通过方法本身使用。

这些参数隐藏在身份验证部分上方的切换开关显示标准参数下:

“显示标准参数”切换开关。

点击此切换开关可显示其他微件参数。点击隐藏标准参数可隐藏这些参数。

这些标准参数中最有用的是 fields 参数,您可以在返回的输出中选择要查看的字段。这在 API Explorer 面板中非常有用,其中输出显示在框中。通常需要滚动浏览大量输出。

例如,列出以 utilization 结尾的指标的描述符仍然返回大量信息。如果您只想了解指标类型的名称及其说明,则可以仅使用 fields 字段指定这些字段。

要查看差异,请在 metricsDescriptor.list 页面上填写以下字段。使用您的项目 ID 替代 [PROJECT_ID],但提供如下所示的其他值:

  • name,和前面一样:projects/[PROJECT_ID]
  • filter,和前面一样:metric.type=ends_with("utilization")
  • 字段metricDescriptors.type,metricDescriptors.description

执行此请求仅返回每个指标的 type(简称)及其 description。以下是输出的一部分:

试试看!

提示

记住更改 [PROJECT_ID]

请务必将 [PROJECT_ID] 替换为您的项目 ID。如果您忘记了,则会得到以下结果:

忘记更改 PROJECT_ID 时出现的错误消息。

值问题

以下是使用 API Explorer 表单时需要注意的一些问题。这些错误可能会导致错误或被接受,但可能会被视为 API 方法中的拼写错误:

  • 请勿在任何类型的字段值前后加上引号。
  • 请务必用英文引号括住过滤器内的字符串。使用双引号 ("),不要使用单引号 (')。有关示例,请参阅提供其他参数
  • 请勿在表单字段中使用反斜杠或网址编码。如果需要,在执行方法时对字段值执行网址编码。
  • 在执行调用后查看结果框中的值。您可能会在此处发现问题。
  • 您可能希望为 pageSize 字段提供一个值,例如 2。这限制了在您调试 API 调用时返回的数据量。

用于调试的书签网址

获得所需的输出后,将 API Explorer 网址添加为书签。如果想要再次运行该方法,请将网址粘贴到浏览器中。您会看到表单已填入您的值。对参数进行必要的更改,然后点击执行以再次运行该方法。

身份验证

在 API Explorer 页面的执行按钮上方有一个身份验证部分。您通常不需要更改此处的内容。

默认身份验证机制为 Google OAuth 2.0

身份验证部分中还有一个显示范围切换开关。这将显示您可用的 Compute Engine 范围。默认情况下,系统会启用所有可用范围。

如需详细了解这些概念,请参阅访问控制

问题排查

如果您仍遇到问题,请参阅排查 Monitoring API 问题