freedom-man.com

ブログは俺のセーブポイント

Tag: box

Box API叩いてみる【Webアプリ統合編】

今回はBox APIのWebアプリ統合機能を試してみます。

Webアプリ統合とは、BoxのWebアプリに対する拡張機能になります。

BoxのWebアプリ上で任意のファイルで [その他オプション>その他の操作] から

ファイルに応じたアクションをすることが可能になります。

SalesforceだとSend To Chatterという、BoxのファイルリンクをChatter投稿するような

アプリケーションが公開されています。

 

参考URL→https://box-content.readme.io/docs/box-web-application-integrations

0. Webアプリ統合の仕組み

BoxのWebアプリで、[その他オプション>その他の操作] からアプリを選択すると

以下のようなプロンプトが表示されます。

box-api-webapp-integration-prompt-view

このプロンプトでOKを押下すると任意のエンドポイントにHTTPリクエストが飛ばされ

エンドポイント側でHTTPリクエストに応じた処理を行うことで

Boxのファイル情報を使って外部Webアプリ連携が出来るようになる仕組みです。

1. アプリケーションの設定

Boxのアプリケーションで「新しいWebアプリ統合を作成」ボタンをクリックします。

box-api-new-webapp-integration

名前と説明は必須なので適当に入力します。

box-api-webapp-integration-info

プロンプトのメッセージとプロンプトで入力する項目を設定します。

入力項目は必須ではないですが、入力値をコールバックのパラメータとして含めることができるため

入力項目を利用することで処理に柔軟性を持たせることが出来ます。

box-api-webapp-integration-prompt

コールバック構成ではコールバック先のエンドポイントやコールバックの方式を指定します。

box-api-webapp-integration-callback-info

また、ユーザ体験の項目で「ポップアップが表示されます」を選択すると

プロンプトでOKを押したあとの処理が別ウィンドウ(or別タブ)を立ち上げて

そのウィンドウ内でiframe読み込み(ホスト側はboxのWebアプリ)で呼び出されます。

 

現時点ではiframe読み込みではGETリクエストになる仕様のようなので

RESTのURLパラメータ(Get)でしかパラメータを渡すことが出来ません。

「サーバ側でのみ実行されます」はBoxがサーバ間で通信をしてくれる方式になり

この場合はRESTのPostパラメータとXML, SOAPが利用できます。

※ポップアップでもPOSTリクエストをする、という記述があるのですが確認できず…

 

コールバックパラメータの指定の方法はWebhookのときと同じです。

パラメータの値にOAuth2.0のAuthorization Code(scopeは対象のファイルアクセス権限のみ)

やfileのBase64値を含めることができます。

Authorization Codeを含める場合は、リクエストを受け取ったコールバック先が

code値をaccess_token, refresh_tokenに変換する必要があります。

(仕組み上、State値を使ったCSRF対策が出来なさそうなのが、すこし不安)

box-api-webapp-integration-callbackparams

Webhookのときと違って、こちらではBasic認証を使うことができ…そうですが

試してみたところ、プロンプト型、サーバ側での実行に関わらず入力した情報が

Authorizationヘッダに格納されておりませんでした。

リファレンスには認証の記載がなかったので利用方法が違うのか

まだ実装が完了してないのかもしれません。

box-api-webapp-integration-authentication

2. ユーザのアプリケーション設定

https://app.box.com/appsのアプリケーション画面から「マイアプリケーション」を選択

box-api-webapp-integration-apptop

自分が作成したアプリケーションの詳細画面で「Webアプリ統合」のチェックを入れれば設定完了。

box-api-webapp-integration-enabled

これで、「その他の操作」から設定したアプリケーションを実行することができます。

box-api-webapp-integration-testapp

Box API叩いてみる【ViewAPI編】

今回はBoxView APIを叩いてみます。

View APIとはPDFやOfficeドキュメントをHTMLに埋め込んで表示するためのAPIになります。

HTMLに埋め込むためにはPDFやOfficeドキュメントをHTMLにコンバートする必要があります。

 

