S3互換クライアントを接続する

パス形式のアドレス指定、リージョンus-east-1、dosya APIキーに紐付けたS3認証情報のペアを使って、S3クライアントをhttps://api.dosya.dev/s3に接続します。バケットには表示名ではなくワークスペースIDを使います。ゲートウェイから通常のワークスペースファイルにアクセスできます。AWSのバケット管理や不変性の機能はサポート対象外です。

始める前に

対象のワークスペースを選択し、連携 → S3を開いてください。接続設定に現在のワークスペースのEndpoint、Region、Bucketが表示されます。ページにこのロールではS3ゲートウェイを使用できませんと表示される場合は、クライアントを設定する前にオーナーまたは管理者にS3アクセスを依頼してください。一覧表示、アップロード、ダウンロード、削除のロール権限はそれぞれ別に適用されます。

無料プランでもストレージとダウンロードの許容量内でS3を使えます。APIキーの作成数は、実質的に無料のユーザーは3個、全体では20個が上限です。明示的なキーまたはロールの制限により、ファイルサイズ、日次のダウンロードバイト数、毎分リクエスト数、同時転送数がさらに制限されることがあります。このプロトコルはプランのリクエスト数と同時実行数の上限の対象外ですが、明示的な制限や送信量の制限は適用されます。

手順：適切な認証情報のペアを生成する

1. プロフィール → API（APIキー） → API：APIキーを作成を開き、用途にラベルを入力してください。この一覧表示、アップロード、ダウンロードのテストにはフルアクセスを選択します。読み取り専用では閲覧とダウンロードはできますがアップロードは拒否され、アップロードのみではオブジェクトの一覧表示もダウンロードもできません。
2. 制限と有効期限で、プロトコルに選択したもののみを選択し、「S3」ゲートウェイを選んで対象のワークスペースを固定してください。短い有効期限を選び、このクライアントに適したアドレス、利用時間、使用量の制御を確認します。**フォルダーを選択…**で選択したフォルダーをクライアントのルートにできます。
3. キーを生成を選択してください。dos_… APIキーも必要な場合は全体を保存します。作成時にのみ表示されます。S3クライアントにはこの値ではなく別のペアが必要です。
4. 保存したキーの行を展開し、S3認証情報で有効化を選択してください。S3認証情報ダイアログで、完了前にアクセスキーID、シークレットアクセスキー、エンドポイント、リージョンをコピーします。アクセスIDはDOSYAで始まり、生成されたシークレットは40文字です。クライアントの保護された認証情報保存機能に保管してください。

スクリーンショットはAPIキーの制限フォームであり、後に表示されるS3シークレットのダイアログではありません。S3の有効・表示ではアクセスIDを再表示できますが、シークレットは**（シークレットキーは取得できません。ローテーションするにはキーを無効化して再作成してください）に置き換わります。同じキーを2回有効にしようとするとS3 credentials already exist for this API key. Delete and recreate to regenerate.**と表示され拒否されます。シークレットを紛失した場合は新しいキーとペアが必要です。依存するクライアントを更新してから古いキーを取り消してください。取り消しは元に戻せず、そのキーとS3ペアの両方が拒否されます。保存済みファイルは削除されません。

手順：接続設定を入力する

クライアントの項目	dosyaの値
S3互換エンドポイント / サービスURL	https://api.dosya.dev/s3
リージョン	us-east-1
署名 / 認証	AWS Signature Version 4
アクセスキー	生成されたDOSYA…アクセスキーID
シークレットキー	対応するS3シークレット。dos_… APIキーではありません
アドレス指定	パス形式（AWS SDK for JavaScriptではforcePathStyle: true）
バケット	連携 → S3からコピーした正確なワークスペースID。例：ws_example

ホスト名にバケットを含めないでください。キーchecks/sample.txtのオブジェクトは/s3/ws_example/checks/sample.txtにあり、ファイルのchecks内にsample.txtとして表示されます。S3はWebDAVのAllコレクションを追加しません。All/sample.txtは通常のフォルダーを指します。ワークスペースの名前が変更されていてもIDは正確にコピーしてください。

フォルダーに制限されたキーはワークスペースのバケットIDを保持しますが、すべてのオブジェクトキーは起点からの相対パスとして解決されます。起点がProjectsの場合、checks/sample.txtでProjects/checks/sample.txtにアクセスできます。Projectsを再度先頭に付けないでください。ワークスペースのメンバーに対する制限とキーの制限の両方が適用されます。キーはメンバーより広いサブツリー、別の固定されたワークスペース、ゴミ箱内の起点にはアクセスできません。キーのオーナーまたはそのロールから非表示の項目は、非表示項目の閲覧を許可するhide_filesをロールが持たない限り除外されます。キー自体が表示ルールを回避することはありません。

手順：サンプル転送を確認する

1. 選択したバケットを一覧表示してください。できればIDを直接指定します。バケットの検出結果は許可されたワークスペースに絞られることがあります。検出できただけではアップロード権限の証明にはなりません。
2. 許可された使い捨てのプレフィックス内に、checks/s3-first-sample.txtなどの新しいサンプル名を選択してください。無害なデータをアップロードし、クライアントの操作結果を待ちます。ロールにフォルダー作成権限があれば、新しい入れ子のパスによって不足するフォルダーが作成されることがあります。
3. dosyaのファイルを更新し、実際のワークスペースまたは起点のパス、名前、バイト数を確認してください。そのキーを別のローカルファイルにダウンロードし、内容またはローカルで計算したSHA-256を比較します。
4. checks/s3-first-sample.txtを確認用に残すか、クライアントからそのオブジェクトを指定して削除するか決めてください。このテスト接続の使用を終了するには、プロフィール → API（APIキー）の専用行で招待を取り消すを選択します。ローカルプロファイルだけを削除しても、クラウドのサンプルとキーは両方残ります。

