Content Open With - Box Dev Docs

日本時間 2021 年 12 月 22 日をもって、新規のお客様に対するOpenWith UI Element のサポートは終了しました。

Box Content Open With UI Element を使用すると、開発者は、Box に保存されているコンテンツをパートナーアプリケーションまたはローカルのデスクトップで開くためのドロップダウンを埋め込むことができます。この Element は、有効化された統合に関する情報を Box API を使用して取得し、パートナーのサービスを呼び出します。その後、ユーザーはこれらのサービスで操作を行うと、編集したコンテンツは Box に自動的に保存されます。 Open With Element に含まれる統合には、Google Suite および Box Edit があります。Google Suite の統合の詳細については、Box コミュニティサイトを参照してください。現在、この要素では、認証用にApp Userのみがサポートされています。

インストール

NPM または Box CDN 経由で Box UI Elements をインストールする方法は、こちらを参照してください。

Box Edit

Box Edit では、Platform アプリケーションに統合するために追加の設定が必要です。Box Edit は、デスクトップアプリケーションのBox Toolsを使用してコンテンツをローカルで開きます。

リクエストでは (httpsドメインからの) セキュアな接続を使用する必要があります。
アプリケーションのドメインは、Box Tools で許可する必要があります。手順については、こちらを参照してください。理想的なワークフローでは、Box Tools もインストールされるインストーラにこれらの手順をバンドルします。
Safari では、Box Tools に接続するためにブラウザの機能拡張が必要です。詳細については、こちらを参照してください。

G Suite

Box for G Suite の統合を使用するには、有効な G Suite アカウントが必要です。ユーザーの G Suite と Box アカウントを接続するには、App User のexternal_app_user_idを、ユーザーの G Suite アカウントに関連付けられたメールアドレスに更新する必要があります。 App User のexternal_app_user_idは、PUT /users/:idエンドポイントを介して更新できます。

設定

Open With UI Element を使用する前に、アプリケーションを許可し、Box API エンドポイントを使用して App User のために統合を有効にしておく必要があります。

アプリケーションのアクティブ化

「Open With」UI Element は、Box Platform を使用して構築するすべての開発者が使用できます。インスタンスに対してこの要素をアクティブ化するには、開発者コンソールでアプリケーションに [統合を有効化] スコープを追加します。

アプリケーションは、API コールに対してアクティブ化されたら、会社での再認証が必要になります。この操作を実行する手順については、こちらを参照してください。

使用可能な統合のリストの取得

アプリ統合をユーザーに割り当てるには、まず、使用可能な統合のリストを取得します。このGETリクエストは、次のcURLリクエストを使用して実行できます。

curl -X GET https://api.box.com/2.0/app_integrations \
    -H 'Authorization: Bearer [ACCESS_TOKEN]'

{
  "next_marker": null,
  "entries": [
    { "type": "app_integration", "id": "10897" },
    { "type": "app_integration", "id": "1338" },
    { "type": "app_integration", "id": "13418" },
    { "type": "app_integration", "id": "3282" }
  ],
  "limit": 100
}

アプリ統合 ID を使用して、指定したユーザーに統合を割り当てます。

特定の統合の取得

ID に基づいて、特定の統合に関する追加情報を取得するには、次の GET リクエストを実行できます。

curl -X GET \
    https://api.box.com/2.0/app_integrations/[APP_INTEGRATION_ID] \
    -H 'Authorization: Bearer [ACCESS_TOKEN]'

{
  "type": "app_integration",
  "id": "10897",
  "app": {
    "type": "app",
    "id": "336417"
  },
  "name": "Edit with G Suite",
  "description": "Securely manage your Google Docs, Sheets and Slides in Box",
  "executable_item_types": ["file"],
  "restricted_extensions": ["docx", "gdoc", "xlsx", "gsheet", "pptx", "gslides", "gslide"],
  "scoped_to": "parent"
}

