rcloneを用いてSharePoint(OneDrive)にファイルをアップロードしてみた

1.はじめに

こんにちは。テクマトリックスの長久保です。

rcloneを用いてSharePoint(OneDrive)にファイルをアップロードする方法について調査する機会があったので、整理する意味も込めてブログにまとめました。
本記事では、rcloneの基本概念から実践的な利用方法、認証手順、そして運用上の注意点まで幅広く解説します。

2.rcloneとは

rcloneは、クラウドストレージ上のファイルを管理するためのコマンドラインプログラムです。
「rsync for cloud storage」とも呼ばれており、70以上のクラウドストレージサービスに対応しています。異なるクラウドストレージ間でのデータ移行や同期、バックアップなど、様々な用途に活用できます。

また、コマンドライン上からの実行が可能なので、Jenkinsで作成したビルド成果物を、Jenkins上ではなくAmazon S3やGoogle Drive、Microsoft OneDriveにアップロードするために利用できます。

対応しているクラウドストレージサービスの一覧は公式サイト：Supported providersを参照ください。
主要なストレージサービスは網羅されており、非常に汎用性の高いツールです。

3.OneDriveとSharePointの違い

rcloneでSharePointやOneDriveを扱う前に、これらのサービスの違いを理解しておくことが重要です。

3.1. 基本的な違い（用途の違い）

OneDrive（個人向け）
個人ユーザーまたは個人の業務用アカウントに割り当てられる専用のクラウドストレージ。
通常、自分だけがアクセスするファイルや、個人的なバックアップ目的で使用します。
SharePoint（チーム・組織向け）
チーム内でのファイル共有や共同作業に使われるストレージで、複数ユーザーによる同時アクセスが前提。
組織内のポータルサイトやドキュメントライブラリとして、業務上の情報共有を目的に使用します。

3.2. rcloneでの設定時の違い

rcloneではどちらもonedriveとして扱います。また、ファイルをアップロード可能という点では差異はありませんが、設定時に少々設定方法が異なります。

初期設定時にrclone config実行すると、以下のような選択肢が表示されます。

OneDriveを使う場合は、次を選択します。

  1) OneDrive Personal or Business

SharePointを使う場合は、次を選択します。

  2) Sharepoint site

また、SharePointの場合は、さらに接続するドキュメントライブラリが属するサイトを検索またはIDで指定する必要があります。

3.3. 認証方法・APIの違い

どちらも内部的にはMicrosoft Graph REST API v1.0を使用しますが、以下の点に注意が必要です。
OneDriveの場合、認証後にrcloneは自動的にユーザー自身のストレージを特定して直接ファイル操作をします。
しかし、SharePointを利用する場合、接続先のSharePointサイトを特定するため、Sites.Read.Allという追加のパーミッションが必要になります。
管理者がこの権限を許可していない場合、自動検出が使えないためサイトIDなどを手動で入力する必要があります。

3.4. ファイル操作時の挙動の違い

ファイルをアップロードするという点では同じですが、以下のような機能差があります。

機能・操作	OneDrive（個人）	OneDrive for Business	SharePoint
ファイルアップロード	○	○	○
バージョン管理	△（制限あり）	○	○
完全削除（ハードデリート）	×（サポートなし）	○	○

※特に注意点は以下の通りです。

個人向けOneDriveでは、API経由の完全削除（ごみ箱を経由せず直接消す削除）はサポートされていません。
個人向けOneDriveではファイルのバージョン管理が部分的で、API経由での古いバージョン削除はできません。
それ以外にも細かな制約があるため、一度、APIの仕様を一読することを推奨します。
SharePointやOneDrive for Businessでは、これらの機能がフルサポートされています。

4.実際に実行する

4.1.必要なファイルを取得する

必要なファイルは公式サイト：Downloadsからダウンロード可能です。

今回はWindows環境で実行します。
それ以外の環境については、公式サイト：Installのページを参照ください。

4.2.ログイン済み環境での実行

Microsoftアカウントにログイン済みの端末上で実行する場合は、スムーズに利用を開始することができます。

コマンドラインから以下のコマンドを実行し、新しいrcloneの接続情報を設定します。

rclone config

「n」を入力して新しいrcloneの接続情報を作成します。

リモート名を入力します（例：remote）。
ストレージタイプとして「Microsoft OneDrive」を選択します。
「Use auto config?」で「y」を選択すると、ブラウザが開いてMicrosoftアカウントでのログインを求められます。