PutObjectは書き込み後にETagとHTTP 200を返します。GETはオブジェクトのバイトまたは範囲レスポンスを返し、一覧はページあたり最大1,000件のXMLです。クライアントは継続トークンをたどる必要があります。ETagだけでは汎用的なファイルハッシュにはなりません。マルチパートオブジェクトはマルチパートETagを使います。これらの操作では公開共有URLは作成されません。認証情報を渡さずに受信者にアクセスを許可するにはdosyaの共有を使ってください。

対応する操作と影響

ルーターはバケットとオブジェクトの一覧表示、HEAD、アップロード、ダウンロード、コピー、削除、一括削除、ディレクトリマーカー、およびマルチパートの開始、パートのアップロード、パートのコピー、一覧表示、完了、中止を実装しています。一括削除は最大1,000キーを受け付け、キーごとのエラーを報告します。マルチパートのパート番号は1〜10,000で、各パートの上限は5 GiBです。実際のオブジェクトやストレージの上限はもっと小さい場合があります。マルチパート転送が失敗すると未完了のアップロードが残ることがあります。ローカルでキャンセルしただけでパートが削除されたと考えず、クライアントの中止操作を使ってください。

バケットは既存のワークスペースに対応します。アクセス可能な既存ワークスペースに対するCreateBucketリクエストは互換性確認として200を返すことがありますが、ワークスペースは作成できません。バケット削除、AWS IAM/ACL、ライフサイクルルール、設定可能なCORS、レプリケーション、AWS S3バージョニング、Object Lock/保持/リーガルホールドはこのゲートウェイでは利用できません。設定の書き込みは501 NotImplementedを返し、一部の読み取りは空の設定または対象がないことを示すエラーを返します。S3の不変性やリーガルホールドの保証を必要とするソフトウェアにはこのエンドポイントを選択しないでください。

同じファイルパスへのアップロードでは、AWSのバージョンIDではなく別のdosyaファイルバージョンが作成されます。ワークスペースの既定の履歴上限は10バージョンです。正の上限が設定されている場合は超過した履歴が削除され、無料オーナーの古いバージョンには7日間の保持処理が適用されます。復元用に元ファイルを保管してください。削除可能なオブジェクトの削除は、すでに存在しない場合も204を返します。存在するファイルはゴミ箱に移動し、共有リンクは取り消されます。ゴミ箱は完全削除までストレージを使用し、オーナーに適用される保持期間は無料で7日、それ以外は30日です。完全削除されたデータや取り消された認証情報はクライアントを再接続しても復元できません。

トラブルシューティング

結果	確認または対処
InvalidAccessKeyId / The access key ID does not exist	S3アクセスIDを確認してください。期限切れ、取り消し済み、無効なキーは拒否されます。
SignatureDoesNotMatch / The request signature does not match	対応するシークレットと署名された正確なエンドポイントおよびパスを確認し、古いリクエストを破棄してクライアントに再署名させてください。
AccessDenied / This API key is not permitted to use the S3 gateway	選択したプロトコルにS3を含むキーを作成してください。
This API key is pinned to a different workspace	キーの固定先と一致するコピー済みバケットIDを使ってください。
This role is not permitted to use the S3 gateway	ワークスペースのオーナーまたは管理者がロールのS3アクセスを確認する必要があります。
Upload not allowed、Creating folders is not allowed、Object is locked	要求した操作がロールの権限と出力先の状態に合っているか確認してください。
EntityTooLargeまたはQuotaExceeded	再試行前にファイルサイズ、ワークスペースのストレージ、明示的なキーやロールの制限を確認してください。
429 XML SlowDown	キーまたはロールの使用制限によりリクエストや転送が拒否されました。個別のMessageを読み、Retry-Afterがあれば従ってください。同時実行数による拒否では並列数を減らします。バイトの許容量はリセットか権限のある制限変更が必要です。
429 JSON {"ok":false,"error":"Too many requests"}	別のフロントドア制限に達しました。上限はユーザーごとに毎分600件、IPごとに毎分1,200件です。Retry-Afterまで待ち、リクエスト頻度を減らし、同じユーザーやIPを共有するジョブを時間差で実行してください。

認証はプロトコル、キーの条件、使用量、ワークスペースの固定、メンバーや起点、ロールの各制限より先に行われます。そのため、1つの拒否を解消すると別の拒否が現れることがあります。別の操作の失敗を隠すためだけに制限付きキーの範囲を広げないでください。

期待される結果

クライアントがSigV4のパス形式リクエストでコピーしたワークスペースのバケットに接続します。サンプルの保存先がファイルに表示され、別途ダウンロードしたバイトが元のデータと一致します。この確認なしに接続名が保存された、または認証が成功しただけでは設定は完了していません。

関連ガイド

• 独立したプロファイルでAWS CLIサンプルを実行する
• 署名とリクエスト時刻のエラーから復旧する
• キーのプロトコル制限を設定する