ドキュメントのアップロード(&コンバート@バックエンド)

→ドキュメントを閲覧するためのセッション(有効期限)を作成

→発行されたセッションIDを使ってURLを生成し、iframe等で表示

というフローで実装することになります。

 

今回はApexでSalesforceの添付ファイルをコンバートし、外部公開用のURLを発行してみます。

参考URL→https://box-content.readme.io/docs/viewing-your-first-document

1. アプリケーションの作成

View API用のアプリケーションを作成します(Content APIとは別)

https://app.box.com/developers/services にアクセスして

「Boxアプリケーションの作成」をクリックします。

box-view-api-create-app

テキトーに入力して、アプリケーションを作成します。

box-view-api-create-app2

アプリケーションの詳細を開くと、View APIキーというのがあるのでコレをコピります。

box-view-api-app-info

2. ドキュメントのアップロード

アップロードにはファイルそのものをアップロードするスタイルと

外部公開されているURLを指定するスタイルの2種類があります。

今回はファイルそのものをアップロードしてみます。

ファイルそのものをアップロードする場合はContent-Type: multipart/form-dataで

送信する必要があります。

Apexからバイナリデータをmultipart/form-dataで送る方法は以下の記事を参照。

Apexからmultipart/form-data形式で送信してみる。

 

サンプルはこちら↓。Authorizationヘッダには1のView APIキーを入れてください。

curlだとこんな感じ

レスポンスはこんな感じ

PDF/OfficeドキュメントからHTMLへの変換はバックエンドで非同期で行われます。

そのため、送信直後はqueuedというステータスが返却されます。

ちなみに変換処理の完了通知手段としてwebhookを利用できるそうです(要申請)。

3. セッションの発行

アップロードされたドキュメントはそのままでは外部公開されないので

セッションを発行して外部公開できるようにします。

curlだとこんな感じ

Apexだとこんな感じ

レスポンスはこんな感じ

urls.viewの値が外部公開用のURLになります。

durationで指定した値が有効期限(minutes)になります。

PDF/OfficeドキュメントからHTMLへの変換処理が完了していない場合は

ステータスコード202が返却されます。

 

あとはurls.viewのURLを埋め込むなり通知するなりするだけでOKです。

box-view-api

?theme=light、?theme=darkのURLパラメータを付与することでビュワーのスタイルを変更できたりします。

box-view-api-theme-dark

Apex Connector Framework触ってみた。

いつの間にか、Apex Connector Framework(Custom Adapter)

Dev組織で利用できるようになっていたので触ってみました!

 

Lightning ConnectはSalesforce環境から外部のデータにアクセスする機能で

別Salesforce組織のデータや、ODataに対応したAPI経由でデータを取得し

あたかもSalesforceのオブジェクトであるかのように扱うことが出来ます。

今回のリリースではApex Connector Framework(Custom Adapter)が利用できるようになりました。

これを使うと、閲覧するデータが別Salesforce組織のデータだったり、ODataに対応していなくても

Apexから取得できる手段であればガバナを超えない範囲において

様々なデータでも取得できるようになり、Salesforceのオブジェクトのような

振る舞いを持たせることができます。

 

今回はBoxのファイルデータを閲覧する外部データソースをApex Connector Frameworkを使って

定義し、SalesforceからBoxのファイル一覧を取得してみます。

参考URL→https://developer.salesforce.com/blogs/engineering/2015/05/introducing-lightning-connect-custom-adapters.html

1. Connectionクラスを作成

サンプルは以下の通り。

sync, query, searchを実装すればOKで、

syncは「検証して同期」をしたときのオブジェクト自動作成の設定で

queryはSOQL発行時の挙動、searchはSOSL発行時の挙動をそれぞれ定義します。

 

syncで作成するオブジェクト内には「Name」「ExternalId」「DisplayUrl」を必ず指定します。

 

DataSource.QueryContext内にはSOQLの抽出フィールド、抽出対象オブジェクト、抽出条件等が

全て格納されています。

