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 です。最初のページでは省略します。
オフセットパラメーター、前のページへの移動、正確な総件数はありません。コレクションの件数を数えるには、コレクションを順に取得してください。
例外: GET /v1/cohorts/{id}/members は、limit にそれより大きい値を指定した場合でも、1 ページあたり最大 50 行までしか返しません。has_more と next_page_token は、引き続きコホートの実際の残りを反映します。
いずれかの Basic 認証情報の形式で認証してください。詳細は クイックスタート(apikey:secret または secret:)を参照してください。 BASE には、組織のリージョン別ホストを設定してください。詳細は リージョン を参照してください。

リストを順に取得する

クイックスタートと同様に、シークレットマネージャーから LIVING_SECURITY_API_KEY を読み込みます。 この例では entity:read が必要です。最初のリクエストのガイドで使用したキーには、この追加の権限付与が必要になる場合があります。Python の例では requests を、シェルの例では jq をインストールしてください。どちらの例もバージョンを固定し、フィルターを変更せず、リダイレクトを拒否します。エラーが発生した場合、および 1,000 ページに達した場合は処理を停止し、一部のみの取得を完了として報告することはありません。Python の読み取りタイムアウトは、処理全体の所要時間ではなく、無通信時間を制限するものです。ジョブ全体の期限は、お使いの連携側で設定してください。 next_page_token が null になるまでページをリクエストします。一括読み取りでは、より少ないリクエスト数でコレクション全体を取得できるよう、limit=500 を推奨します。詳細は レート制限 を参照してください。

ページネーション中はフィルターを固定する

ページトークンは、署名された不透明なカーソルです。各トークンは、それを発行したリクエストの組織、認証済みのサービスアカウント、契約バージョン、および正確なフィルターセットに紐づけられています。たとえば 2 ページ目で type フィルターを追加するなど、順次取得の途中でこれらのいずれかを変更すると、page_token パラメーターに対してコード invalid_request の 400 が返されます。
400 Invalid request
フィルターを変更するには、最初のページから新たに取得をやり直してください。
page_token は不透明な文字列として扱い、受け取ったとおりに返してください。トークンをデコードしたり、長期間保存したり、自分で生成したりしないでください。内部形式は予告なく変更されることがあります。
リストエンドポイントは、サポートしていないクエリパラメーターが指定されると、そのパラメーターを示す 400 invalid_request を返して拒否します。サポートされているフィルターについては、各エンドポイントのリファレンスを確認してください。

中断された、または変化するコレクションへの対処

これらの例では、エラーを自動的に再試行しません。429 の場合は、Retry-After に従い、制限付きの再試行ガイダンスに従ってください。読み取りを再試行する際は、同じリージョン、サービスアカウント、バージョン、フィルター、および最後に正常に処理したページトークンを使用してください。認証情報を変更してもアクセス権は付与されません。各リクエストでは、常に現在の権限が確認されます。 複数ページにわたる読み取りは、コレクションのスナップショットではありません。取得している間にも行が変更される可能性があります。リソースは安定した id で処理し、下流への書き込みは冪等にしてください。再開すると、同じ行が再び返されることがあります。トークンが拒否された場合は、page_token エラーを確認し、リクエストを修正してから最初のページからやり直してください。処理済みのデータを黙って破棄したり、中断されたエクスポートを完了としてマークしたりしないでください。正確な集計値が必要な場合は、ライブのリスト取得をスナップショットとして扱うのではなく、適切なレポートリソースを使用してください。