REST APIでファイルをダウンロードする

保存されたファイルはREST APIで2回のリクエストによりダウンロードします。GET /api/files/{file_id}/download-urlから認可された一時URLを取得し、そのURLを使ってストレージからファイルを取得してください。発行時の応答はJSONであり、ファイルのバイトやリダイレクトではありません。URLを持つ人は有効期限内に認可されたオブジェクトを取得できるため、URLは非公開にしてください。

ダウンロードできるファイルを選ぶ

REST APIが有効な読み取り専用またはフルアクセスのAPIキーを使用してください。必要に応じてプロフィール → API（APIキー） → API：APIキーを作成で作成し、一度だけ表示される画面を閉じる前にトークン全体を保存してください。ワークスペースの固定先によってキーが制限される場合があります。フォルダーに固定された通常のキーはこのプロトコルでは拒否されます。

GET /api/files?workspace_id=WORKSPACE_IDでファイルIDを探してください。特定のフォルダー内を探す場合はfolder_idを追加します。選択するファイルは、所属するワークスペース内にあり、メンバーの範囲制限内で、表示可能かつダウンロードが許可されている必要があります。ロールにはファイルページへのアクセスとdownload_filesが必要です。プレビューできるだけでは不十分です。

手順：URLの発行と使用

DOSYA_API_KEYを非公開で設定し、以下のファイルのプレースホルダーを置き換えてください。このBashの例はcurlとPython 3を使用し、発行された情報を非公開のファイル権限で保存し、署名済みURLを出力しません。

set -e
umask 077
DOSYA_FILE_ID='REPLACE_WITH_FILE_ID'
DOSYA_GRANT_FILE=$(mktemp)
curl --fail-with-body --silent --show-error \
  "https://api.dosya.dev/api/files/$DOSYA_FILE_ID/download-url" \
  -H "Authorization: Bearer $DOSYA_API_KEY" \
  -o "$DOSYA_GRANT_FILE"
python3 - "$DOSYA_GRANT_FILE" <<'PYTHON'
import json, sys
from urllib.request import urlopen
grant = json.load(open(sys.argv[1]))
with urlopen(grant["url"]) as response, open("dosya-download.bin", "wb") as output:
    while chunk := response.read(1024 * 1024):
        output.write(chunk)
from pathlib import Path
actual = Path("dosya-download.bin").stat().st_size
if actual != grant["size"]:
    raise SystemExit(f"Size mismatch: received {actual}, expected {grant['size']}")
print("Downloaded", grant["name"], "bytes:", actual, "region:", grant["region"])
PYTHON
rm -f "$DOSYA_GRANT_FILE"

発行に失敗した場合は古いJSONファイルを読み込まずに停止してください。Pythonの例にはPython 3.8以降が必要です。dosya-download.binに書き込むため、以前のダウンロードを保持する場合は再実行前に別のローカル出力ファイル名を選んでください。

成功を示す200の発行応答には、必要なフィールドであるurl、バイト単位のsize、name、regionが含まれます。このルートにはok: trueは含まれません。urlは署名パラメーターをすべて含めて返されたまま取得し、ストレージへのリクエストにdosyaのAPIキーを付けないでください。発行時に権限が確認され、ストレージではURLの署名が使用されます。

ダウンロードしたサイズをsizeと照合してください。より確実に整合性を検証するには、ローカルのSHA-256を信頼できる元のダイジェストと比較してください。ファイル名や長さの一致だけでは内容が同一であることを証明できません。選択したファイルとバージョンの識別情報を検証結果とともに保存してください。

URLの有効期間、バージョン、使用量

クエリパラメーター	対応する動作
ttl	秒単位の整数。初期値は**300秒（5分）です。正の値の上限は3,600秒（1時間）**です。値がない場合、無効な場合、または正でない場合は300が使われます。
version	正のバージョン番号で保存済みのリビジョンを選びます。現在のファイルには省略してください。有効な番号でも存在しないバージョンには404 Version not foundが返ります。
region	想定するリージョンを任意で指定します。一致しない場合は404 File not foundが返り、ファイルを別の場所にリダイレクトしません。
ut	必要な場合に指定する、このユーザーの完全ロックされたファイル用の有効なロック解除トークンです。ロールや表示の確認は省略されません。

たとえば/api/files/FILE_ID/download-url?version=1&ttl=3600は1時間有効なURLで最初のバージョンをリクエストします。編集したことのないファイルの初期バージョンも、以前のバージョンの項目がなくても取得できます。正の整数を明示的に使用してください。不正な形式のversionではリビジョンを確実に選択できません。

