Dropbox SDK を使った Ruby での Dropbox へのファイルエクスポート
コミュニティ製の dropbox_api gem を使い、Ruby からローカルファイルをエクスポートします。以下のコマンドはアクセストークンを更新し、明示的に指定した Dropbox パスにアップロードした後、結果をダウンロードして全バイトを検証し、完了を報告します。アプリフォルダー型のアプリでは、/report.csv はアプリのフォルダー内のファイルを意味します。先頭に /Apps/YourAppFolder を付けないでください。
前提条件
この手順は、Bash を使用でき、Bundler がインストール済みの
Linux 上にある既存の Ruby 3.4 アプリケーションを対象としています。再現に使用したバージョンは Ruby 3.4.10、Bundler 4.0.23、dropbox_api 0.1.21 です。Ruby 3.4 は保守対象です。アプリケーションには最新のパッチリリースを使用してください。現在の安定版メジャーバージョンは Ruby 4.0 ですが、この手順の実行環境は 3.4 に限定しています。gem の最新公開リリースは現在も
2022年3月の 0.1.21です。ここでの互換性はテスト済みの組み合わせを示すもので、現行の Ruby への対応を開発元が保証しているわけではありません。
Dropbox アカウントと、アプリシークレットおよびリフレッシュトークンを保管できる、非公開のサーバー側環境が必要です。内容が変化しない通常ファイルを、UTF-8 のファイル名で使用してください。この例は空のファイルとバイナリデータに対応していますが、検証時にダウンロード全体をバッファリングするため、各ファイルの上限は 16 MiB です。リモートパスには ASCII 文字を使用する必要があります。UTF-8 のローカルファイル名に ASCII のリモート名を付けるには、ファイルモードを使用してください。このため、ディレクトリモードではベース名が ASCII である必要があります。エクスポートは逐次実行し、実行中は入力ファイルを変更しないでください。チームスペースの名前空間の選択と、複数の書き込み処理の同時実行は、この例の対象外です。
Dropbox アプリの設定とアクセストークンの取得
Dropbox App Console でアプリを作成します。自分のファイルだけを扱うエクスポーターには、App folder を選択してください。既存の Full Dropbox アプリでも同じコードを使えますが、その場合、パスの起点はユーザーのデフォルトの Dropbox ルートになります。アプリフォルダーへのアクセス権は利用可能なコンテンツを制限し、OAuth スコープはそれとは別に操作を制限します。認可する前に、files.content.write、files.content.read、files.metadata.read を有効にしてください。このコマンドはアップロード、ダウンロード、保存先の既存ファイルの確認を行います。
アプリフォルダー型のアプリでは、API パス /Exports/report.csv は
Dropbox 内のアプリのフォルダー配下に表示されます。フルアクセス型のアプリでは、デフォルトのユーザールート内の
/Exports 配下に表示されます。親フォルダーは事前に Dropbox に作成し、大文字と小文字を正確に指定してください。これらは API パスであり、ウェブサイトの URL やローカルファイルシステムのパスではありません。ASCII に限定するのは、このバージョンの gem で引数ヘッダーに非 ASCII 文字が入るのを避けるためです。Dropbox のヘッダーエンコード規則では、そのような文字をエスケープする必要があります。
シークレットマネージャーまたは非公開のシェル環境を通じて、DROPBOX_APP_KEY と DROPBOX_APP_SECRET を環境変数として渡してください。シークレットをソース管理やコマンド引数に含めないでください。最初に一度だけオフラインアクセスの認可を要求し、以降の無人実行には、そこで取得したリフレッシュトークンを使用します。Dropbox のコードフローガイドでは、このローカルでコピー&ペーストする認可フローでのリダイレクト URI の省略が認められています。
Ruby 用 Dropbox SDK のインストール
BUNDLE_* による上書き設定のない Bash セッションで、書き込み可能な親ディレクトリから次のブロックを貼り付けて実行してください。新しい dropbox-export プロジェクトが作成されます。同名のディレクトリが既にある場合はエラーになり、そのディレクトリは変更されません。サブシェルを使うため、インストールが失敗しても現在のディレクトリとシェルオプションは維持されます。
(
set -eu
command -v ruby >/dev/null
command -v bundle >/dev/null
mkdir dropbox-export
cd dropbox-export
cat > Gemfile <<'RUBY'
source 'https://rubygems.org'
gem 'dropbox_api', '0.1.21'
RUBY
bundle config set --local path vendor/bundle
bundle install
)
作成されたディレクトリをエディターで開き、以降のコマンドの作業ディレクトリとして使用してください。生成された Gemfile.lock はアプリケーションと一緒に保管し、後のインストールでも同じ解決済み依存関係が使われるようにしてください。プロジェクト作成後にインストールが失敗した場合は、ファイルを確認し、そのディレクトリから bundle install を再実行してください。セットアップをやり直すために既存のプロジェクトを削除しないでください。
Ruby での Dropbox 認証
次のコードを authorize_dropbox.rb として保存してください。url コマンドは認可 URL を出力します。exchange コマンドは環境変数から DROPBOX_AUTH_CODE を読み取り、所有者が読み取れる新しいファイル refresh-token に、リフレッシュトークンだけを保存します。既存のトークンファイルの置き換えは拒否します。
require 'dropbox_api'
def authorize
auth = DropboxApi::Authenticator.new(
ENV.fetch('DROPBOX_APP_KEY'), ENV.fetch('DROPBOX_APP_SECRET')
)
case ARGV
when ['url']
puts auth.auth_code.authorize_url(token_access_type: 'offline')
when ['exchange']
raise 'refresh-token already exists' if File.exist?('refresh-token')
token = auth.auth_code.get_token(ENV.fetch('DROPBOX_AUTH_CODE'))
raise 'No refresh token returned' if token.refresh_token.to_s.empty?
File.open('refresh-token', File::WRONLY | File::CREAT | File::EXCL, 0o600) do |file|
file.write(token.refresh_token)
end
puts 'Authorization saved to refresh-token'
else
raise ArgumentError, 'Use url or exchange'
end
end
begin
authorize
rescue StandardError => error
warn "Authorization failed (#{error.class})"
exit 1
end
次を実行します。
bundle exec ruby authorize_dropbox.rb url
出力された URL を自分で開いてアプリを認可し、表示されたコードを、同じ非公開環境で DROPBOX_AUTH_CODE を通じて渡してください。続いて次を実行します。
bundle exec ruby authorize_dropbox.rb exchange
refresh-token はソース管理に含めず、バックアップへのアクセスも制限してください。非公開ストレージに移動し、その絶対パスを DROPBOX_REFRESH_TOKEN_FILE に設定することもできます。エクスポーターは呼び出されるたびに、このリフレッシュトークンから新しいアクセストークンを生成します。コンソールで生成したアクセストークンが引き続き有効であることには依存しません。認可が取り消された場合は、認可フローを繰り返す必要があります。
Ruby を使った Dropbox へのファイルアップロード
次のプログラム全体を export_dropbox.rb として保存してください。4 MiB 未満のファイルには単一のアップロードリクエストを使用します。4 MiB 以上では、gem がデフォルトの 4 MiB チャンクでアップロードセッションを使用します。このしきい値を意図的に小さく設定することで、この例の上限である 16 MiB 以内でもセッションを使う処理を実行できます。Dropbox のアップロードエンドポイントは、より大きな単一リクエストに対応していますが、この例ではその上限に近づける必要はありません。
require 'digest'
require 'dropbox_api'
require 'json'
require 'stringio'
MAX_SINGLE_REQUEST_UPLOAD = 4 * 1024 * 1024
MAX_FILE_BYTES = 16 * 1024 * 1024
def utf8_path(value)
path = value.dup.force_encoding(Encoding::UTF_8)
raise ArgumentError, 'Paths must be valid UTF-8' unless path.valid_encoding?
path
end
def remote_path(value)
path = utf8_path(value)
raise ArgumentError, 'Dropbox paths must contain ASCII only' unless path.ascii_only?
parts = path.split('/', -1)
unless path.start_with?('/') && parts.drop(1).all? { |part| !['', '.', '..'].include?(part) }
raise ArgumentError, 'Use an absolute Dropbox file or folder path without empty, . or .. segments'
end
path
end
def initialize_dropbox_client
auth = DropboxApi::Authenticator.new(
ENV.fetch('DROPBOX_APP_KEY'), ENV.fetch('DROPBOX_APP_SECRET')
)
refresh_token = File.read(ENV.fetch('DROPBOX_REFRESH_TOKEN_FILE', 'refresh-token')).strip
raise ArgumentError, 'Refresh token is empty' if refresh_token.empty?
token = OAuth2::AccessToken.new(auth, '', refresh_token: refresh_token, expires_at: 0)
DropboxApi::Client.new(access_token: token)
end
def with_rate_limit(max_retries = 3)
retries = 0
begin
yield
rescue DropboxApi::Errors::TooManyRequestsError => error
raise if retries >= max_retries
retries += 1
wait = error.retry_after.to_i.positive? ? error.retry_after.to_i : 2**retries
sleep(wait)
retry
end
end
def upload_file(client, file_path, dropbox_path)
local = utf8_path(file_path)
destination = remote_path(dropbox_path)
raise ArgumentError, 'Input must be a regular file' unless File.file?(local)
raise ArgumentError, 'File exceeds 16 MiB' if File.size(local) > MAX_FILE_BYTES
bytes = File.binread(local)
raise ArgumentError, 'File exceeds 16 MiB' if bytes.bytesize > MAX_FILE_BYTES
existing = begin
with_rate_limit { client.get_metadata(destination) }
rescue DropboxApi::Errors::NotFoundError
nil
end
raise 'Destination already exists' unless existing.nil?
uploaded = if bytes.bytesize >= MAX_SINGLE_REQUEST_UPLOAD
with_rate_limit { client.upload_by_chunks(destination, StringIO.new(bytes), mode: :add, autorename: false) }
else
with_rate_limit { client.upload(destination, bytes, mode: :add, autorename: false) }
end
downloaded = nil
stored = with_rate_limit do
client.download("rev:#{uploaded.rev}") do |body|
downloaded = body.nil? ? ''.b : body.b
end
end
unless uploaded.path_display == destination && stored.path_display == destination &&
uploaded.size == bytes.bytesize && stored.size == bytes.bytesize && downloaded == bytes
raise 'Stored file did not match the requested path and bytes'
end
puts JSON.generate(path: destination, bytes: bytes.bytesize, sha256: Digest::SHA256.hexdigest(bytes))
end
class DropboxExporter
def initialize(client)
@client = client
end
def process_directory(local_dir, dropbox_dir)
local = utf8_path(local_dir)
remote = remote_path(dropbox_dir)
raise ArgumentError, 'Input must be a directory' unless File.directory?(local)
Dir.children(local).sort.each do |name|
path = File.join(local, name)
next unless File.file?(path)
upload_file(@client, path, "#{remote}/#{utf8_path(name)}")
end
end
end
if $PROGRAM_NAME == __FILE__
begin
raise ArgumentError, 'Use file|directory LOCAL DROPBOX_PATH' unless ARGV.length == 3
mode, local, remote = ARGV
raise ArgumentError, 'Use file or directory' unless ['file', 'directory'].include?(mode)
client = initialize_dropbox_client
if mode == 'file'
upload_file(client, local, remote)
else
DropboxExporter.new(client).process_directory(local, remote)
end
puts 'Export complete'
rescue StandardError => error
warn "Export failed (#{error.class}); inspect the destination before retrying"
exit 1
end
end
このプロジェクトディレクトリから、既存のローカルファイルをアプリのルートにエクスポートします。
bundle exec ruby export_dropbox.rb file ./report.csv /report.csv
コマンドが成功すると、API パス、バイト数、ローカルのバイト列の通常の SHA-256 を含む JSON レコードが出力され、その後に Export complete が出力されます。ダウンロードにはアップロードしたリビジョンを使用するため、比較ではそのバージョンの内容全体を検証します。gem はダウンロードをバッファリングするため、アップロードをチャンクに分割しても、このエクスポーターのメモリ使用量が一定になるわけではありません。
エラーと例外の処理
ファイルや設定の不足、認可の拒否、既存の保存先、セッション完了の失敗、再読み取り時の不一致がある場合、コマンドはゼロ以外の終了コードで終了します。診断メッセージには例外クラス名が表示されますが、プロバイダーのレスポンス本文や認証情報は出力されません。再読み取り中の NotFoundError は、要求したリビジョンを読み取れなかったことを意味します。保存先とアプリの権限を確認してください。更新中の OAuth2::Error は、認可が成功しなかったことを意味します。
再試行するのは TooManyRequestsError だけで、操作ごとに最大三回です。待機時間には正の retry_after の値を使用し、それ以外の場合は 2 秒、4 秒、8 秒を使用します。その他の失敗は呼び出し元に伝播します。アップロードが成功しても、レスポンスや検証結果が失われた場合は、リモートファイルが存在している可能性があります。再試行する前に確認してください。このスクリプトは失敗時にリモートデータを削除しません。開始したセッションも未完了のまま残る可能性があります。
既存の保存先を確認するため、同じバイト列であっても逐次的な再実行は失敗します。これはロックではありません。エクスポート中は、保存先フォルダーへの他の書き込みを防いでください。アップロードでは mode: :add と autorename: false を要求します。スクリプトは上書きを要求せず、名前が変更された結果を成功として扱うこともありません。
Ruby アプリケーションでのファイルエクスポートの自動化
Dropbox 内のアプリフォルダーに /Exports を作成し、既存のローカルディレクトリ exports の直下にある通常ファイルをエクスポートします。
bundle exec ruby export_dropbox.rb directory ./exports /Exports
ディレクトリモードでは隠し通常ファイルも対象に含め、サブディレクトリはスキップし、最初の失敗で停止します。それまでのファイルはエクスポートおよび検証済みのまま残ります。ディレクトリ全体を成功か失敗のどちらかにするトランザクションではありません。空のディレクトリにはエクスポートするファイルがありません。スケジュール実行するバッチごとに新しい保存先フォルダーを使用するか、完了したパスを記録してから、次の実行の入力を選択してください。
Rails のジョブでは、export_dropbox.rb を require し、ジョブ内でクライアントを作成して、upload_file または DropboxExporter.new(client).process_directory を呼び出してください。これらのメソッドは失敗時に例外を送出するため、ジョブ側でその失敗を記録するようにしてください。認証情報は同じ非公開設定を通じて利用できるようにし、リモート側の結果が不確かな場合は、ジョブが再試行する前に確認してください。
ご自身での運用は避けたいですか?
Transloadit は、単一の API 呼び出し内の処理の一環として、S3、Azure、Google Cloud などにファイルをエクスポートします。
