ウェブアプリ統合の作成
ウェブアプリ統合の作成
次のガイドでは、カスタムアプリのウェブアプリ統合を設定する方法について説明します。
前提条件
開始する前に、以下の要件を満たしている必要があります。
- 会社の開発者コンソールにアクセスできる必要があります。アクセスできない場合は、Developerアカウントにサインアップしてください。
- 開発者コンソールでOAuth 2.0認証を使用してカスタムアプリを作成済みである必要があります。
1. 新しい統合を作成する
開発者コンソールにログインし、アプリケーションを探し、左側のサイドバーで[統合]パネルを見つけます。[ウェブアプリ統合を作成]をクリックします。
2. 統合を構成する
好きなように統合を構成します。以下に、各値のガイドを示します。
アプリ情報
フィールド | 説明 |
---|---|
統合名 | 統合の名前。ユーザーがファイルを選択すると、ウェブアプリのコンテキストメニューにこの名前が表示されます。 |
説明 | Boxアプリギャラリーに表示される統合の説明。 |
サポートされているファイル拡張子 | この統合が有効になるファイルの種類。この統合は、この拡張子が付いたファイルにのみ表示されます。 |
共有ページで表示 | 共有ページで外部ユーザーに統合を表示可能にするかどうかを決定します。オンに切り替えた場合、項目のコラボレータではないユーザーが共有リンクを介して項目を閲覧すると、コンテキストメニューに統合が表示されます。 |
コールバック設定
フィールド | 説明 |
---|---|
ユーザーエクスペリエンス | 統合がサーバー側統合であるか、ポップアップ統合であるか。 |
事前コールバックのURL | ユーザーがプロンプトを受け入れたときにコールバックパラメータの送信先となるURL。これは、アプリケーションサーバーでAPI呼び出しを実行するURLであることがほとんどですが、HTTPリクエストを受け入れるように構成されたエンドポイントにすることもできます。 |
クライアントコールバックのURL | ポップアップ統合で、最初のリクエストの後にBoxからの追加のコールバックリクエストを処理するコールバックURL。アプリケーションがRESTメソッドでファイルパラメータを指定した場合、事前コールバックのURLはクライアントから発信できません。その結果、サーバーが必要なインターフェイスをユーザーに送信できるように、2番目のリクエストがクライアントからサーバーに送信される必要があります。 |
統合ステータス
この統合のステータス。
- 開発: 統合は、アプリケーションに割り当てられた開発者のみが表示し、使用できます。このオプションは、アプリケーションがまだ開発中で、開発者が統合をテストする場合に最もよく使用されます。
- オンライン: 統合は、すべてのBoxユーザーが表示し、使用できます。このオプションは、開発が完了し、アプリケーションをアプリギャラリーで公開する準備ができている場合に最もよく使用されます。
- メンテナンス: 統合は、アプリケーションに割り当てられた開発者のみが表示し、使用できます。このオプションは、アプリケーションが一般にリリースされ、メンテナンスでの更新の実行または問題のトラブルシューティングが必要な場合に最もよく使用されます。このオプションを使用すると、統合の開発者を除くすべてのユーザーに対して統合が一時的にオフラインになります。
コールバックパラメータ
[コールバックパラメータ]セクションでは、ユーザーが確認プロンプトを受け入れるとBoxからコールバックURLに送信されるパラメータを構成します。構成しないと、BoxからコールバックURLにパラメータが送信されません。
以下のパラメータが使用可能です。
パラメータ | 説明 |
---|---|
user_id | ユーザーのBox ID。この情報は、アクションを完了するためにユーザー認証が必要なポップアップ統合で使用されます。Box IDをアプリケーションに保存すると、アプリケーションで統合からの後続のリクエストを認証できます。 |
user_name | Boxユーザーのフルネームまたはメールアドレス。Boxユーザーが常に自分の名前を指定しているとは限りません。 |
file_id | ファイルのBox ID。このIDを使用すると、ファイルを操作するBox API呼び出しを実行できます。 |
file_name | ファイルの名前。 |
file_extension | ファイルの拡張子。 |
auth_code | 認証の成功時にBoxから提供される、ファイルのOAuth 2承認コード。API呼び出しを実行するには、アプリケーションでOAuth 2.0アクセストークンとOAuth 2.0更新トークンの代わりにこの承認コードをBoxに指定する必要があります。有効なアクセストークンが含まれた承認ヘッダーをすべてのBox APIリクエストに含める必要があります。 |
redirect_to_box_url | ポップアップ統合で、確認プロンプトによるリクエストの送信先となるURL。このパラメータはポップアップ統合のみに適用できます。このURLを使用すると、ユーザーは[すべてのファイル]ページにリダイレクトされます。このパラメータにより、ポップアップパネルが閉じ、[すべてのファイル]ページは、統合による変更がすべて反映されるよう更新されます。このパラメータをアプリケーションに追加しない場合は、URL全体を指定できます。成功: #redirect_to_box_url#&status=success&message=Your%20action%20was%20successful%2E 。失敗: #redirect_to_box_url#&status=failure&message=Your%20action%20was%20unsuccessful%2E |
Box統合の使用例
ユーザーがポップアップ統合を選択すると、Boxから事前コールバックのURLにコールバックリクエストが送信されます。これにより、構成済みのコールバックパラメータがサーバーに送信されます。クライアントが必要なデータを最初のリクエストからすべて取得できない場合は、Boxが2番目のリクエストを送信することもあります。
次の例では、クライアントコールバックのURLが必要ありません。
- ポップアップ統合で、
download_file_url
コールバックパラメータを使用してREST呼び出しを実行する。 - ユーザーが確認プロンプトで[OK]をクリックしてポップアップを受け入れる。
- Boxが次のURLにリクエストを送信する(事前コールバックのURLにコールバックパラメータを追加):
http://www.doceditor.com/service?apikey=abc&file=&redirect=
。 - コールバックURLからの応答により、リクエストを送信したユーザーにユーザーインターフェイスが表示される。ポップアップには、アクションを続行するために必要なすべての情報が表示されているため、追加のクライアントコールバックは必要ありません。
次の例では、クライアントコールバックのURLが必要です。
- ポップアップ統合で、ファイルコールバックパラメータを使用してREST呼び出しを実行する。
- ユーザーが確認プロンプトで[OK]をクリックしてポップアップを受け入れる。
- ポップアップによって表示されたページで、Boxからリモートサーバーに、ファイルのコンテンツを含むPOSTリクエストとともにコールバックパラメータが送信される。
- Boxがリモートサーバーから応答を受信し、クライアントにクライアントコールバックのURLへの応答を投稿するよう指示する。このURLで識別されたサーバーが応答を解釈し、適切なセッションIDを持つユーザーをリダイレクトします。
クライアントコールバックのURLのリクエスト形式
BoxからクライアントコールバックのURLに送信されるPOSTリクエストは、事前コールバックのURLから応答を取得し、元のコールバックと同じデータとともに応答を同じURLに転送します。
クライアントコールバックのURL | 例 |
---|---|
2つのGETパラメータと1つのPOSTパラメータ: http://your-client-callback-url.com/?get_param1=value1&get_param2=value2 | POST data: post_param1=value1initial_callback_response |
クライアントコールバックリクエストへの応答はHTTPステータス302であり、ユーザーは正しいURLにリダイレクトされるか、ユーザーインターフェイスのHTMLにリダイレクトされます。
ほとんどの場合、URLはウェブアプリ統合のために開発された個々のAPIまたはカスタムスクリプトを指します。これは、事前コールバックのURLの結果を解析します。また、このURLは、インターネット上で一般公開する必要があることに注意してください。
統合の一般公開
Box統合を一般公開するには、統合をアプリギャラリーに掲載する必要があります。詳細については、アプリギャラリーガイドに従ってください。