APIで識別子からファイルのメタデータを取得

単一ファイルのエンドポイントは、識別情報、ストレージ、保存場所、バージョン、表示状態、共同作業の件数を1件のレコードで返します。nullフィールドも有効なデータであり、必ずしも検索の失敗を意味しません。

アクセス要件

REST APIで許可された読み取り専用またはフルアクセスキーでGET https://api.dosya.dev/api/files/:idを呼び出してください。キーの対象をワークスペースに限定できますが、フォルダーをアンカーに設定するとRESTは使用できません。現在のメンバーのロールにはaccess_filesが必要です。

手順

1. 信頼できる一覧、アップロードの応答、またはWebhookから既知のfile_…のIDを取得し、想定されるワークスペースとともに保持してください。
2. Bearerヘッダーを付けてGET /api/files/:idを送信し、画面表示用の値ではなくJSONを取得してください。
3. file.id、workspace_id、folder_id、nameを連携先で選択したレコードと照合してください。
4. size_bytes、mime_type、extension、region、current_version、etag、content_hashを検証対象の操作と比較してください。
5. created_atとupdated_atをUnix時刻の秒数として解釈し、uploader_nameやcontent_hashなどにnullが入ることを考慮してください。
6. アプリに必要なメタデータを記録し、公開ログには表示状態や識別情報の詳細を含めず、403/404は応答本文に応じて処理してください。

返されるファイルのフィールド

成功時の本文は{ok:true,file:{…}}です。ファイルオブジェクトにはid、name、size_bytes、mime_type、extension、region、uploaded_by、uploader_name、created_at、updated_at、deleted_at、lock_mode、is_hidden、hidden_mode、current_version、workspace_id、folder_id、content_hash、etag、share_count、comment_countが含まれます。

検証済みハッシュまたは遅延計算されたハッシュがまだない場合は、content_hash:nullが返されることが想定されます。アップロード者の行がない場合、uploaded_byが存在していてもuploader_nameはnullになることがあります。

期待される結果

HTTP 200で、呼び出し元が想定したファイルIDとワークスペースが返されます。整合性や同期の判断に使えるバイト単位のサイズとバージョンのメタデータも含まれます。

トラブルシューティング

Missing file IDはルート入力の400エラーです。File not foundは、ファイルの不存在またはプライバシーを守るための非表示やアクセス範囲の制限を示す場合があります。403はメンバーシップ、ファイルページの権限、メンバーのフォルダー制限、フォルダー全体のロック、キースコープ、接続先、ワークスペースの固定を示すことがあります。これらの異なる条件を一律の再試行ループで処理しないでください。

関連ガイド

• APIでファイルを一覧表示
• APIエラーへの対応