Press CTRL+K to open search

排查 Cato API 调用

  • 更新于 Jul 30, 2026
  • 发布于 Jul 7, 2026
  • 1 分钟阅读
Prev Next

本文章提供一些解决常见错误的建议，这些错误可能在使用 API 工具和软件运行 Cato 的 API 查询时出现。 例如，Altair 和 Postman。

不支持与 API 脚本和编码相关的问题。

必需的 API 参数

这些是您必须在 API 查询中包含的参数。 当从 API 查询中去除可选参数时，将使用默认值。

  • accountMetrics 查询

    • id - 账户 ID

    • timeframe - 查询返回数据的时间范围

    • groupDevices - 对于多个站点以及具有多个 Sockets 的站点，将分析数据合并到一个 Socket 中（对于布尔值 true）

  • accountSnapshot 查询

    • id - 账户 ID

常见 GRAPHQL_PARSE_FAILED 错误

本节解释了一些与 Cato GraphQL 架构相关的错误消息常见示例。

消息: 意外的)

查询中有多余的括号。 常常因为没有为参数提供布尔值而导致此错误。 例如，groupInterfaces: , 而不是 groupInterfaces: true,

消息: 预期名称，发现 <字符>

JSON 文件的格式不正确。 消息显示一个与缺少或多余字符相关的字符。 例如，预期名称，发现 ( 对于参数 accountSnapshot((id: 42)。 对此参数的正确格式是 accountSnapshot(id: 1941)

消息: 预期名称，发现 <无效>

错误消息表明有一个参数值无效。

例如，Cato API 中的 timeFrame 参数 (accountMetrics) 使用引号隔开的 ISO 8601 日期时间标准，timeFrame: "last.P1D" 是正确的，而 timeFrame: last.P1D 则会产生此错误。

常见 GRAPH_QL_VALIDATION_FAILED 错误

本节解释了一些与查询参数格式不正确相关的错误消息常见示例。

消息: 预期类型 String !，发现 <数字>

错误消息表明参数有一个无效值，通常与参数格式有关。

例如，站点 IDs 参数 (accountMetrics > 站点) 是一个字符串，因此您必须为值使用引号，ids: ["4242"] 是正确的，ids:[4242] 则会产生此错误。

消息: 预期类型 Int !，发现 \"<数字>\"

错误消息表明参数有一个无效值，通常与参数格式有关。

例如，站点 IDs 参数 (accountSnapshot > 站点) 是一个整数，因此不应为值使用引号，ids: [2626] 是正确的，ids:["2626"] 则会产生此错误。

API 错误消息

本节解释的一些常见错误消息不与 Cato GraphQL 架构或格式特定相关。

消息: 身份验证错误或 403

您账户的 API 密钥出现问题。 建议的解决方案：

  • 在 Cato 管理应用程序 (系统 > API 访问管理) 中，确保：

    • 您正在使用的 API 密钥仍然有效（存在且未过期）

    • 如果设置了 允许来自 IP 的访问 选项，则 API 客户端从某个特定允许的 IP 地址或范围进行调用

  • 确认密钥在 API 查询软件的 HTTP 头设置中配置正确：x-api-key: <密钥值>，例如 x-api-key: abcdef12345

  • 若问题继续，生成一个新的 API 密钥并添加到 API 查询软件中

这是一个 API 客户端的有效 HTTP 头示例：

POST /api/v1/graphql2 HTTP/2
Host: api.catonetworks.com
User-Agent: curl/8.7.1
Accept: */*
Content-Type:application/json
x-api-key: abcdef123456789

消息：当选择多个站点时无法分离设备（组设备 = false）

当查询包含多个站点时，groupDevices 参数(accountMetrics) 的值必须为 true。

转换 API 分析数据

Cato API 返回的数据为字节。 要将数据转换为更大单位（例如 MB 或 GB），您需要除以 1024 的指数值：MB 用 10242，GB 用 10243。

例如，要将 536,870,912,000 字节转换为 GB，请除以 10243，显示为 500GB 的数据。

相关文章