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コミュニティサイトを参照してください。現在、この要素では、認証用にのみがサポートされています。

インストール

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は、エンドポイントを介して更新できます。

設定

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`	リクエストをインターセプトする関数。例については、を参照してください。基盤となるXHRライブラリは`axios.js`で、に従っています。
`responseInterceptor`	`Function`	レスポンスをインターセプトする関数。例については、を参照してください。基盤となる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

パラメータ

オプション

イベント