REST APIでフォルダーとファイルを一覧表示

GET https://api.dosya.dev/api/filesを使って、ワークスペース内の1か所で表示可能なフォルダーとファイルを一覧表示します。リクエストはメタデータ、パンくずリスト、権限、ファイル一覧のページ情報を返します。ファイルの内容は返さず、共有リンクも作成しません。

認証情報とアクセスの要件

プロトコルでREST APIを許可した読み取り専用またはフルアクセスのAPIキーを作成してください。連携から他のワークスペースを列挙させない場合は、対象のワークスペースに固定してください。フォルダーアンカー付きの通常のAPIキーはRESTで拒否されるため、このエンドポイントではフォルダーアンカーを設定せずワークスペースを固定してください。

キーは、そのキーを作成したアカウントのアクセス範囲を制限します。アカウントは引き続きワークスペースのメンバーである必要があり、そのロールにはaccess_filesが必要です。一覧を返す前に、フォルダーのアクセス制限、非表示フォルダーのルール、完全ロック、ワークスペースのメンバーシップが確認されます。

アップロードのみキーでは、このGETエンドポイントを呼び出せません。拒否時には対象の操作が明示されます：This credential's scope is 'upload' and cannot perform GET /api/files。

手順

シークレットを非公開で設定し、GET /api/workspacesから返されたワークスペースIDを使用してください：

read -r -s -p 'API key: ' DOSYA_API_KEY
printf '\n'
export DOSYA_API_KEY
export DOSYA_WORKSPACE_ID='ws_REPLACE_ME'

curl --fail-with-body --silent --show-error --get \
  'https://api.dosya.dev/api/files' \
  -H "Authorization: Bearer $DOSYA_API_KEY" \
  --data-urlencode "workspace_id=$DOSYA_WORKSPACE_ID" \
  --data-urlencode 'page=1' \
  --data-urlencode 'per_page=100' \
  --data-urlencode 'sort=name' \
  --data-urlencode 'dir=asc' \
  -o files-page-1.json

python3 -m json.tool files-page-1.json

workspace_idは必須です。省略するとworkspace_id is requiredが返されます。folder_idを指定しない場合、このルートはワークスペースのルートを一覧表示します。メンバーのアカウントがフォルダーに制限されている場合は、その制限されたルートを一覧表示します。

成功時のJSONには次が含まれます：

• folders：現在の場所にある子フォルダーのメタデータ。
• files：現在のページのファイルメタデータ。後続のファイルルートで使うIDを含みます。
• breadcrumbs：サブフォルダーを一覧表示する場合の、ルートから現在のフォルダーまでの名前。
• workspace_idと特定されたfolder_id。
• 呼び出し元の現在のロールとフォルダーの状態を示すcan_lock、can_hide、folder_view_only。
• pagination.page、per_page、total_files、total_pages。

フォルダーとファイルは別々の配列です。total_filesとtotal_pagesはファイルのページを表し、子フォルダーの数ではありません。

サブフォルダーの一覧表示と名前による絞り込み

既知のフォルダーIDを渡して、そのフォルダーの直下の項目を一覧表示します：

DOSYA_FOLDER_ID='fld_REPLACE_ME'
curl --fail-with-body --silent --show-error --get \
  'https://api.dosya.dev/api/files' \
  -H "Authorization: Bearer $DOSYA_API_KEY" \
  --data-urlencode "workspace_id=$DOSYA_WORKSPACE_ID" \
  --data-urlencode "folder_id=$DOSYA_FOLDER_ID" \
  --data-urlencode 'q=invoice' \
  --data-urlencode 'page=1' \
  --data-urlencode 'per_page=100'

qは前後の空白が取り除かれ、大文字と小文字を区別せず名前と照合されます。特殊なワイルドカード文字は、生のSQLパターンではなく検索テキストとして扱われます。フォルダーに制限されたメンバーが、許可されたサブツリーの外にあるフォルダーを明示的に指定すると、HTTP 403とThis folder is outside the folder you're confined toが返されます。

対応する並べ替えキーにはname、size、created、modified、taken、type、extension、version、uploader、region、origin、shares、commentsがあります。キーを単独で指定し、dir=ascまたはdir=descを併用してください。newest、oldest、largest、smallestなどの従来の値も受け付けます。不明な並べ替え入力は新しい順にフォールバックします。

ファイルのすべてのページを取得

標準の1ページあたりの件数は100です。per_pageは10–500の範囲に収められ、pageは1から始まります。返されたページがpagination.total_pagesに達するまで続けてください：

import json, os, urllib.parse, urllib.request

base = 'https://api.dosya.dev/api/files'
workspace = os.environ['DOSYA_WORKSPACE_ID']
key = os.environ['DOSYA_API_KEY']
page = 1

while True:
    query = urllib.parse.urlencode({
        'workspace_id': workspace,
        'page': page,
        'per_page': 500,
        'sort': 'name',
        'dir': 'asc',
    })
    req = urllib.request.Request(base + '?' + query,
        headers={'Authorization': 'Bearer ' + key})
    with urllib.request.urlopen(req) as response:
        body = json.load(response)
    for item in body['files']:
        print(item['id'], item['name'], item['size_bytes'])
    if page >= body['pagination']['total_pages']:
        break
    page += 1

オフセット方式では、ページを取得している間にファイルが変化する場合があります。安定したエクスポートのため、実行中は名前変更、アップロード、削除を同時に行わず、収集した行をファイルIDで重複排除してください。

アクセスとロックの応答を解釈

応答	意味と次の操作
401、Not authenticatedまたは無効なキーを示すテキスト	完全なBearerトークンを設定し直し、有効期限や取り消しを確認してください。
403、This API key is not permitted to use the api surface	プロトコルの選択にREST APIを含むキーを作成してください。
403、Not a member of this workspace	ワークスペースIDを確認し、メンバーシップを復元してください。キーでメンバーシップを付与することはできません。
403、You don't have access to the files page	現在のロールにaccess_filesがありません。ワークスペースの管理者に変更を依頼してください。
403とerror: "folder_locked"、lock_mode: "full_lock"	連携がロックされたフォルダーに対応している場合は、許可された手順でフォルダーのロックを解除し、現在のutトークンを渡してください。
404、Folder not found	このリクエスト元にとってフォルダーは存在しません。非表示フォルダーや非表示の親の配下にあるフォルダーも含まれます。この応答から非表示コンテンツを推測しないでください。

呼び出し元に非表示コンテンツを管理する権限がない場合、非表示のファイルとフォルダーは通常の結果から除外されます。view_onlyフォルダーは引き続き一覧表示でき、クライアントがダウンロード操作を抑制できるよう、応答にfolder_view_only: trueが設定されます。

期待される結果

各リクエストはHTTP 200とともに、指定した場所で認証情報の持ち主が表示できるフォルダーとファイルだけを返します。pagination.total_pagesに従ってページを取得すると、ファイルの内容をダウンロードしたりワークスペースを変更したりせずに、アクセス可能なファイル一式を取得できます。

関連ガイド

• REST APIを使い始める
• 読み取り可能なAPIキーを選択
• APIエラーとページ分割への対応