ユーザーへの統合の追加

有効な App User にアプリ統合を追加するには、以下の 3 つの情報が必要です。

有効なサービスアカウントアクセストークン
統合を割り当てる App User の ID
ユーザーに割り当てるアプリ統合の ID

アプリ統合に関する情報を取得するための前述の 2 つのリクエストは、有効な開発者トークンなど、任意の有効なトークンを使用して実行できますが、アプリ統合を追加および削除するには、有効なサービスアカウントのアクセストークンが必要です。開発者トークンを使用すると404 Not Foundエラーが発生します。

アプリ統合を App User に割り当てるには、次のPOSTリクエストを実行できます。

curl -X POST https://api.box.com/2.0/app_integration_assignments \
    -H 'Authorization: Bearer [SERVICE_ACCOUNT_TOKEN]' \
    -d '{
      "assignee": {
        "type": "user",
        "id": "[APP_USER_ID]"
      },
      "app_integration": {
        "type": "app_integration",
        "id": "[APP_INTEGRATION_ID]"
      }
    }'

{
  "type": "app_integration_assignment",
  "id": "72048301",
  "assignee": {
    "type": "user",
    "id": "6084519920"
  },
  "app_integration": {
    "type": "app_integration",
    "id": "3282"
  }
}

JSON レスポンスに含まれる ID は、割り当て後にアプリ統合を管理するために使用できるため、アプリケーションで保存する必要があります。

ユーザーからの統合の削除

App User からアプリ統合を削除するには、有効なサービスのアクセストークンと、前の手順で取得したアプリ統合割り当て ID を使用して次のリクエストを実行できます。

curl -X DELETE https://api.box.com/2.0/app_integration_assignments/[APP_INTEGRATION_ASSIGNMENT_ID] \
    -H 'Authorization: Bearer [SERVICE_ACCOUNT_TOKEN]'

204 No Content

サンプル HTML

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <title>Box Content Open With Demo</title>

    <!-- Latest version of the open with css for your locale -->
    <link rel="stylesheet" href="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/openwith.css" />
  </head>
  <body>
    <div class="container" style="height:600px"></div>
    <!-- Latest version of the open with js for your locale -->
    <script src="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/openwith.js"></script>
    <script>
      var fileId = "123";
      var accessToken = "abc";
      var contentOpenWith = new Box.ContentOpenWith();
      contentOpenWith.show(fileId, accessToken, {
        container: ".container",
      });
    </script>
  </body>
</html>

デモ

Open With の例

コンテンツエクスプローラと Open With の例

アクセストークン上記のデモは、デモの [JS] タブで有効なアクセストークンを指定しなければ、十分に機能しない可能性があります。Open With Element の場合は、有効なサービスアカウントアクセストークンを指定する必要があります。

認証

UI Element は認証に依存しない方法で設計されているため、Box アカウントを持つユーザー (管理対象ユーザー) と Box 以外のアカウントを持つユーザー (App User) のどちらに UI Element を使用するかどうかに関係なく、UI Element を使用するのに特別な設定は必要ありません。その理由は、UI Element は認証のために「トークン」を受け取ることのみを予期しており、Box にはトークンの生成方法として OAuth と JWT の 2 つがあるからです。

認証方法の選択について確認する

スコープ

ダウンスコープされたトークンを使用して統合を実行するには、item_execute_integrationスコープに加えて、使用する特定の統合で必要となるスコープを含める必要があります。

Google: 親フォルダに対するitem_readwrite
Adobe: root_readwrite
Box Edit: 親フォルダに対するitem_readwrite
Box Edit 単一ファイルコラボレーション: ファイルに対するitem_readwrite

スコープの詳細については、こちらを参照してください。

API

const { ContentOpenWith } = Box;
const contentOpenWith = new ContentOpenWith();

/**
 * Shows the content open with element.
 *
 * @param {string} fileId - The root file id
 * @param {string} accessToken - Box API access token
 * @param {Object} [options] - Options
 * @return {void}
 */
