Skip to main content
每个 /v1 列表端点都返回相同的信封,并以相同的方式进行分页:基于令牌,仅支持向前翻页。

列表信封

string
始终为 "list"。
array
当前页的资源,按稳定且确定的顺序排列。
string | null
在下一次请求中将其作为 page_token 传入,以获取下一页。 没有更多结果时为 null。
boolean
当前页之后是否还有更多结果。

请求参数

integer
默认值:"25"
每页数量。取值为 1 到 500 之间的整数。超出该范围的值将返回带有代码 invalid_request 的 400。
string
上一次响应中的 next_page_token。获取第一页时请省略该参数。
不提供偏移量参数,不支持向前一页回溯,也不提供精确的总数。如需统计集合的数量,请遍历该集合。
**例外情况:**即使您请求了更大的 limit,GET /v1/cohorts/{id}/members 每页最多也只返回 50 行。has_more 和 next_page_token 仍会反映该群组的实际剩余数量。
可使用任一种 Basic 凭据形式进行身份验证,请参阅快速入门(apikey:secret 或 secret:)。 请将 BASE 设置为组织所在区域的主机,请参阅区域。

遍历列表

按照快速入门中的方式,从您的密钥管理器中加载 LIVING_SECURITY_API_KEY。 此示例需要 entity:read;用于首次请求指南的密钥可能需要获得该额外授权。Python 示例请安装 requests,Shell 示例请安装 jq。两个示例都固定了版本,保持筛选条件不变,并拒绝重定向。它们会在出错时以及达到 1,000 页后停止,而不会把不完整的遍历报告为已完成。Python 的读取超时限制的是无活动时间,而不是作业总时长;请在您的集成中设置作业截止时间。 持续请求各页,直到 next_page_token 为 null。进行批量读取时,建议使用 limit=500,以便用更少的请求覆盖整个集合,请参阅速率限制。

分页期间保持筛选条件不变

页面令牌是不透明的签名游标。每个令牌都绑定到生成它的请求所对应的组织、已验证的服务账户、合约版本以及完整的筛选条件集合。在遍历过程中更改其中任何一项(例如在第二页添加 type 筛选条件),都会返回 400,其代码为 invalid_request,涉及的参数为 page_token:
400 Invalid request
如需更改筛选条件,请从第一页重新开始遍历。
请将 page_token 视为不透明字符串:按收到时的原样传回。 请勿解码、长期存储或自行构造令牌,其内部格式可能随时更改,恕不另行通知。
列表端点会拒绝其不支持的查询参数,并返回指明该参数的 400 invalid_request。请查阅各端点的参考文档,了解其支持的筛选条件。

处理中断或发生变化的集合

这些示例不会自动重试错误。对于 429,请遵循 Retry-After,并参照有限度的重试指南。重试读取请求时,请保持相同的区域、服务账户、版本、筛选条件以及最近一次成功处理的页面令牌。更换凭据并不会授予访问权限:每个请求仍会检查当前权限。 多页读取并非集合的快照。在您遍历期间,行数据可能发生变化。请根据稳定的 id 处理资源,并确保下游写入具有幂等性;重新启动后可能会再次返回同一行。如果令牌被拒绝,请检查 page_token 错误并更正请求,然后再从第一页重新开始。请勿静默丢弃已处理的数据,也不要将中断的导出标记为已完成。如需精确的报表总数,请使用相应的报表资源,而不要将实时列表遍历视为快照。