Extensions 開発者ガイド

1. Extensions の概要

アプリで Dropbox Extensions を使用すると、ファイルの［開く］メニューまたは［共有］メニューを使用して、Dropbox から直接アプリを開始できるようになります。

ユーザーがファイルのメニューでアプリ名をクリックすると、Dropbox は、事前に設定された Extensions URI に file_id パラメーターと require_role パラメーターを渡します。アプリがリクエストを受け取った後、ユーザーはアプリのワークフローに遷移し、ユーザーの識別、Dropbox からの元のファイルの取得、アプリ固有のワークフローの提供（ファイルの編集など）、変更を加えたファイルの Dropbox への保存（必要な場合）は、すべてアプリが実施することになります。

2. Extensions を設定する

Dropbox Extensions は、Dropbox へのフルアクセス権を持つ新規または既存のあらゆる Dropbox アプリに追加できます。

新規アプリの場合は、Dropbox へのフルアクセス権を持つアプリをアプリコンソールで作成します。スコープを使用するアプリの場合は、files.metadata.read 以上のスコープも必要になります。
文字隠し
Dropbox における OAuth 2 スコープの詳細については、こちらをご覧ください。 Dropbox へのフルアクセス権を持つ既存のアプリがある場合は、アプリの［Settings］ページで新しい Extension URI を追加できます。

文字隠し
［Settings］ページの［Extensions］セクションにある［Add］ボタンをクリックして、Extension の設定に進みます。

Extension URI
Dropbox からのユーザーのリダイレクト先であり、file_id と require_role の値を渡す先となる URI です。たとえば、https://www.example.com/dropbox_extensions と入力した場合、Dropbox は、https://www.example.com/dropbox_extensions?file_id={dropbox_file_id})&require_role={work/personal} という URI を送信します。
a-1.

a-i. file_id はファイルを指す一意の識別子であり、fileMetadata.id の値に対応します。そのため、/files/get_metadata などの Dropbox API エンドポイントと組み合わせて使用できます。

a-ii. require_role は、ユーザーがチームアカウント（work）または個人用アカウント（personal）のどちらで承認しているかを示します。このパラメーターは、アプリの再承認が必要で、ユーザーが個人用アカウントとビジネス用アカウントをリンクしている場合に使用できます。

a-2
What is the main purpose of this extension?
この Extension を、選択したファイルの［開く］メニューまたは［共有］メニューのどちらに表示するかを、アプリの機能に基づいて指定します。
b-1.

b-i. Opening/Editing files：Extension は選択したファイルの［開く］メニューに表示されます。

b-ii. Sharing/Sending files：Extension は選択したファイルの［共有］メニューに表示されます。

b-2.
Supported File Types
サポートするファイル拡張子をカンマで区切って入力します。Extension は、ここで指定した形式のファイルの［開く］メニューまたは［共有］メニューにのみ表示されます。
文字隠し
Max File Size (MB)
（オプション）ファイルサイズの上限を指定します。ここで指定したサイズよりも大きなファイルで Extension を選択した場合、次のエラーが表示されます。
Visibility
作成時点での Extension は、デベロッパーの Dropbox アカウントにのみ表示されます。これはテスト用であり、承認する必要がありません。Extension の設定を行い、想定どおりに動作することがテストで確認できたら、この画面に戻って［Only me］フィールドをオフにします。すると、他のユーザーにもこの Extension が表示されるようになります。他のユーザーにも Extension が表示されるようにすると、すでにアプリを承認済みのユーザーの Dropbox アカウントには、アプリの再承認なしで Extension が表示されます。

3. Extensions アプリを使用する

OAuth 経由でアプリを承認する
Extensions がエンドユーザーの［開く］メニューまたは［共有］メニューに表示されるのは、（a）デベロッパーがアプリの［Visibility］セクションにある［Only me］をオフにし、（b）エンドユーザーがアプリを OAuth 経由で承認している場合に限られます*。OAuth フローは、通常の Dropbox アプリと同様、デベロッパーのウェブサイトから開始する必要があります（アプリが Dropbox App Center で提供されている場合を除きます）。エンドユーザーが OAuth フローを完了すると、アプリにアクセストークンが付与されます。アプリはこのトークンを使用して /users/get_current_account などの Dropbox API を呼び出し、ユーザー情報を取得できます。
文字隠し
*チーム管理者がこの設定を管理している Dropbox Business チームでは、Extensions が表示されない場合があります。アプリインテグレーションと Extensions の管理の詳細については、ヘルプセンターの記事をご覧ください。
文字隠し
Dropbox で Extensions のワークフローを開始する
アプリを承認後、ユーザーはファイルの［開く］メニューまたは［共有］メニューから Extension を利用できるようになります。ユーザーがメニューのアプリ名をクリックすると、あらかじめ設定された Extension URI にリダイレクトされ、file_id パラメーターと require_role パラメーターがアプリに渡されます。

この後の処理を続行する前に、users/get_current_account を呼び出し、レスポンスの account_type が require_role と対応していることを確認します。ユーザーは、個人用アカウントとビジネス用アカウントをリンクしている場合があるためです。account_type のレスポンスが business で、require_role が work である場合、そのユーザーは Dropbox Business のチームアカウントを使用しています。このとき、再承認が必要になる場合もありますが、承認フローの require_role の値を使用できます。
文字隠し
ファイルを操作する
アプリのワークフローによっては、同じアクセストークンと file_id で別の API エンドポイントを使用する必要があります。たとえば、ファイルをダウンロードするには /files/download を使用し、ファイルのメタデータを取得するには /files/get_metadata を使用します。なお、スコープが指定されたアプリの場合は、特定のエンドポイントを呼び出すために適切な権限が必要になります。こちらのドキュメントを参照して、各エンドポイントへの呼び出しを行うために必要なスコープをご確認ください。

API Explorer を使用すると、各 API エンドポイントの動作を簡単にテストできます。
文字隠し
ファイルを Dropbox に保存し直す
選択されたファイルにアプリで変更を加えた場合は、そのファイルをユーザーの Dropbox アカウントに保存し直すことをおすすめします。ファイルを Dropbox に保存し直す方法は次のように複数あります。
4-1.
4-a. /files/upload エンドポイントを使用。
4-b. /files/save_url エンドポイントを使用。
4-c. Saver を使用。Saver は、Dropbox の信頼された UI から、ユーザーがファイルの保存先を簡単に選択できるようにするためのプリビルトされたコンポーネントです。