排查 Cato API 调用

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

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

必需的 API 参数

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

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

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

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

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

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

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

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

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

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

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

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

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

您账户的 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

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

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

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