REST APIでファイルを安全に移動する

PUT /api/files/:id/moveはファイルのIDやバージョンを変えずに親を変更します。移動先がフォルダーの場合はfolder_idにそのIDを、ワークスペースのルートの場合はnullを指定してください。同じアトミックなリクエストで名前も変更する場合に限りnameを追加します。

始める前に

• フルアクセスのREST APIキーを使用してください。読み取り専用およびアップロード専用キーではファイルを移動できません。
• ワークスペースのロールにupload_filesが必要です。nameも指定するリクエストにはrename_filesが必要です。
• ファイルID、現在のフォルダー、移動先フォルダーを記録してください。自動処理のテストには不要になってもよいファイルを選んでください。
• 移動先は同じワークスペースに属し、呼び出し元が参照できる必要があります。

手順

1. まずファイルと移動先を読み取ってください。変更操作を送る前にファイルID、現在の親、正確な移動先IDを記録します。
2. 移動先を指定するJSONを用意してください。例：{"folder_id":"folder_destination"}。ルートには{"folder_id":null}を使用し、移動と名前の変更を同時に行う場合は"name":"renamed.pdf"を追加してください。
3. PUT /api/files/file_id/moveをAuthorization: Bearer $DOSYA_API_KEYとContent-Type: application/jsonとともに送信してください。レスポンスが失われた場合、確認せずに再試行しないでください。
4. HTTP 200を確認し、{ "ok": true, "name": "…" }を読み取ります。400は既にそのフォルダーにあることを示す場合があり、403は権限またはロックによる拒否、404は利用できない対象、409は同じフォルダー内の名前の競合を示します。
5. GET /api/files/file_idを送信し、同じIDに意図したfolder_idと、指定した場合は新しい名前が表示されることを確認してください。変更操作でX-D1-Bookmarkが返された場合は引き継ぎます。ただしD1を使う読み取りの順序付けに限られ、ファイルのコンテンツのメタデータはワークスペースリポジトリから取得される場合があります。
6. 後続の処理がファイルがどのフォルダーに属するかに依存する場合は、移動元と移動先の両方の親を一覧表示してください。元の親にIDがなく、移動先にIDがあることを確認してから続行します。

期待される結果

APIはok: trueとともに200を返し、ルート固有のメタデータ読み取りでは元のファイルIDが選択した親の下に表示されます。同時に名前を変更した場合、確認結果に指定した名前が表示されます。

トラブルシューティング

409が返る場合 別のnameを選ぶか、移動先の既存項目との競合を解消してから再試行してください。

403が返る場合 upload_filesを確認し、同時に名前を変更する場合はrename_filesを追加して、ロック状態を確認してください。APIキーのスコープを変更してもワークスペースのロールやロックは回避できません。

レスポンスが失われた場合 別の変更操作を送る前にファイルを読み取ってください。移動ルートに冪等性キーはありません。移動先を確認できれば最初のリクエストは既に確定しています。

関連ガイド

• フォルダー操作を使用する
• REST APIクイックスタート