在开始使用Cato API之前，我们强烈建议您查看Cato API访问权限策略。

accountMetrics概览

accountMetrics查询帮助您分析站点和SDP用户到Cato Cloud的连接状态和质量。 此数据用于站点与Cato Cloud之间DTLS隧道内的流量。

accountMetrics显示账户的历史指标、统计和分析。 它返回与Cato管理应用程序中的站点连接性窗口相似的数据。

对于经销商账户，您可以在连接到Cato API的每个客户账户内创建单独的API密钥。 有关速率限制和accountMetrics API查询的更多信息，请参阅了解Cato API速率限制。

处理存储桶的粒度和API 查询限制

每个accountMetrics API 查询返回的项目数最多为100,000个。 如果查询达到此限制，则不会返回任何其他数据，并显示错误消息。

Cato根据以下元素的乘积计算此限制：

• 站点总数加上VPN用户
• 指标数量（API标签/遥测）
• 存储桶数量

换句话说，（站点 + VPN用户）*（指标）*（存储桶）的总和必须小于100,000。 例如，以下查询将产生错误：

• 10个站点
• 140个VPN 用户
• 5个指标
• 150个存储桶

（10 + 140）* 5 * 150 = 查询中112,500个项目。 在此示例中，您可以减少存储桶的数量以成功运行查询。

有关API 标签类型的更多信息，请参阅Cato API - AccountMetrics > 时间序列。

计算查询的最小粒度

本部分说明如何根据查询的时间框架计算最小粒度（存储桶大小）。

1. 时间框架 - 将时间框架转换为秒
2. 存储桶限制 - 基于100000 / （（站点 + VPN用户）*（指标））计算存储桶限制
3. 最小粒度 = （时间框架） / （存储桶限制）

例如，下表中的第一行显示了7天、100个站点和VPN用户、5个指标的查询限制：

• 7天 = 604,800秒
• 200个存储桶 = 10000 / （100）*（5）
• 3024秒最小粒度 = 604800 / 200

下表显示了具有最小存储桶粒度的accountMetrics查询的示例设置：

accountMetrics字段的详细信息

这些是accountMetrics字段可以为查询返回的详细信息：

• ID - 账户ID
• from - 起始时间
• to - 结束时间
• granularity - 存储桶大小
• 站点 -每个站点返回的数据（包含嵌套查询和字段的数组）
• timeseries - 数据的时间框架，并定义存储桶和数据之间的关系（包含嵌套查询和字段的数组）

accountMetrics ID

ID 字段显示唯一的账户内部ID。

此账户ID不会在Cato 管理应用程序中显示，而是在Cato 管理应用程序的URL中显示为数字。 例如，对于以下URL，账户ID是26： https://cc2.catonetworks.com/#!/26/topology。

accountMetrics起始

起始字段显示查询数据的起始时间，定义在timeFrame参数中。

accountMetrics结束

结束字段显示查询数据的结束时间，定义在timeFrame参数中。

accountMetrics粒度

粒度字段显示单个指标存储桶的持续时间（秒）。 存储桶数量在timeseries > bucket参数中定义。

粒度根据以下公式计算：时间范围/存储桶。 例如，如果查询返回五分钟的数据（时间框架），有60个存储桶，则粒度（存储桶大小）是5秒（300秒 / 60）。

存储桶的最小粒度为5秒。 当存储桶的粒度小于5秒时，可能不会返回该存储桶的数据。

有关粒度字段的更多信息，请参阅处理accountMetrics > 粒度。

accountMetrics站点

站点字段包含与账户中的一个或多个站点相关的数据。 您还可以使用用户ID指定VPN 用户的数据。

有关accountMetrics的站点字段的更多信息，请参阅Cato API - AccountMetrics > 站点。

accountMetrics时间序列

根据查询中指定的时间框架（存储桶），显示账户的指标，并包括历史统计和指标。 此数据类似于Cato管理应用程序中的站点连接性窗格为每个站点提供的字段。

有关 accountMetrics 的时间序列字段的更多信息，请参见 Cato API - AccountMetrics > Timeseries。

accountMetrics 的参数

这些是您可以传递的参数，并定义查询返回的数据：

• accountID - 账户 ID
• ID - 账户 ID（传统参数）
• timeFrame - 查询的起始和结束时间
• groupInterfaces - 将链接的分析合并为一个链接（对于布尔值 true）
• groupDevices - 对于多个站点和具有多个 Sockets 的单个站点，将分析合并为一个 Socket（对于布尔值 true）

accountMetrics 账户 ID 参数

输入查询返回数据的账户 ID。 此参数是必需的。

此账户 ID 不显示在 Cato 管理应用程序中，而是在 Cato 管理应用程序的网址中显示的号码。 例如，以下网址中账户 ID 为 26：https://cc2.catonetworks.com/#!/26/topology。

accountMetrics 时间范围参数

输入查询返回数据的时间范围。 参数的格式为 <type>.<time value>。 此参数是必需的。

以下是定义时间范围的支持选项：

• last.<时间持续时间> - last 类型的 <时间持续时间> 值符合 ISO-8601 标准，并返回前面特定时间的数据。 例如：
  • timeFrame = last.PT5M 显示前 5 分钟
  • timeFrame = last.PT2H 显示前 2 小时
  • timeFrame = last.P1D 显示前 1 天
  • timeFrame = last.P3M 显示前 3 个月
  • timeFrame = last.P1Y 显示前 1 年
• utc.<短时间范围规范> - 时间范围根据指定的时区按格式 YY-MM-DD/hh:mm:ss 组合开始和结束日期。 您必须为参数输入所有日期和时间值。 例如：
  • timeFrame = utc.2020-02-{11/04:50:00--21/04:50:00} 显示 2020 年 2 月 11 日上午 4:50:00 到 2020 年 2 月 21 日上午 4:50:00 为期 10 天的分析数据
  • timeFrame = utc.2020-02-11/{04:50:15--16:50:15} 显示 2020 年 2 月 11 日上午 4:50:15 到下午 16:50:15 的 12 小时分析数据
  • timeFrame = utc.2020-{02-11/04:50:00--04-11/04:50:00} 显示 2020 年 2 月 11 日上午 4:50:00 到 4 月 11 日上午 4:50:00 的 2 个月分析数据
  • timeFrame = utc.{2019-10-01/04:50:00--2020-02-01/04:50:00} 显示 2019 年 10 月 1 日上午 4:50:00 到 2020 年 2 月 1 日上午 4:50:00 的 4 个月分析数据

    此格式允许您配置包含多个日历年的时间范围

有关 timeFrame 参数和 Granularity 字段的更多信息，请参见 与 accountMetrics 合作 > Granularity。

accountMetrics groupInterfaces 参数

当布尔参数 groupInterfaces 设置为 true 时，所有接口的数据将聚合到一个接口中。

accountMetrics groupDevices 参数

当布尔参数 groupDevices 设置为 true 时，所有 Sockets 的分析（通常在高可用性中为两个）将聚合为一个结果。 为了获得最佳的聚合 Sockets 结果，我们建议对于两个 Sockets 上的链接具有一致的名称和功能（例如目标）。