排除 Cato API 调用故障

本文提供了在使用 Cato 和 API 工具及软件运行 API 查询时可能出现的常见错误的故障排除建议。 例如，Altair 和 Postman。

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

必填 API 参数

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

• accountMetrics 查询
  • id - 账户ID
  • 时间范围 - 查询返回的数据时间范围
  • groupDevices - 对于多个站点，以及具有多个 Sockets 的站点，将分析合并到一个 Socket 中（对于布尔值 true）
• accountSnapshot 查询
  • id - 账户ID

常见 GRAPHQL_PARSE_FAILED 错误

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

消息：意外的 )

查询中多余一个括号。 通常，当您未为参数提供布尔值时，会导致此错误。 例如，使用 groupInterfaces: ， 而不是 groupInterfaces: true，

消息：预期名称，发现 <character>

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

消息：预期名称，发现 <Invalid>

错误消息表示存在无效值。

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

常见 GRAPH_QL_VALIDATION_FAILED 错误

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

消息：预期类型 String！，发现 <number>

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

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

消息：预期类型 Int！，发现 \"<number>\"

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

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

API 错误消息

本节解释了与 Cato GraphQL 模式或格式不直接相关的常见错误消息。

消息：认证错误

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

• 在 Cato 管理应用程序 (系统 > API 访问管理) 中，确保您使用的 API 密钥仍然有效。 密钥被撤销时会被删除。
• 确认密钥在 API 查询软件的 HTTP 头设置中已正确配置：x-api-key <密钥值>
• 如果问题继续，生成一个新 API 密钥并将其添加到 API 查询软件中

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

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

在维护时间窗口运行脚本时出现的一般 API 错误

在维护时间窗口期间（通常为隔周星期日），Cato 会升级 API 服务器，可能会暂时不可用长达两分钟。 如果您正在运行递归 API 脚本，则在维护窗口期间脚本可能会失败并返回错误。 这对您的账户数据没有影响。

有关计划维护窗口和 Cato Cloud 状态的最新信息，请参阅 https://status.catonetworks.com/。

API 服务器超时的一般 API 错误

如果 API 查询的延迟超过 40 秒，则 API 服务器超时，您需要重新运行查询。 我们建议您为您的 Cato 账户的 API 脚本包括一个重试机制。 此机制应至少包括两次重试尝试，每次重试尝试之间至少等待 30 秒。