REST APIのファイル一覧をページごとに取得する

ファイル一覧は番号付きのオフセットページを使用します。GET /api/filesから保存する継続トークン、カーソル、次ページの値はありません。

リクエストと応答

GET /api/files?workspace_id=wks_…&folder_id=fld_…&page=1&per_page=100を呼び出してください。ワークスペースのルートにはfolder_idを省略します。pageの初期値は1、per_pageの初期値は100で、10〜500の範囲に制限されます。ページ番号の上限は10,000,000です。小数は切り捨てられ、不正な値には安全な既定値が使用されます。

応答にはfolders、ページ分割されたfiles、breadcrumbs、解決されたworkspace_idとfolder_id、can_lock、can_hide、folder_view_only、paginationが含まれます。

手順

1. 走査中のワークスペース、フォルダー、フィルター、検索、並べ替えを固定し、10〜500のper_pageを選択してください。
2. page=1をリクエストしてok:trueを確認し、pagination.page、per_page、total_files、total_pagesを記録してください。
3. filesの各要素を安定したidで処理してください。folders配列はファイルのページ件数には含めず、フォルダーの情報として扱ってください。
4. ページ番号を増やし、返されたページがpagination.total_pagesと等しくなるまで同じクエリを繰り返してください。
5. 1つの安定したエクスポートが必要な場合は、ファイルIDの重複を除き、並行するアップロード、移動、削除を避けてください。
6. 処理済みの一意のIDの数を表示可能な結果と照合し、403、404、429、503によるページの失敗を復旧のために保持してください。

ページ分割の詳細

pagination.total_filesはフォルダーではなくファイルを数えます。total_pagesは一致するファイルがなくても1以上です。これはlimit/offset方式のページ分割なので、処理中の変更によって行がページ間で移動することがあります。IDによる重複排除は二重処理を防ぎますが、過去のスナップショットを再現することはできません。

このエンドポイントは応答のETagに対応しています。シリアライズされた一覧に変更がない場合、条件付きリクエストはHTTP 304を返すことがあります。

RESTが有効な読み取り専用またはフルアクセスのキーと、access_filesを持つロールを使用してください。アップロード専用はThis credential's scope is 'upload' and cannot perform GET /api/filesで拒否されます。フォルダーに固定されたキーはこのRESTルートを使用できません。

期待される結果

クライアントは1ページ目からtotal_pagesまでを処理し、選択したクエリで表示可能な各ファイルIDを1回ずつ処理します。APIが返さない継続フィールドを待つことはありません。

関連ガイド

• APIでファイルを一覧表示する
• APIエラーに対処する