/v1 清單端點都會傳回相同的封包,並以相同方式進行分頁:採用權杖機制,且僅能向前翻頁。
清單封包
string
一律為
"list"。array
該頁的資源,依穩定且具確定性的順序排列。
string | null
在下一次請求中將此值作為
page_token 傳入,即可取得下一頁。
若已無更多結果,則為 null。boolean
此頁之後是否還有更多結果。
請求參數
integer
預設值:"25"
每頁筆數。須為介於 1 至 500 之間的整數。超出此範圍的值會傳回
400,錯誤代碼為 invalid_request。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 錯誤並修正請求,再從第一頁重新開始。請勿默默捨棄先前已處理的資料,也不要將中斷的匯出標示為已完成。若需要精確的報表總數,請使用適當的報表資源,而非將即時的清單走訪視為快照。
