--- title: "Cato API - 账户指标" slug: "cato-api-accountmetrics" updated: 2026-07-30T03:23:12Z published: 2026-07-30T03:23:12Z canonical: "knowledge.catonetworks.com/cato-api-accountmetrics" --- > ## Documentation Index > Fetch the complete documentation index at: https://knowledge.catonetworks.com/llms.txt > Use this file to discover all available pages before exploring further. # Cato API - 账户指标 我们强烈建议您在开始使用Cato API之前,请查看[Cato API支持政策](/v1/docs/support-policy-for-the-cato-api)。 ## 账户指标概述 accountMetrics 查询帮助您分析站点和 SDP 用户到 Cato 云的连接状态和质量。 此数据用于站点和 Cato 云之间的 DTLS 隧道内的流量。 accountMetrics 显示账户的历史指标、静态信息和分析。 它返回类似于 Cato 管理应用程序中的**站点连接性**窗口的数据。 对于经销商账户,您可以在每个与 Cato API 连接的客户账户中创建单独的 API 密钥。 有关速率限制和 accountMetrics API 查询的更多信息,请参见[了解 Cato API 速率限制](/v1/docs/understanding-cato-api-rate-limiting)。 ## 使用存储桶粒度和 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 > 时间序列](/v1/docs/cato-api-accountmetrics-timeseries)。 ### 计算查询的最小粒度 本节说明如何根据查询时间范围计算最小粒度(存储桶大小)。 1. 时间范围 - 将时间范围转换为秒 2. 存储桶限制 - 计算基于 100000 / ((站点 + VPN 用户) * (指标)) 的存储桶限制 3. 最小粒度 = (时间范围) / (存储桶限制) 例如,下面表格中的第一行显示了 7 天、100 个站点和 VPN 用户与 5 个指标的查询限制: - 7 天 = 604,800 秒 - 200 存储桶 = 10000 / (100) * (5) - 3024 秒最小粒度 = 604800 / 200 下表显示了具有最小存储桶粒度的 accountMetrics 查询的示例设置: | 查询时间范围(天) | 站点和 VPN 用户 | 指标(标签) | 存储桶限制 | 最小粒度(秒) | | --- | --- | --- | --- | --- | | 7 (604800 秒) | 100 | 5 | 200 | 3024 | | 7 (604800 秒) | 100 | 10 | 100 | 6048 | | 7 (604800 秒) | 500 | 10 | 20 | 30240 | | 3 (259200 秒) | 100 | 5 | 200 | 1296 | | 3 (259200 秒) | 100 | 10 | 100 | 2592 | | 3 (259200 秒) | 500 | 10 | 20 | 12960 | | 1 (86400 秒) | 100 | 5 | 200 | 432 | | 1 (86400 秒) | 100 | 10 | 100 | 864 | | 1 (86400 秒) | 500 | 10 | 20 | 4320 | ## accountMetrics 字段的详细信息 这些是 accountMetrics 字段可以为查询返回的详细信息: - ID - 账户ID - 从 - 开始时间 - 到 - 结束时间 - 粒度 - 存储桶大小 - sites - 为每个站点返回的数据(数组包含嵌套查询和字段) - timeseries - 数据的时间范围,并定义桶和数据之间的关系(具有嵌套查询和字段的数组) ## accountMetrics ID ID 字段显示唯一的账户内部 ID。 此账户 ID 不会在 Cato 管理应用程序中显示,而是 Cato 管理应用程序 URL 中的数字。 例如,对于以下 URL ,账户 ID 为 26:https://cc2.catonetworks.com/#!/**26**/topology。 ## accountMetrics From From 字段显示查询数据的起始时间,并在 timeFrame 参数中定义。 ## accountMetrics To To 字段显示查询数据的结束时间,并在 timeFrame 参数中定义。 ## accountMetrics 粒度 粒度字段显示单个指标存储桶的秒数。 存储桶的数量在时间序列 > 存储桶参数中定义。 粒度根据以下公式计算:时间范围/存储桶。 例如,如果查询返回五分钟的数据(时间范围)和 60 个存储桶,则粒度(存储桶大小) 为 5 秒(300 秒 / 60)。 一个存储桶的最小粒度为 5 秒。 当存储桶粒度小于5秒时,可能没有数据返回给该存储桶。 有关粒度字段的更多信息,请参见[使用 accountMetrics > 粒度](/v1/docs/working-with-accountmetrics-granularity)。 ## accountMetrics 站点 站点字段包含与账户中的一个或多个站点相关的数据。 您还可以通过其用户ID指定 VPN 用户的数据。 有关 accountMetrics 的站点字段的更多信息,请参见[Cato API - AccountMetrics > 站点](/v1/docs/cato-api-accountmetrics-sites)。 ## accountMetrics 时间序列 根据查询中指定的时间范围(存储桶)显示账户的指标,包括历史统计和指标。 此数据类似于每个站点的 Cato 管理应用程序中的 **站点连接性** 窗口。 有关 accountMetrics 时间序列字段的更多信息,请参见[Cato API - AccountMetrics > 时间序列](/v1/docs/cato-api-accountmetrics-timeseries)。 ## accountMetrics 参数 这些是您可以传递的参数,并定义查询返回的数据: - accountID - 账户ID - ID - 账户ID(旧参数) - 时间范围 - 查询的开始和结束时间 - groupInterfaces - 将链接的分析结果合并为一个链接(对于布尔值 **true**) - groupDevices - 对于多个站点,以及一个具有多个套接字的单个站点,将分析结果合并为一个套接字(对于布尔值 **true**) ## accountMetrics accountID 参数 输入查询返回数据的账户 ID。 此参数是强制性的。 此账户 ID 不会在 Cato 管理应用程序中显示,而是 Cato 管理应用程序 URL 中的数字。 例如,对于以下 URL ,账户 ID 为 26:https://cc2.catonetworks.com/#!/**26**/topology。 ## accountMetrics timeFrame 参数 输入查询返回数据的时间范围。 参数格式为`<类型>.<时间值>`。 此参数是强制性的。 这些是用于定义时间范围的支持选项: - 最后.<时间期限> - `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 到 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 月 11 日凌晨 4:50:00 的 4 个月分析数据 这种格式允许您配置包含多个日历年的时间框架 有关 timeFrame 参数和粒度字段的更多信息,请参见[使用 accountMetrics > 粒度](/v1/docs/working-with-accountmetrics-granularity)。 ## accountMetrics groupInterfaces 参数 当布尔参数 groupInterfaces 设置为 **true** 时,所有接口的数据将聚合到单一接口。 ## accountMetrics groupDevices 参数 当布尔参数 groupDevices 设置为 **true** 时,所有套接字(通常在高可用性情况下为两个)的分析结果将聚合为一个结果。 为了获得聚合套接字的最佳结果,我们建议链接在两套接字上具有一致的名称和功能(例如,目的地)。 **注意:** 该参数对于多个站点的查询是强制性的,并且 groupDevices 的唯一有效值为 **true**。