使用 API Explorer

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

API Explorer 微件。

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

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

试试看!按钮

在文档中,您可能会看到试试看!按钮,如下所示:

试试看!

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

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

访问 API Explorer

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

执行请求

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

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

如需执行 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 时的常见问题。

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

过滤条件语法无效

您可以复制多行表达式并将其粘贴到 但 APIs 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 参数中输入一个值,例如 2pageSize 参数定义了 返回的结果数,适用于大多数 API 方法。

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

身份验证

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

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

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