ログイン後、アクセス許可を承認すると、設定が自動的に完了します。
OneDriveまたはSharePointサイトの選択を求められるので、適切なものを選びます。

基本的に公式サイトの手順通り実施することでスムーズに設定は完了できました。

設定が完了したら、以下のコマンドでOneDriveやSharePointとファイルのやり取りが可能です。
代表的なコマンドを記載します。コマンド一覧は公式サイト：Rclone Commandsを参照ください。

# 単一ファイルのアップロード
rclone copy localfile.txt remote:path

# ディレクトリ全体のアップロード
rclone copy /local/directory remote:remote/directory

# アップロード済みファイルの一覧表示
rclone ls remote:path/to/directory

# ファイルリストの表示
rclone ls remote:Documents

# ディレクトリ構造のみ表示
rclone lsd remote:

アップロードされたファイルはOneDrive上のマイファイルまたは指定したSharePointライブラリに保存されます。
該当のディレクトリを共有設定にしておけば、他の人からも参照することが可能です。

4.3.ヘッドレス環境での認証について

LinuxサーバーなどGUIのない環境では、以下のいずれかの方法で認証を行います。
公式サイト：Configuring rclone on a remote / headless machineのページも併せて確認ください。

方法1：rclone authorizeコマンドを用いる方法

ヘッドレス環境で以下のコマンドを実行します。

   rclone config

新しいリモートを設定する際、「Use auto config?」という質問で「n」（No）を選びます。

Use auto config?
 * Say Y if not sure
 * Say N if you are working on a remote or headless machine

y) Yes (default)
n) No
y/n> n

表示された指示文を確認します。通常は「rclone authorize “onedrive”」コマンドを別のブラウザが利用可能なマシンで実行するよう指示されます。
別のブラウザが利用可能なマシンで、同じバージョンのrcloneをインストールし、指示されたコマンドを実行します。

   rclone authorize "onedrive"

ブラウザが開き、Microsoftへのログインと認可が行われます。
認可が完了すると、ターミナル上に「SECRET_TOKEN」が表示されるので、それをヘッドレス環境側のrclone configプロンプトに貼り付けます。
これでヘッドレス環境のrcloneにも認証情報が渡され、設定が完了します。

方法2：設定ファイルをコピーする方法

すでにGUI環境のPCなどでOneDrive用のリモートを設定済みであれば、その設定ファイルを転送することでも認証を行うことが可能です。

ローカルPC上で以下のコマンドを実行し、設定ファイルの場所を確認します。

   rclone config file

通常は「~/.config/rclone/rclone.conf」または「%USERPROFILE%\.config\rclone\rclone.conf」が表示されます。
この設定ファイルをscpやSFTP、または手動でコピーするなどしてヘッドレスサーバー上の同じパスに配置します。
配置した設定ファイルの認証情報を元に、ヘッドレス環境でもrcloneコマンドをそのまま利用が可能です。

完全ヘッドレス環境のみでの認証は可能か？

上記の方法1：rclone authorizeコマンドを用いる方法だと、別環境のヘッドレスではないブラウザを使う必要があります。また方法2：設定ファイルをコピーする方法でもヘッドレスではないブラウザを用いて事前にログインし、認証済みのrclone.confを作成する必要があります。そのため、結論として、完全にヘッドレス環境のみでの認証は、標準的な方法では不可能です(少なくとも私が調べたり検証した範囲では実現できませんでした)。
Microsoftの認証システムは、ブラウザベースのOAuth認証フローを前提としており、ユーザーが対話的にログインしてアクセス許可を与える必要があります。
Microsoft ID プラットフォームと OAuth 2.0 認証コードフロー

また、lynxやw3mなどのテキストベースブラウザでの認証を試みることはできますが、MicrosoftのJavaScriptベースのログインページはこれらのブラウザでは正常に動作しませんでした。

Microsoft account requires JavaScript to sign in. This web browser either does not support JavaScript, or scripts are being blocked. To find out whether your browser supports JavaScript, or to allow scripts, see the browser's online help.

ポートフォワーディングを使った方法もあります。SSHポートフォワーディングを使用して、ヘッドレス環境のローカルポート（例：http://127.0.0.1:53682/）をSSHトンネル経由で手元PCに転送し、手元のブラウザで認証する方法もrclone公式でも紹介されていますが、やはり別マシンのブラウザが必要です。