有効期限は最初のGETだけでなく、後続のRangeリクエストにも影響します。長時間動作するダウンローダーやメディアプレーヤーには、1時間の上限内で十分なTTLをリクエストしてください。期限切れのURLをストレージが拒否した場合は、引き続き権限のある認証情報で新たに発行してください。古いURLの有効期限パラメーターを編集すると署名が無効になります。

ファイルを取得しなかった場合や一部の範囲だけを読み取った場合でも、該当する認証情報やプランのダウンロードバイト数は、発行時に選択したバージョンの全サイズ分が消費されます。そのため、繰り返し発行すると使用枠を複数回消費することがあります。チャンクごとに新しいURLをリクエストせず、対象のジョブ内で期限内の発行情報を非公開でキャッシュしてください。ダウンロードの監査イベントは発行を記録するもので、受信者がすべてのバイトを受け取った証拠ではありません。

ダウンロードできない場合の確認

ステータスとエラー	意味と対処
401、Invalid or expired API key	トークンがない、無効化された、または期限切れの場合は交換してから再発行してください。
403、Access denied	ファイルのワークスペースのメンバーではありません。
403、This file is outside the folder you're confined to	メンバーのフォルダー範囲にこのファイルが含まれていません。
403、You don't have download permission	管理者にダウンロード操作の権限を依頼してください。プレビュー権限では代用できません。
403、This file is view-only and cannot be downloaded	閲覧専用ロックを尊重してください。このエンドポイントからはダウンロード用のバイトを取得できません。
403、This file is locked. Enter the lock password to access it.	正規のロック解除手順で有効なファイル解除トークンを取得し、utを送信してください。
403、Invalid or expired unlock token. Please re-enter the password.	正規のロック解除をやり直してください。古いトークンは無効です。
404、File not found	IDと任意のリージョンを確認してください。非表示のコンテンツやロックされた上位フォルダーには、存在しない場合と同じ応答が意図的に返ります。
429、Retry-After	指定された秒数だけ待ってください。キーのリクエストまたはダウンロードバイト数の制限により、URLの発行前に拒否される場合があります。
500、Download failed: …	URLに署名できませんでした。機密情報を除いたエラーを保存し、後でもう一度お試しください。ストレージの詳細や認証情報をログで公開しないでください。

完全ロックされたファイルはPOST /api/files/{file_id}/unlockとJSONの{"password":"REPLACE_WITH_LOCK_PASSWORD"}で解除できます。返されるunlock_tokenは1時間有効で、呼び出し元に属し、ロック自体は解除しません。このPOSTには完全なスコープが必要です。読み取り専用のRESTキーでは呼び出せません。パスワードを入力するこの手順には、別途認可されたフルアクセスの認証情報またはサインイン済みのアプリを使用し、トークンを非公開にしてください。パスワードの推測を繰り返さないでください。ロック解除には回数制限があります。

URLの署名前に、ワークスペースのメンバー資格、ファイルページへのアクセス、範囲制限、ダウンロード権限、非表示状態と上位のロック、ファイル自体のロック、選択したバージョン、バイト数の使用枠が確認されます。発行情報が期限切れになっても保存されたファイルは消えません。また、ダウンロードしても共有リンクは作成されず、選択した受信者への通知も行われません。

ダウンロードしたコピーとURLを保護する

APIキーを無効化すると新たな認証済みURLは発行できなくなりますが、発行済みのストレージURLは無効になりません。短いTTLの期限切れを待ってください。署名済みURLをスクリーンショット、問題の報告、クエリログ、分析データに含めないでください。機密情報がある状態でシェルのトレースを有効にしてコマンドを実行しないでください。

ローカルファイルは管理下にある別のコピーです。クラウドのファイルを削除または変更しても、このダウンロード済みコピーは削除されません。使用後は一時的な発行情報のファイルを削除し、ダウンロードしたデータは内容に必要な権限で保存してください。

期待される結果

ローカルの出力には選択したファイルのバージョンが保存され、サイズは発行時の応答と一致します。保存されたファイルはワークスペースに残ります。一時URLでアクセスできるのは有効期間内だけですが、ダウンロードしたコピーはその期間とは関係なく利用できます。

関連ガイド

• REST API認証とワークスペース一覧
• ダウンロードURLの発行に使う認証情報を管理する