SFTPクライアントを接続

SFTP over SSHでsftp.dosya.devのポート2222に接続してください。ユーザー名はdosyaアカウントのメールアドレス、パスワードはAPIキー全体です。このサービスはファイル操作のみを提供します。FTP、FTPS、対話型SSHシェルではありません。

このクライアント用の認証情報を作成

Webアプリでワークスペースを選び、連携 → SFTPを開いてください。このロールではSFTPを使用できませんが表示された場合は、クライアントのプロファイルを作成する前にワークスペースのオーナーまたは管理者にアクセスを依頼してください。SFTPへのアクセスとアップロード、ダウンロード、削除の権限は、ロールごとに別々に決まります。

プロフィール → API（APIキー） → API：APIキーを作成を開いてください。用途でこのコンピューター用のキーに名前を付け、一覧表示とダウンロードには読み取り専用、アップロードと管理にはフルアクセスを選びます。制限と有効期限 → アクセス範囲はどこまでですか？ → プロトコル → 選択したもののみを選択してSFTPにチェックを入れ、適切なワークスペースの固定先を選びます。キーを生成し、一度だけ表示されるシークレットを安全に保存してください。

SFTPの認証情報には**フォルダーを選択…**を選ばないでください。フォルダーに固定されたキーはこのプロトコルでは拒否されます。ワークスペースに固定されたキーは使用できます。アップロードのみのキーでは、この接続手順に必要な一覧リクエストを実行できません。許可IPの制限も避けてください。ゲートウェイが代理でAPIに接続するため、APIは元のアドレスを確認できず、IP制限付きのキーを拒否します。有効期限、利用可能時間、適用される使用制限は引き続き有効です。

接続を設定

クライアントの設定	dosyaの値
プロトコル	SFTP / SSH File Transfer Protocol
ホスト	sftp.dosya.dev
ポート	2222
ユーザー名	キーのオーナーのアカウントのメールアドレス。大文字と小文字も一致させます
認証	パスワード
パスワード	dos_… APIキー全体
初期フォルダー	ワークスペース一覧には/

サーバーはパスワード認証に対応しており、SSH公開鍵によるサインインには対応していません。メールアドレスはワークスペース名ではありません。ここではアカウントのパスワードによるサインインもできません。キーはクライアントのプライベートな認証情報ストアにのみ保存してください。

OpenSSHでは、SSHのユーザーオプションを使ってメールアドレスをホスト名と分けて指定してください：

sftp -P 2222 -o User=you@example.com -o PreferredAuthentications=password -o PubkeyAuthentication=no sftp.dosya.dev

メールアドレスの例を自身のものに置き換えてください。APIキーはパスワードの入力画面にのみ入力し、ターミナルのコマンド、保存したスクリプト、シェル履歴にシークレットを残さないでください。-PはSFTPポートを指定します。小文字の-pは意味が異なります。クライアントをコンピューターにインストールしておく必要があります。

認証前にホストを確認

初回接続時にSSHホスト鍵のフィンガープリントが表示され、信頼するか確認されることがあります。ホスト鍵はサーバーを、APIキーはアカウントを識別します。受け入れる前に、表示されたホスト名、ポート、鍵の種類、フィンガープリントを、dosyaサポートまたは管理者から別の経路で取得した信頼できる値と比較してください。このガイドには認証済みの本番環境のフィンガープリントはありません。ssh-keyscanだけで鍵を取得しても、相手の身元は証明できません。

**REMOTE HOST IDENTIFICATION HAS CHANGED!**が表示されたら操作を止め、既知のホストのエントリを変更する前に正当な変更か確認してください。通常の対処としてStrictHostKeyChecking=noを設定しないでください。保存された信頼の記録はクライアントのパスワードとは別です。APIキーをローテーションしてもホスト鍵の不一致は解消しません。

手順：移動して転送を確認

1. 接続し、pwdとlsを実行してください。/には、このキーとロールで利用できるワークスペースが一覧表示されます。WebDAVのAllやスマートビューのコレクションは表示されません。
2. cd "My Workspace"の例を一覧にある名前に置き換えて実行してください。ワークスペースのスラッグも使用できます。lsを再度実行すると、そのワークスペースの実際のフォルダーとファイルを確認できます。
3. 既存の保存先フォルダーに移動するか、許可されていればmkdir "sftp-check"で使い捨てのフォルダーを作成してください。SFTPのルートからワークスペースを作成することはできません。
4. put sample.txt sftp-check-20261014.txtで、一意の名前を付けた空でないローカルのサンプルをアップロードしてください。完了と最終的なクローズ応答を待ちます。ゲートウェイはファイルのクローズ時にアップロードを確定するため、進行状況が100%になってもクラウド側では完了前の場合があります。
5. dosyaのファイルで同じワークスペースとフォルダーを開き、名前とサイズを確認してください。get sftp-check-20261014.txt ./sftp-check-downloaded.txtでダウンロードし、バイトまたはSHA-256を元のファイルと比較します。
6. 再接続して一覧を再表示し、保存場所を確認してください。別のクライアントによる変更の反映は短時間遅れることがあります。フォルダーキャッシュの標準値は10秒で、見つからなかった項目は再確認されます。