代替手段として、クライアントID/シークレットを使用した認証も可能かもしれません。
Microsoft ID プラットフォームにおける権限と同意の概要
ただし、こちらの認証方法については、rcloneの公式サイトでも言及されていないため本ブログでは触れません。

ヘッドレス環境でrcloneを用いるための実用的なアプローチとしては、完全ヘッドレス環境のみで実現するのではなく、方法1：rclone authorizeコマンドを用いる方法、方法2：設定ファイルをコピーする方法のいずれかで初期認証を行い、その後は90日以内に定期的にrcloneを使用することでトークンを自動更新し続けるのが良いでしょう。

4.4.ファイルアップロード用のアカウントを用いての利用

自動化プロセスや特定の用途のために、専用のMicrosoftアカウントを作成して利用することもできます。

ファイルアップロード専用のアカウントを作成します。
Azure portalで個人用のクライアントIDを発行します。

Microsoft Entra IDにアクセス
「アプリの登録」→「新規登録」でアプリを作成
リダイレクトURIに「http://localhost:53682/」を設定

発行する際は以下の権限が必要です。

   Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, offline_access, User.Read, Sites.Read.All

作成したクライアントIDとシークレットをrclone configで設定する際に使用します。

ただし、会社などで管理しているアカウントの場合、Microsoft Entra IDにアクセスする権限がないことも考えられます。運用開始前に確認することを推奨します。

詳細についてはrcloneのOneDriveドキュメントを参照ください。

5.制限事項

5.1.トークンの有効期限

Microsoftの仕様により、rcloneを90日間利用しない場合、リフレッシュトークンが期限切れになります。その場合、以下のコマンドを用いて再認証を行う必要があります。

rclone config reconnect remote:

ここで「remote」は設定したリモート名に置き換えてください(初期設定の際に入力しています)。
この再認証では、通常のrclone config時と同様にブラウザでの認証が必要になります。

前述の通り、認証はブラウザベースのOAuth認証フローを用いて対話式での認証になるため、たとえばCI環境での成果物アップロード等の、非対話式環境での再認証は現実的ではありません。
ただし、定期的にrcloneを使ってOneDriveやSharePointにアクセスしていれば、トークンは自動的に更新され続けるため、90日以内に一度でも利用すれば再認証は不要です。

5.2.その他の制限事項

OneDriveとSharePointには以下のような技術的制限があります。

ファイル名の制限

使用できない文字：” (引用符), * (アスタリスク), : (コロン), < (小なり記号), > (大なり記号), ? (疑問符), / (スラッシュ), \ (バックスラッシュ), | (縦線)
ファイル名やフォルダ名の先頭または末尾にスペースを使用することはできません。
.lock、CON、PRN、AUX、NUL、COM0 – COM9、LPT0 – LPT9、vti、desktop.ini 、 ~$　の文字列は利用できません。

詳細については、以下を参照ください。

パスとサイズの制限

ファイルパス全体の長さ：最大400文字まで
各ファイル名/フォルダ名：最大255文字まで
ファイルサイズ：最大250GBまで

rcloneは、これらの制限に対して一部自動的に対応します。
例えば、OneDriveで使用できない文字を含むファイルをアップロードする場合、似たUnicode文字に自動変換するなどの対応を行います。

詳細はMicrosoftの公式ドキュメントを参照ください。

6.Microsoft Graph API経由での処理制限や注意点

rcloneのOneDrive/SharePoint連携は、バックエンドでMicrosoft Graph API v1.0（REST API）を利用しています。
そのため、API固有の挙動や制限に留意する必要があります。

6.1.SharePointサイトの検出権限

rcloneはデフォルトでGraph APIにSites.Read.All（テナント内のサイト閲覧権限）を要求し、ユーザーがアクセス可能なSharePointサイト一覧を取得します。
管理者がこの権限付与を許可していないテナントでは、サイト検索が機能しないため、手動でサイトIDやドライブIDを指定する必要があります。

6.2.ファイルのバージョン管理

OneDrive for BusinessやSharePointではバージョン管理が有効になっています。
アップロード時に旧バージョンも残るため、大量のデータが累積しストレージ容量を圧迫してしまうということも考えられます。
その場合は--onedrive-no-versionsオプションを使って古いバージョンを削除することができます。
ただし個人用OneDriveでは利用できません。
–onedrive-no-versions

6.3.削除操作(ごみ箱の有無)

Graph APIでファイルを削除すると、通常はごみ箱に移動します。
完全に削除したい場合は--onedrive-hard-deleteオプションが利用できますが、こちらも個人用OneDriveではサポートされていません。
–onedrive-hard-delete

