クラウドストレージREST APIクイックスタート

https://api.dosya.dev/apiのクラウドストレージREST APIでワークスペースを一覧表示し、対象を選んでそのファイルを読み取ります。このクイックスタートでは保存済みファイルを変更せず、認証済みの読み取りリクエストを行います。APIは/apiを使用します。/v1や/v2を追加しないでください。

テスト用の認証情報を作成する

1. プロフィール → APIキーにサインインし、API：APIキーを作成を選択してください。
2. 用途に分かりやすい名前を入力し、何ができますか？で読み取り専用を選択してください。
3. 制限と有効期限を展開してください。プロトコルで選択したもののみを選び、REST APIを選択してください。この連携を1つのワークスペースに限定する場合は対象のワークスペースを選択してください。通常のフォルダーに制限されたキーはRESTで拒否されるため、フォルダーは設定しないでください。
4. 30日後に有効期限切れを選んで概要を確認し、キーを生成を選択してください。「キー名」の準備ができました。ダイアログから完了を選択する前に完全なdos_トークンをコピーしてください。その後はキー一覧から確認できません。

無料アカウントはAPIキーを3個まで保持できます。他のプランのアカウント全体の上限は20個です。期限切れの既存キーもこの合計に含まれます。キーの権限はアカウントのアクセスを制限するもので、持っていないワークスペースのメンバーシップやロール権限を付与するものではありません。

手順：最初のリクエストを送る

例を実行するにはシェル、curl、Python 3が必要です。DOSYA_API_KEYはシークレットマネージャーまたは対話式の入力で設定し、保存するコマンド内で変数を実際のトークンに置き換えないでください。Bashでの対話式入力例を示します。

read -r -s -p 'API key: ' DOSYA_API_KEY
printf '\n'
export DOSYA_API_KEY
curl --fail-with-body --silent --show-error \
  'https://api.dosya.dev/api/workspaces' \
  -H "Authorization: Bearer $DOSYA_API_KEY" \
  -o workspaces.json
python3 -c 'import json; d=json.load(open("workspaces.json")); print([(w["id"],w["name"]) for w in d["workspaces"]])'

成功したリクエストはok: trueとworkspaces配列を含むHTTP 200を返します。表示名ではなく返されたワークスペースIDを使用してください。ワークスペースに限定されたキーから見えるのはそのワークスペースだけです。空の配列はアカウント全体にワークスペースがない証拠ではありません。キーの範囲と現在のメンバーシップを確認してください。

1つのワークスペースのルートフォルダーからファイルを読み取ります。

DOSYA_WORKSPACE_ID='REPLACE_WITH_RETURNED_WORKSPACE_ID'
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' \
  -o files.json
python3 -m json.tool files.json

ファイル一覧は既定で各ページ100項目で、per_pageは10〜500を受け付けます。既知のサブフォルダーを一覧するにはfolder_idを指定してください。ここで返されるファイルIDはメタデータとダウンロードのルートで使う値です。ワークスペースのロールにはファイルページへのアクセスが必要です。非表示のコンテンツやフォルダーの制限によって一覧が絞られる場合があります。

書き込みを追加する前に失敗を確認する

レスポンス	対応
401、Invalid or expired API key	完全なトークンを使い、有効期限と失効を確認し、正確なAuthorization: Bearer …ヘッダーを維持してください。
403、This API key is not permitted to use the api surface	認証情報のプロトコル選択にREST APIを含めてください。
403、This API key is anchored at a folder and can only be used over WebDAV or the S3 gateway	フォルダー制限のない、ワークスペースに限定したRESTキーを生成してください。
403、This API key is restricted to specific source addresses	許可されたアドレスから送信してください。転送ヘッダーを偽装しないでください。
403、This API key is being used outside its allowed hours	選択したタイムゾーン、曜日、週間の時間帯を確認してください。
Retry-Afterを伴う429	指定された秒数を待ち、連続して再試行せず同時リクエストを減らしてください。
503、Service temporarily unavailable	認証情報を維持し、レスポンスの5秒の待機後に再試行してください。この認証情報の検索失敗はキーの交換理由にはなりません。

認証後、キーのリクエスト数を消費する前にプロトコル、アドレス・時間、フォルダー制限、権限、ワークスペース限定が確認されます。読み取り専用キーでは一覧表示とダウンロードができますが、書き込みは権限、メソッド、パスを示すメッセージとともに拒否されます。フルアクセスキーを使い、大切なデータに対してこの境界をテストしないでください。

HTTPステータスとJSONのerrorで失敗を特定します。多くのJSONレスポンスにはokがありますが、ダウンロードURLエンドポイントはurl、size、name、regionを返し、ok項目は含みません。共通の形式を決めつけず、実際のレスポンスを確認してください。認可ヘッダーを隠したうえでステータス、エラー、提供されたリクエスト識別子を保持してください。

期待される結果と安全なテスト後の処理

返されたワークスペースIDとファイル名をサインイン済みアプリと比較してください。一覧表示はアップロード、削除、共有リンクの作成を行わず、このリクエストによって受信者にファイルが送られることもありません。保持が許可されたメタデータだけを保存してください。

テストが終わったらプロフィール → API（APIキー）に戻り、テストキーを展開して招待を取り消すを選択し、もう一度招待を取り消すで確定してください。失効は元に戻せず、その認証情報を使用する連携は認証できなくなります。キーの作成、一覧表示、IDによる削除にはサインイン済みセッションが必要なため、Bearerキーで別のキーを発行・管理することはできません。本番環境では読み取り、アップロード、管理の作業ごとに別の認証情報を使用し、書き込みの結果が不明な場合は再実行前に確認してください。

関連ガイド

• APIキーを作成・管理する
• ファイルをアップロードしマルチパート転送を再開する
• 一時的な署名付きURLでダウンロードする
• Webhook受信先を登録・検証する