S3クライアントでオブジェクトをダウンロードする

dosyaは各ワークスペースをS3互換バケットとして公開します。エンドポイントはhttps://api.dosya.dev/s3、署名リージョンはus-east-1、バケット名は連携 → S3に表示されるワークスペースIDです。

認証情報と権限を用意する

ワークスペースのロールには**「S3」ゲートウェイ**、ファイルアクセス、ダウンロードの権限が必要です。S3自体が拒否されている場合、設定ページにこのロールではS3ゲートウェイを使用できませんと表示されます。オーナーまたは管理者がロールを変更する必要があります。

ダウンロードだけに使う認証情報の場合、プロフィール → API（APIキー）で読み取り専用キーを作成し、プロトコルを**「S3」ゲートウェイ**に制限してください。そのAPIキーにS3認証情報を紐付けます。dosyaはシークレットアクセスキーを1回だけ表示するため、作成時に安全な認証情報ストアにコピーしてください。

ワークスペースの固定により、認証情報を対象のバケットに制限できます。フォルダーアンカーも指定できます。そのフォルダーがS3上の/となり、オブジェクトキーは起点からの相対パスになるため、その上位や隣のパスにはアクセスできません。

このダウンロード用に新しい専用AWS CLIプロファイルを選んでください。まずaws configure list-profilesを確認し、dosya-download-testがすでに存在する場合は、以下のすべてのコマンドで別の未使用の名前を一貫して使ってください。

表示されたS3アクセスIDとシークレットを対話形式で入力してください：

aws configure --profile dosya-download-test

プロンプトでS3アクセスID、対応するシークレット、us-east-1、jsonを入力してください。シークレットをコマンドの引数に含めたり、録画中のターミナルを使ったりしないでください。プロンプトではシェルのコマンド履歴に残りませんが、入力した認証情報が隠されるとは限りません。AWS CLIは通常、認証情報を~/.aws/credentials、設定を~/.aws/configに保存します。これらはローカルファイルであり、暗号化されたパスワード保管庫ではありません。非公開にし、共有の記録やリポジトリに含めないでください。

このプロファイルだけにパス形式のアドレス指定を設定してください：

aws configure set s3.addressing_style path --profile dosya-download-test

この手順で既定のプロファイルを使用または変更しないよう、すべてのリモートコマンドに--profile dosya-download-testを指定してください。

手順

1. 連携 → S3からワークスペースIDをコピーし、範囲を絞ったプレフィックスを一覧表示して正確なオブジェクトキーを特定してください：

   aws --profile dosya-download-test --endpoint-url https://api.dosya.dev/s3 --region us-east-1 \
     s3api list-objects-v2 --bucket WORKSPACE_ID --prefix 'path/to/'

2. 内容をダウンロードせずにS3オブジェクトのContentLengthを確認してください：

   aws --profile dosya-download-test --endpoint-url https://api.dosya.dev/s3 --region us-east-1 \
     s3api head-object --bucket WORKSPACE_ID --key 'path/to/object.bin'

3. 新しいローカルファイル名を選ぶか、現在のパスをバックアップしてください。aws s3 cpはコマンドに指定したローカル出力先を置き換えることがあります。

4. オブジェクトをダウンロードしてください：

   aws --profile dosya-download-test --endpoint-url https://api.dosya.dev/s3 --region us-east-1 \
     s3 cp 's3://WORKSPACE_ID/path/to/object.bin' './object.bin'

5. ローカルのバイト数をhead-objectのContentLengthと比較してください。元のデータに別途信頼できるチェックサムがある場合は、ローカルで同じアルゴリズムを使って計算し、比較します。すべてのS3 ETagが移植可能なコンテンツハッシュであるとは限りません。

トラブルシューティング

• AccessDenied: API key scope 'upload' cannot download filesはキーがアップロード専用であることを示します。代わりに読み取り専用またはフルアクセスのキーを発行してください。
• AccessDenied: Access deniedはロールに一般的なファイルアクセス権限がないことを示します。AccessDenied: Download not allowedは別のダウンロード権限に関するものです。
• NoSuchBucketは通常、ワークスペースIDが誤っている、キーが別の場所に固定されている、またはユーザーがそのワークスペースに所属していないことを示します。
• NoSuchKeyは相対パスが表示可能な有効なファイルに解決されないことを示します。非表示のコンテンツも存在しないものとして扱われます。フォルダーを起点とするキーでは、起点より上のパス部分をすべて省く必要があります。
• AccessDenied: Object is lockedはファイルまたはその上位フォルダーが完全にロックされていることを示します。Webアプリで個人がロックを解除しても、S3リクエストによるダウンロードは許可されません。
• SignatureDoesNotMatchの場合はアクセスキーのペア、エンドポイント、署名リージョンus-east-1を確認してください。シークレットは1回しか表示されないため、それだけを再生成することはできません。紛失した場合は新しいS3認証情報のペアを紐付けてください。
• 満たせないバイト範囲にはHTTP 416とContent-Range: bytes */SIZEが返されます。現在のオブジェクトサイズを確認し、古い範囲を指定せずに再試行してください。

dosyaに対するダウンロードは読み取り専用です。クラウド上のオブジェクトは削除、移動、変更されません。既存のローカル出力パスの置き換えはローカルでの変更であり、別のローカルコピーがなければdosyaから復元できません。

期待される結果

AWS CLIが正常終了し、ローカルファイルのサイズがS3のContentLengthと一致します。別途わかっているチェックサムがあれば、それも一致します。元のオブジェクトは同じdosyaワークスペースのパスに残り、クラウド側では変更されません。

関連ガイド

• S3クライアントを接続する
• S3の権限を制限する