サンプルコードではSOQL発行時にgetRowsでルートフォルダ直下のファイルを全件取得して

QueryUtilsのメソッドを使ってプログラム内でフィルタリングしています。

これだと効率が悪かったりガバナに引っかかる可能性が高いので

QueryContextで予め条件を解釈してからAPIを叩くのが理想だと思われます。

 

Providerクラスからコンストラクタ経由で渡されるConnectionParamsには

外部データソースの各種設定値が格納されています。

例えば、外部データソースで指定したURL(Capability.REQUIRE_ENDPOINT)は

ConnectionParamsのendpointプロパティとして取得できるようになります。

また、認証・認可方式にBasic認証を指定すると、username, password

OAuth2.0を指定するとoauthToken

証明書を指定するとcertificateNameがそれぞれ利用できるようになります。

APIをコールするときはこれらの情報を利用することになりますが、

面倒な上にデバッグログとかで認証情報が見られる危険性があるので

サンプルのようにNamed Credentialを使う方式がオススメ。

2. Providerクラスを作成

プロバイダの認証方法として選択可能なリストを定義したり、

外部システムが対応している操作や利用するConnectionクラスを定義します。

サンプルは以下のとおり。

getAuthenticationCapabilitiesで対応している認証方式を定義します。

BoxだとOAuth2.0のみの対応なのでAuthenticationCapability.OAUTHを指定してます。

AuthenticationCapabilityのEnumは以下に定義されています。

https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_enum_DataSource_AuthenticationCapability.htm

 

getCapabilitiesでは、どの操作に対応しているかを定義し、

SOQL、SOSLに対応しているかどうかや、外部プロバイダの設定で

URLを指定できるかどうか等を指定します。

CapabilityのEnumは以下に定義されています。

https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_enum_DataSource_Capability.htm

 

最後にgetConnectionを定義して、1で作成したConnectionクラスを指定します。

3. 外部データソースの設定

正常にコンパイルされていれば、作成したProviderを指定することが出来ます。

external-datasource-custom

CapabilityにREQUIRE_ENDPOINTを指定するとこんな感じでURLが表示されます。

今回外部データソースの認証機構は利用しないので「匿名」のままで。

作成した後は通常通り「検証して同期」すればOK。

オブジェクトが出てこない場合は、Connectionのsyncメソッドの記述が間違っている可能性大。

4. データの閲覧

Boxのファイル一覧だとこんな感じに表示されます。

external-datasource-custom-entries

補足

Connection側を変更したらProvider側も再コンパイル(=空更新)する必要があります。

再コンパイルしないとこんなエラーが発生します。

external-datasource-error

所感

OData Providerを立てなくても外部リソースにアクセスしてSalesforceオブジェクトのように

扱えるのは強力な機能だと思います。

ちゃんとしたもの作りこむにはSOQLに応じて呼ぶAPIを変えるとか、ガバナ考慮するとか

色々と泥臭い処理を入れていくようになると思いますが、

一回作っておけば、色んな組織にコピペして使いまわせて、かなり便利なイメージ。

Box API叩いてみた【イベント通知編】

前回に引き続きBox APIを叩いていきます。

今回はBox Content APIのイベント通知機能について説明していきます。

Box Content APIではファイルのアップロードや削除等の各イベントの発生に対して

任意の処理を実行することが出来ます。

イベント発生の都度、任意のエンドポイントに通知するWebhookの方法と

イベントのストリームをロングポーリングして取得する方法の2つを利用することが出来ます。 Continue reading

Box API叩いてみた【ContentAPI編】

BoxはDropbox的なストレージサービスで、Businessプラン以上は容量無制限だったり

文書の暗号化が標準サポートだったりする、エンプラ向けなサービスになります。

ということで、今回はBoxのAPI(ContentAPI)の使い方を説明していきます!

SalesforceからBox APIを叩くサンプルを作っていきます。

1. アプリケーションの設定

OAuth2.0を利用するので、twitterやfacebook等のようにアプリケーションを設定します。