6.4.大容量ファイルのアップロード

約4MiB以上のファイルをアップロードする際、rcloneは自動的に分割アップロード機能（Chunk Upload）を使用します。
デフォルトでは10MiBずつのチャンクに分割しますが、--onedrive-chunk-sizeオプションで変更可能です。
–onedrive-chunk-size

6.5.APIレート制限

Microsoft Graphは一定以上の大量リクエストが来るとレート制限をかけます。
rcloneは内部で自動的に再試行を行いますが、独自のクライアントIDを使用することで制限を緩和できる場合があるとのことです。

詳細は以下を参照ください。
Excessive throttling or blocked on SharePoint
Avoid getting throttled or blocked in SharePoint Online

7.CI環境との統合

ここで、簡単なCI環境との統合例を示します。
Jenkinsを用いた宣言型パイプラインの例を以下に示します。

pipeline {
    agent any
    stages {
        stage('成果物作成') {
            steps {
                //成果物がtargetフォルダ以下に作成される想定。
                env.CREATED_FILE = fileName //アップロード対象名称の保持
            }
        }
        stage('rcloneでアップロード') {
            steps {
                script {
                    // rcloneコマンドの実行
                    bat "rclone copy target\\${env.CREATED_FILE} {設定済みリモート名}:{アップロード先のパス}/ --progress"
                    echo "ファイル ${env.CREATED_FILE} をアップロードしました"
                }
            }
        }
    }
}

実装に際してのrcloneのオプションは公式ページ：rcloneコマンドや、公式ページ：Microsoft OneDriveを参照ください。

8.安全性の観点

rcloneは内部的にMicrosoft Graph REST API v1.0を利用しており、安全性については以下の点を挙げることができます。

オープンソース：ソースコードが公開されており、誰でも検証可能です。
活発な開発：コミット履歴からわかるように、頻繁にメンテナンスされています。
コミュニティ：多くの開発者やユーザーによってレビューされており、フォーラムも存在するため、マルウェア等のリスクは低いと考えられます。
認証セキュリティ：OAuth 2.0認証を使用しており、パスワードを直接保存することはありません。
通信暗号化：TLS/SSLによる安全な通信が行われます。

このようにrcloneは安全性の高いツールであり、信頼して使用できると言えます。
ただし、認証トークンの保管や適切な権限設定をする必要があります。

9.トラブルシューティング

利用時にありそうなエラーをいくつか紹介します。
私が確認した範囲ではエラーログが出力されるため、その内容に従って判断が可能でした。

トークン期限切れエラー
解決策：rclone config reconnect remote: で再認証します。

アクセス権限エラー
解決策：適切な権限（Files.ReadWrite.All, Sites.Read.All など）が付与されているか確認します。

ファイル名やパス長のエラー
解決策：ファイル名に使用できない文字（”*:/<>?|\）がないか確認します。また、合計400文字以内にフォルダ階層を減らすか、ファイル名を短くします。

アップロードエラー(429 Too Many Requests)
解決策：APIレート制限に達しています。しばらく待つか、6.5.APIレート制限を参考に独自のクライアントIDを使用すると良いでしょう。

rcloneの公式ページにもトラブルシューティングのページがあるため、利用前に一読されるとよいでしょう。

10.所感・まとめ

以下、個人的な感想です。

「rcloneの利用が可能なユーザーとして認証済みのブラウザ」がある環境かどうかで設定の難易度が大きく変わると感じました。
日常的にMicrosoftアカウントにログインし、作業している端末でrcloneの認証が可能であれば、設定は非常に容易ですし、すぐに利用開始できます。
一度設定してしまえば、コマンドラインからのファイル操作やスクリプトによる自動化が容易になるというメリットは非常に大きいです。自前でMicrosoft Graph REST APIの実装をするよりもとても簡単に利用することが可能ですので、とても有益なツールだと思いました。特に定期的なバックアップや大量のファイル転送などの場合、Webインターフェースよりもはるかに効率的に作業できます。

ただし、「rcloneの利用が可能なユーザーとして認証済みのブラウザ」が存在しない場合、「Microsoftアカウントとの連携」が非常に高いハードルになります。

特に企業で運用されている場合、個人アカウントの利用制限や内部統制でクライアントIDの発行ができないということもあるかと思います。Microsoftの認証について内部統制上利用が可能かどうかの確認をしてから、rcloneの利用を検討されるのが良いでしょう。