Skip to main content
每個 /v1 清單端點都會傳回相同的封包,並以相同方式進行分頁:採用權杖機制,且僅能向前翻頁。

清單封包

string
一律為 "list"。
array
該頁的資源,依穩定且具確定性的順序排列。
string | null
在下一次請求中將此值作為 page_token 傳入,即可取得下一頁。 若已無更多結果,則為 null。
boolean
此頁之後是否還有更多結果。

請求參數

integer
預設值:"25"
每頁筆數。須為介於 1 至 500 之間的整數。超出此範圍的值會傳回 400,錯誤代碼為 invalid_request。
string
上一個回應中的 next_page_token。取得第一頁時請省略此參數。
本 API 不提供位移(offset)參數、不支援回溯至上一頁,也不提供精確的總筆數。若要計算某個集合的筆數,請逐頁走訪該集合。
**例外:**即使您要求更高的 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 錯誤並修正請求,再從第一頁重新開始。請勿默默捨棄先前已處理的資料,也不要將中斷的匯出標示為已完成。若需要精確的報表總數,請使用適當的報表資源,而非將即時的清單走訪視為快照。