contentOpenWith.show(fileId, accessToken, options);

/**
 * Hides the content open with element, removes all event listeners,
 * and clears out the
 * HTML.
 *
 * @return {void}
 */
openWith.hide();

/**
 * Adds an event listener to the content open with element. Listeners should be added
 * before calling show() so no events are missed.
 *
 * @param {string} eventName - Name of the event
 * @param {Function} listener - Callback function
 * @return {void}
 */
contentOpenWith.addListener(eventName, listener);

/**
 * Removes an event listener from the content open with element.
 *
 * @param {string} eventName - Name of the event
 * @param {Function} listener - Callback function
 * @return {void}
 */
contentOpenWith.removeListener(eventName, listener);

/**
 * Removes all event listeners from the content open with element.
 *
 * @return {void}
 */
contentOpenWith.removeAllListeners();

パラメータ

パラメータ	型	説明
`fileId`	String	Box ファイル ID。統合の実行対象となるファイルの ID です。
`accessToken`	String	使用する Box API アクセストークン。このトークンには、上記のフォルダに対する読み取り/書き込みアクセス権限が必要です。このトークンのために渡される値は、エクスプローラの表示中は有効期限切れにならないことが前提となっています。
`options`	Object	省略可能なオプション。詳細は以下を参照してください。たとえば、`contentExplorer.show(FOLDER_ID, TOKEN, {canDelete: false})`を使用すると、削除オプションが非表示になります。

オプション

パラメータ	型	説明
`dropdownAlignment`	`left	right`	[開く] ボタンに対するドロップダウンの位置を決定します。デフォルトは`right`です。
`boxToolsName`	`String`	この文字列は、「このファイルをデスクトップで開くには Box Tools をインストールしてください」というメッセージ内の Box Tools の名前に置き換わります。
`boxToolsInstallUrl`	`String`	この URL は、「このファイルをデスクトップで開くには Box Tools をインストールしてください」というメッセージ内でリンクされている、デフォルトの Box インストール手順の代わりに使用されます。
`onExecute`	`Function`	統合の呼び出しが試行されたときに実行されるコールバック。
`onError`	`Function`	エラーが発生したときに実行されるコールバック。
`requestInterceptor`	`Function`	リクエストをインターセプトする関数。例については、この CodePenを参照してください。基盤となる XHR ライブラリは`axios.js`で、インターセプタでは同様のアプローチに従っています。
`responseInterceptor`	`Function`	レスポンスをインターセプトする関数。例については、この CodePenを参照してください。基盤となる XHR ライブラリは`axios.js`で、インターセプタでは同様のアプローチに従っています。

現在、onErrorイベントとonExecuteイベントは、既知のバグの影響を受けています。一時的な回避策としてopenWith.addListener('execute', callback)およびopenWith.addListener('error', callback)を使用することをお勧めします。

イベント

イベント名	イベントデータ	説明
`execute`	統合 ID	統合の呼び出しが実行されたときに発生します。
`error`	エラー	エラーが発生したときに発生します。

​インストール

​Box Edit

​G Suite

​設定

​アプリケーションのアクティブ化

​使用可能な統合のリストの取得

​特定の統合の取得

​ユーザーへの統合の追加

​ユーザーからの統合の削除

​サンプル HTML

​デモ

​Open With の例

​コンテンツエクスプローラと Open With の例

​認証

認証方法の選択について確認する

​スコープ

​API

​パラメータ

​オプション

​イベント

インストール

Box Edit

G Suite

設定

アプリケーションのアクティブ化

使用可能な統合のリストの取得

特定の統合の取得

ユーザーへの統合の追加

ユーザーからの統合の削除

サンプル HTML

デモ

Open With の例

コンテンツエクスプローラと Open With の例

認証

スコープ

API

パラメータ

オプション

イベント