認証とセットアップ
Dropboxの統合は、Scoped AccessアプローチによるOAuth 2.0認証を使用します。組織は、Dropbox App ConsoleでDropbox Appを作成し、適切な権限を設定する必要があります。この統合は、個人のDropboxアカウントとDropbox Businessチームアカウントの両方をサポートしています。エージェントは、適切な認証を得てユーザーのDropboxまたは共有チームフォルダ内のファイルにアクセスできます。必要な権限とスコープ
- files.content.write: ファイルコンテンツのアップロードと変更を行います。
- files.content.read: ファイルコンテンツのダウンロードと読み取りを行います。
- files.metadata.write: フォルダの作成、ファイルの移動、名前変更、削除を行います。
- files.metadata.read: ファイルとフォルダのメタデータを表示します。
- sharing.write: 共有リンクの作成と変更を行います。
- sharing.read: 既存の共有設定を表示します。
- team_data.member: チームフォルダコンテンツへのアクセス（Dropbox Business）。
利用可能な操作
すべての必要な権限を設定すると、ツールキットは以下の操作を可能にします。ファイル操作
- Upload File: 自動バージョニング機能付きで、エージェントワークスペースからDropboxにファイルをアップロードします。
- Download File: 部分ダウンロードをサポートし、ファイルを取得してローカルで処理します。
- Move File: 自動的な競合解決機能付きで、フォルダ間でファイルを移動します。
- Copy File: 同じ場所または異なる場所にファイルを複製します。
- Delete File: ファイルを削除します（削除ファイルは30日間復元可能です）。
- Restore File: 削除されたファイルを復元したり、以前のバージョンに戻したりします。
- Get File Metadata: サイズ、変更日、コンテンツハッシュなどのファイルの詳細を取得します。
- Search Files: ファイル名とコンテンツの全文検索を行います（サポートされている場合）。
- Get Thumbnail: 画像やドキュメントのプレビューサムネイルを生成します。
フォルダ管理
- Create Folder: ネストされた階層で新しいフォルダを作成します。
- List Folder: ページネーションサポート付きでフォルダの内容を閲覧します。
- Move Folder: フォルダ構造全体を移動します。
- Copy Folder: すべての内容を含むフォルダを複製します。
- Delete Folder: フォルダとすべての内容を削除します。
- Get Folder Metadata: フォルダのプロパティと統計情報を取得します。
共有操作
- Create Shared Link: 公開またはパスワード保護付きの共有リンクを生成します。
- List Shared Links: ファイルとフォルダのすべてのアクティブな共有リンクを表示します。
- Revoke Shared Link: 共有リンクを無効化し、さらなるアクセスを防止します。
- Update Link Settings: リンクの権限と有効期限日を変更します。
- Create Shared Folder: 特定のユーザーまたはチームとフォルダを共有します。
- Add Folder Member: 共有フォルダでのコラボレーションにユーザーを招待します。
- Remove Folder Member: 共有フォルダのコラボレーターのアクセスを剥奪します。
- Set Link Expiration: リンクの自動有効期限日を設定します。
- Set Link Password: パスワード認証でリンクを保護します。
高度な操作
- Get File Revisions: ファイルのバージョン履歴にアクセスします（最大30日間、または拡張履歴でそれ以上）。
- Batch Operations: 単一のAPIコールで複数のファイル操作を実行します。
- Upload Session: チャンクアップロードセッションを使用して大きなファイル（150MB以上）をアップロードします。
- Download Zip: 複数のファイルを圧縮アーカイブとしてダウンロードします。
- Get Space Usage: アカウントのストレージ使用量と利用可能な空き容量を確認します。
- Paper Doc Operations: Dropbox Paperドキュメントを作成および編集します。
Dropbox Business機能
- Team Folder Access: チームフォルダにアクセスして管理します。
- Member Management: チームメンバーとその権限を一覧表示します。
- Admin Operations: 管理タスクを実行します（管理者権限が必要です）。
設定オプション
- Default Folder: Dropbox内のデフォルトのアップロード場所を設定します。
- Conflict Resolution: ファイル名の競合時の動作を選択します（自動リネーム、上書き、失敗）。
- Chunk Size: 大きなファイルのアップロードチャンクサイズを設定します（デフォルト4MB）。
- Link Permissions: 共有リンクのデフォルト権限（閲覧のみ、編集）。
- Auto Delete: アップロード成功後にローカルファイルを自動的に削除します。
ユースケース
- ファイルストレージ: エージェントワークスペースから重要なドキュメントとデータをクラウドにバックアップします。
- バックアップ自動化: 重要なファイルのDropboxへの自動バックアップをスケジュールします。
- ファイル共有: レポート、ドキュメント、またはデータセットの共有リンクを生成し、ステークホルダーがアクセスできるようにします。
- コラボレーションワークフロー: チームでのコラボレーションのために共有チームフォルダにファイルをアップロードします。
- ドキュメント配信: 共有リンクを通じて、生成されたレポートを複数の受信者に配信します。
- データ移行: Dropboxを仲介として、ストレージシステム間でファイルを転送します。
- バージョン管理: ドキュメント管理にDropboxの自動バージョニングを活用します。
- メディアライブラリ: 画像、動画、メディアアセットを保存および整理します。
ベストプラクティス
- パス識別子の使用: 安定性のために、ファイルをパスで参照してください（大文字小文字を区別しません）。
- チャンクアップロード: 150MB以上のファイルには必ずアップロードセッションを使用してください。
- バッチリクエスト: APIコールを削減するために複数の操作をグループ化してください（バッチあたり最大1,000操作）。
- レート制限の監視: Dropboxはレート制限を適用しています。リトライには指数バックオフを実装してください。
- リンクの有効期限: 機密コンテンツの共有リンクに有効期限日を設定してください。
- フォルダの整理: ファイルを整理するために明確なフォルダ階層を使用してください。
- 空き容量の確認: 大量アップロード前に利用可能なストレージを確認し、失敗を防いでください。
レート制限とクォータ
Dropbox APIはアプリの種類とアカウントティアに基づいてレート制限を適用します。標準の制限：個人ユーザーは毎秒40リクエスト。バッチ操作は単一リクエストとしてカウントされます。HTTP 429レスポンスを監視し、指数バックオフによるリトライロジックを実装してください（推奨：1秒、2秒、4秒、8秒）。よくある問題と対処法
- パスが見つかりません: パスのスペルと大文字小文字を確認してください（Dropboxのパスは大文字小文字を区別しませんが、大文字小文字を保持します）。
- 空き容量が不足しています: アップロード前にアカウントのストレージを確認してください。必要に応じてプランをアップグレードしてください。
- レート制限を超過しました: 指数バックオフを実装し、バッチ操作の使用を検討してください。
- アップロードタイムアウト: ネットワークの中断に対応するために、大きなファイルにはチャンクアップロードセッションを使用してください。
- 権限が拒否されました: OAuthスコープにその操作に必要な権限が含まれていることを確認してください。