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