Dropbox API: ネームスペースとパスの表現

Dropbox APIファイル操作をするときに必ず必要になってくるのがネームスペースの概念とファイルやフォルダへのパスです。実際にはほとんど意識することなく使えるのですが、知っていると見えてくる仕様もあるのでそのあたりを詳しく見てみましょう。

Dropboxがどのようにファイルを管理しているか

Dropboxがどのようにファイルを管理しているかみていきます。まずは次の記事を参照してみます。

• Streaming File Synchronization

これはStreaming同期という機能を紹介したブログエントリですがDropboxファイルシステムについても言及しています。Dropboxでは、ファイルシステムを抽象化するにあたってネームスペースという概念を定義しています。ネームスペースはすべてのユーザーのルートフォルダにあたり、また共有フォルダのように他のユーザーと共有しているスペースについては別のネームスペースが与えられます。

ユーザーがいくつかの共有フォルダを持っている場合、それぞれの共有フォルダのネームスペースは特定のパス以下にマウントされている状態となります。

パスの書式

APIドキュメントのPath formatsというセクションに詳しく書かれていますがいくつか特徴をピックアップしてみます。

• ”” (空文字列)はルートフォルダを示す (ルートフォルダは “/” ではない)
• すべてのファイルやフォルダはIDを持っていて、このIDでも表現できる (例: "id:abc123xyz")
• IDで表現したフォルダからさらに相対パスを指定できる (例: "id:abc123xyz/hello.txt")
• ネームスペースIDを指定して、相対パスを指定できる (例: "ns:12345/cupcake.png")
• アルファベット大文字小文字の違いは無視されて、/A/B/c.txtも/a/b/c.txtも同一視される
• パスの区切り文字は “/”. Windowsで利用されている “" ではありませんのでご注意

なお、ネームスペースIDやフォルダのIDを指定した場合、当然ながら該当フォルダなどへのアクセス権限が必要となります。

実行例

下図はルートフォルダからのファイル一覧を取得する例です。ルートフォルダから一覧を取得するためにpathには”“を指定しています。

curl -X POST https://api.dropboxapi.com/2/files/list_folder \
    --header "Authorization: Bearer <access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\": \"\"}"

ルートフォルダを示すためにもし、”/” のようにスラッシュを入れてしまうと次のようなエラーが返されます。

Error in call to API function “files/list_folder”: request body: path: Specify the root folder as an empty string rather than as “/”.

ネームスペース

ネームスペースについてもう少し詳しく見てみましょう。Namespace Guideにいくつか例がありますが、契約しているプランなどによって共有フォルダなどの種類に若干違いがあります。

ネームスペースとなるものとしては下記5つが列挙されています。いずれの場合も、ネームスペース = アクセス制御の範囲と考えると良いでしょう。

• ユーザーのホームフォルダ
• 共有フォルダ
• チームフォルダ
• チームルートフォルダ
• アプリケーションフォルダ

ユーザーのホームフォルダはユーザー毎に作成されるものです。共有フォルダは共有フォルダとして新しくフォルダを共有した段階でそのフォルダが独立した別のネームスペースとして管理されます。

チームフォルダにはいくつか種類があるのですがどの場合でも独立したネームスペースとして管理されます。チームフォルダではチームフォルダ以下に作成したフォルダに追加のメンバーを設定することができるなど、共有フォルダにはできない設定が可能です。この場合、追加のメンバーを設定した下位のフォルダも実装上は別のネームスペースとして管理されることになります。

アプリケーションフォルダはアクセス範囲を制限した、Dropbox APIを利用するアプリケーション向けのフォルダです。各ユーザーのルートフォルダ以下「/アプリ/<アプリ名>」のようなフォルダにアプリケーション専用のデータを格納することができます。アプリケーションからみるとこのフォルダがルートフォルダとなり、ユーザーのホームフォルダなど他のネームスペースとなる部分にはアクセスできません。