読み取り専用のユーザーは、代わりにgetで既知のリモートサンプルを確認できます。通常のダウンロードではオフセット読み取りを実行できます。64 MiB以上の大きな読み取りでは範囲を限定して取得するため、最初のバイトを受け取るまでの時間や転送速度が異なる場合があります。比較に使えるサーバー側のハッシュコマンドやシェルセッションはありません。ローカルの元ファイルとダウンロードしたコピーでハッシュを計算してください。

期待される結果

ワークスペースのパスに目的のファイルが一覧表示され、ダウンロードが完了したサンプルが元のファイルと一致します。アップロードしたサンプルは、クラウドへの確定が成功して初めてdosyaのファイル内の通常のファイルになります。公開共有リンクではありません。

対応する操作と制限

ゲートウェイは一覧表示/stat、get、put、mkdir、名前変更/移動、rm、rmdirに対応します。chmod/chownの属性リクエストは受け付けますが、dosyaのワークスペース権限は変更しません。シンボリックリンクとSSHシェル/execには対応していません。シェルを確認するクライアントは、SFTP専用モードで続行する必要があります。

同梱のサーバー設定ではアップロードの上限は**352 MiB (369,098,752 bytes)**です。デプロイ先でこれより小さい上限を設定することもでき、エラーには有効なMB値が表示されます。この上限はプランのクラウドストレージ総容量とは別です。ワークスペースのサイズや拡張子のポリシー、残りのストレージ、明示的な認証情報やロールの使用制限により、より小さいファイルも拒否されることがあります。無料アカウントも有料アカウントもSFTPを利用できます。このプロトコルにはプランのリクエスト数と同時実行数の上限は適用されませんが、日次送信量と明示的な制限は適用されます。転送は1件から始め、サービスがスロットリングを報告した場合はクライアントの同時実行数を下げてください。

アップロードはCLOSEまでSFTPセッション内にバッファーされます。現在、空のアップロードではファイルは作成されません。中断されたアップロードは永続的に再開できる転送ではありません。アップロードのResume、Append、reput、put -aを使用しないでください。現在のサーバーは書き込みを開く際に以前の先頭部分を読み込み直しません。できれば新しいファイル名を使い、オフセット0から全体を再アップロードしてください。

既存の名前に完全なファイルをアップロードすると、既存のファイルIDがdosyaのバージョン管理付きアップロード経路に渡されます。現在のバイトが置き換わり、バージョンが追加される場合があります。バージョン履歴は別途設定されていなければ標準で10件で、保持と整理の対象です。置換前に別のオリジナルを保管してください。rmとフォルダーの削除はクラウド上のコンテンツに影響し、対象項目をゴミ箱に移動して共有リンクを無効にします。ゴミ箱の保持期間は無料プランのオーナーでは7日、それ以外のプランでは30日です。完全削除は元に戻せません。コンテンツを復元しても、無効になった古い共有URLは再び有効になりません。

拒否の原因を調べる

メッセージまたは状態	対処
パスワード認証に失敗	メールアドレスの大文字と小文字、APIキー全体、SFTPプロトコルの選択、ワークスペースの固定、有効期限、フォルダー/IP制限を確認してください。認証情報を繰り返し推測すると、一時的にIPが禁止されることがあります。
このロールではSFTPを使用できません	ワークスペースへのアクセスを依頼してください。クライアントを変更してもロールの制限は回避できません。
access to that workspace is not permitted for this credential（SFTPステータス3）	メンバーシップとロールのSFTP権限を確認してください。
no such file or directory（ステータス2）	一覧にあるワークスペース名とパスを確認してください。表示権限のないリソースは存在しないように見える場合があります。
the parent directory does not exist or is not writable by this credential	既存のワークスペース/フォルダーに移動し、作成とアップロードの権限を確認してください。
write past the 352 MB per-file limit（または別の有効な値）	ゲートウェイの上限を超えるファイルにはWebアップローダーか別の適切なプロトコルを使用してください。回避策としてオフセットを分割しないでください。
close failed: API 403 … または close failed: API 429 (rate limited - back off and retry) …	権限やポリシーの詳細を調べるか、待ってから再試行してください。WRITEの成功はCLOSEで確定できることを保証しません。
access to this workspace was revoked while the upload was in flight	最終確定が拒否されました。部分的な書き込みを再開せず、オーナーに連絡してください。

SFTPはAPIの403をpermission denied、404をno-such-file、それ以外の失敗をステータス4に変換します。クライアントにはこれらの汎用名だけが表示されることがあります。サーバーの詳細は180文字に制限され、キーの形をしたシークレットは伏せられます。認証情報を公開せずに、表示された操作、エラー、時刻を記録してください。

切断と無効化

byeを実行するか、クライアントを切断してください。保存された認証情報は別途削除し、アクセスを終了する場合は**プロフィール → API（APIキー）**で専用キーを無効化します。SFTPのサインイン成功とロール権限のキャッシュはそれぞれ最大60秒保持されますが、API認可には別のキャッシュがあるため、60秒以内に無効化が完了する保証はありません。無効化が反映された後、再接続して対象の操作が拒否されることを確認してください。すでに開いている接続は、無効化されたキーで操作を確定できる証拠にはなりません。認証情報を無効化しても既存のワークスペースファイルは削除されません。

関連ガイド

• 中断したSFTP転送を復旧
• APIキーの設定と制限