developersのサイトでログインします。

box-developer-login

boxアカウント持っている場合は、MyAppsからログインして

持っていない場合はSignUpで無料の開発者用のアカウントを作成する必要があります。

ログイン後、初めてアプリケーションを作成する場合は以下の画面が表示されるので、

そのまま「はじめに」をクリックします。(これ日本語訳が…)

box-api-app-firstapp

アプリケーション名を設定して、「アプリケーションの作成」をクリックします。

ラジオボタンは「Boxコンテンツ」のままでOK。

box-api-app-create

 

完了すると以下の画面になるので、そのまま「アプリケーションの構成」をクリックします。

box-api-app-complete

そうすると、アプリケーションの詳細画面が表示されます。

色々と設定できるのですが、大事なところはOAuth2パラメータの部分になります。

box-api-app-oauth2

BoxのAPIの認証はOAuth2.0のAuthorization Code Grantになるので

redirect_uriを設定し、client_id、client_secretをメモっておきます。

redirect_uriに関しては必須項目になりますがURI形式であればOKなので

https://localhostとかを入力して「アプリケーションの保存」で設定を保存します。

2. Salesforceの設定

ApexのSDKもあるみたいですが(dhoechst/ApexBox)、今回はNamed Credentialを使って叩いてみます。

OAuth danceをイチから実装しなくて良いから楽なんですよねー。

ということで、以下のように認証プロバイダを設定します。

box-api-sfdc-connect-app

  • 承認エンドポイントURL → https://app.box.com/api/oauth2/authorize
  • トークンエンドポイントURL → https://app.box.com/api/oauth2/token
  • コンシューマ鍵と、コンシューマの秘密
    → それぞれ1のアプリ作成時にメモったclient_id, client_secret

と、それぞれ値をセットします。

 

発行された「コールバックURL」はBoxのアプリケーションのredirect_uriにセットしておきます。

Named Credentialは以下のように設定。

box-api-sfdc-named-credential

  • URL → https://api.box.com
  • 認証プロバイダ → さっき作ったやつ
  • ID種別 → 「ユーザ」or「指定ユーザ」
  • 認証プロトコル → OAuth2.0

と、設定します。

今回は設定が楽な「指定ユーザ」の方で進めてます。

保存時に認証フローを開始にチェックをつけて、「保存」ボタンを押下すると

OAuth2.0のフローが始まるので適切なアカウントで認証/認可します。

3. Apexからコールアウトしてみる

設定が完了したら、以下のApexコードを叩きます。(ルートフォルダ情報の取得)

いい感じにJSONが返って来てたら成功です!

補足1. BoxのContentAPIの認証方式について

前述のようにOAuth2.0 Authorization Code Grant一択になります

MobileやJavaScriptなどのフロントエンドのアプリ向けにはImplicit Grant必須だと思うんですが

何故か対応しておらず、MobileのSDKはclient_secretを

アプリ側にベタに設定しちゃうような作りになっているんですが大丈夫なんですかね…。

CORSも一応対応しているようなので、なおさらImplicit Grantに対応してても良い気がします。

補足2. 開発者用トークンについて

Boxのアプリケーションの設定画面で

OAuth2パラメータのセクションで「開発者トークン」を発行できます。

こちらを利用すると、OAuth2.0のフローを踏まずに

その開発者のユーザコンテキストでaccess_tokenを発行することができます。

ちょうどtwitterにも開発者のアカウントの

永続的なaccess_tokenを発行できる機能がありますがアレと同じです。

box-api-app-accesstoken

APIの動きを確認したいときはかなり便利ですが

有効期限付きなので、期限が切れたら都度再発行する必要があります。

補足3. アプリケーションの削除について

Boxのアプリケーションは削除できないっぽいです。

削除ボタンが見つからないし、以下のようなサポートへの問い合わせが…。

https://support.box.com/hc/communities/public/questions/200268938-As-a-developer-Remove-delete-application-

© 2017 freedom-man.com

Theme by Anders NorenUp ↑