※ 2015/09 File Handler は GA しました。
こんにちは。
Office 365 では、さまざま形で 3rd party のカスタム アプリのプラグインが可能です。
ここで紹介する Office 365 File Handler を使用すると、印刷フォーマットや CAD 図面など、独自の拡張子を持ち、独自の Preview 機能や編集 (Edit) 機能を提供するアプリケーションを Office 365 に登録できます。
SharePoint、OneDrive for Business、Outlook Web App の添付ファイルに対応しています。
注意 : ただし、Office 365 が既に関連付けているファイル形式 (Excel, Word 等) には適用できません。
(2017/05 追記) 新しい File Handler v2 では、newFile, open, preview などの既存の Action 以外の Custom Action (下図) が追加できます。(Custom Action は、既存のファイルやフォルダーすべてに適用することもできます。(ただし、2017 年 5 月現在の Preview では、Office 365 の日本のデータセンターでは使用できないので注意してください。)
また、Azure AD v2 endpoint による Microsoft Account (Consumer 用の OneDrive) も利用可能です。(ただし、2017 年 5 月現在では、まだ v2 endpoint との統合はできませんので、もう少々お待ちください。)
File Handler の登録 (Registration) – v1 の場合
Office 365 (Azure AD) を使ったアプリケーション構築経験がある方にとっては、概念や動作は、それほどむずかしいものではありません。
Office 365 File Handler を Azure AD (Azure Active Directory) の Application として登録し、Application の Manifest (applicaiton properties) に Add-in に関する情報 (例えば、Preview 用の URL など) を設定します。
まず、使用する Office 365 のテナントの Azure AD 管理画面 (Azure Portal) を表示し、Application を登録します。(手順詳細は「Native Application (Mobile App) で Azure Active Directory に Login するプログラミング」を参照してください。)
この際、[Web app / API] (下図) として登録をおこなってください。(今回は Auzre Portal を使用して登録しますが、「Azure Active Directory の Common Consent Framework」で解説したように、Application を Multi-tenant で構築し、Consent UI を使って配布できます。)
また、Key (client secret) の作成もおこない、client id, client secret をコピーしておきましょう。(また、redirect uri として、この後 使用する Preview, Open の Url も登録しておいてください。)
Required permissions には、[Microsoft Graph] の [Have full access to all files user can access] を付与します。
File Handler を登録するには、Graph API を使用します。(下記の access token の取得方法は「Azure Active Directory の Graph API の活用」を参照してください。下記の通り、あらかじめ、登録した Application の objectId を取得しておきます。)
なお、現段階では api-version として beta を指定する必要があります。
例えば、下記では、拡張子 .mat のファイルの場合、Preview として https://handlersample.azurewebsites.net/preview.php、Open として https://handlersample.azurewebsites.net/open.php の Web が呼び出されます。(id には、一意の GUID を設定してください。)
PATCH https://graph.windows.net/o365demo01.onmicrosoft.com/applications/cd9e5bdb-41d7-4cc9-badf-8f200d84cd19/?api-version=betaContent-Type: application/jsonAuthorization: BEARER xxxxxxxxxx{ "addIns": [{ "id": "dc75dbe2-7fab-4ee4-9857-d563ce54a59b", "type": "FileHandler", "properties": [{ "key": "extension", "value": "mat"},{ "key": "fileIcon", "value": "https://handlersample.azurewebsites.net/icon.png"},{ "key": "openUrl", "value": "https://handlersample.azurewebsites.net/open.php"},{ "key": "previewUrl", "value": "https://handlersample.azurewebsites.net/preview.php"} ]} ]}
File Handler の登録 – v2 の場合 (2017/05 追記)
上述の Azure AD へのアプリケーション登録までは同じです。
File Handler v2 の File Handler では、api-version を 1.6 以降にして、下記の通り Graph API を発行します。(Action の登録方法が異なっている点に注意してください。)
ここでは、”Add to ZIP file – debug” という Custom Action をすべてのファイルとフォルダーに登録しています。(type プロパティを “custom” に設定しています。)
PUT https://graph.windows.net/o365demo01.onmicrosoft.com/ applications/cd9e5bdb-41d7-4cc9-badf-8f200d84cd19/addIns ?api-version=1.6Content-Type: application/jsonAuthorization: BEARER xxxxxxxxxx{ "value": [{ "id": "4B1F5105-A892-4DF7-9CDA-1060EED73F24", "type": "FileHandler", "properties": [{ "key": "actions", "value": "[{"type":"custom","displayName":"Add to ZIP file - debug","url":"https://localhost:44362/filehandler/compressFiles","availableOn":{"file":{},"folder":{},"allowMultiSelect":true}}]"},{ "key": "version", "value": "2"} ]},{ "id": "27CCFFE9-4155-4FDF-95AC-DAFDD4014B15", "type": "FileHandler", "properties": [{ "key": "version", "value": "2"},{ "key": "fileTypeDisplayName", "value": "Markdown (debug)"},{ "key": "fileTypeIconUrl", "value": "https://localhost:44362/images/markdown.png"},{ "key": "actions", "value": "[{"type":"newFile","url":"https://localhost:44362/filehandler/newFile","availableOn":{"file":{"extensions":[".gfm"]}}},{"type":"open","url":"https://localhost:44362/filehandler/open","availableOn":{"file":{"extensions":[".gfm"]}}},{"type":"preview","url":"https://localhost:44362/filehandler/preview","availableOn":{"file":{"extensions":[".gfm"]}}}]"} ]} ]}
Application の構築 (Programming)
上述のプレビュー用の Web ページ (preview.php), 編集用の Web ページ (open.php) は、下記の概念で実装 (プログラミング) します。
- 「Office 365 API 入門」で紹介している手順で access token を取得します。(上述でコピーした client id, client secret を使用します。resource には、下記 resourceid で渡される SharePoint Online の resource 名を指定します。)
この HTTP Flow では、通常、SignIn 画面が表示されますが、今回は、既に Web Browser でログイン済の状態で使用されるため、SignIn 画面は表示せずにログインしているユーザーの access token が取得できます。 - 後述する URL (fileget, fileput) に対して、上記の access token を付与してアクセスします。これにより、ファイルの内容の取得や変更が可能です。
プレビュー用の Web ページ (preview.php), 編集用の Web ページ (open.php) が表示される際、下記の POST 要求が実行されます。プログラム側では、ここで渡された fileget, fileput の URI を使用して選択されたファイルの中身の取得と変更が可能です。(ファイルの内容は application/octet-stream として取得できます。)
なお、下記の通り、fileget, fileput 共に Query string として access token が付与されていますが、これとは別に、上述 1 の通りログイン ユーザーの access token を取得して、Authorization ヘッダーに設定する必要があるので注意してください。
Content-Type:application/x-www-form-urlencodedAccept:text/html, application/xhtml+xml, */*Connection:Keep-Aliveresourceid=https%3A%2F%2Fo365demo01.sharepoint.com&culturename=ja-JP&fileget=https%3A%2F%2Fo365demo01.sharepoint.com%2F_vti_bin%2Fwopi.ashx%2Ffiles%2F10e5a085f9194d8fb384e39e73156cea%2Fcontents?access_token=eyJ0eXAiOi...&fileput=https%3A%2F%2Fo365demo01.sharepoint.com%2F_vti_bin%2Fwopi.ashx%2Ffiles%2F10e5a085f9194d8fb384e39e73156cea%2Fcontents?access_token=eyJ0eXAiOi...&fileid=10e5a085-f919-4d8f-b384-e39e73156cea&client=Sharepoint
例えば、「Office 365 API – PHP, Node.js, etc での使用」と同じ方法でプログラミング (access token の取得) をおこなって、今回、下記の通り preview.php を実装してみましょう。
このコードでは、access token を取得後、fileget の URI (https://o365demo01.sharepoint.com%2F_vti_bin/wopi.ashx/files/10e5a085f9194d8fb384e39e73156cea/contents?access_token=eyJ0eXAiOi…) を使用してファイルの内容を取得し、取得した内容 (テキストと仮定します) をそのまま Preview 画面上 (preview.php) にテキストで表示しています。
<?php// This time we use in-memory session,// but please change if needed. (scale not ready)session_start();if(isset($_POST['fileget'])) { $_SESSION['fileget'] = $_POST['fileget'];}// When auth code is supplied, get access tokenif(isset($_GET['code'])) { $authreq = curl_init();curl_setopt($authreq, CURLOPT_URL,'https://login.microsoftonline.com/common/oauth2/token'); curl_setopt($authreq, CURLOPT_POST, true);curl_setopt($authreq, CURLOPT_HTTPHEADER,array('Content-Type: application/x-www-form-urlencoded')); curl_setopt($authreq, CURLOPT_POSTFIELDS, http_build_query(array('grant_type' => 'authorization_code','code' => $_GET['code'],'client_id' => 'c58c6ca6-1dd6-4314-bcdd-bf5671c1d659','client_secret' => 'XNa7R...','redirect_uri' => 'https://handlersample.azurewebsites.net/preview.php', ))); curl_setopt($authreq, CURLOPT_RETURNTRANSFER, true); curl_setopt($authreq, CURLOPT_SSL_VERIFYPEER, false); // temporary $authres = json_decode(curl_exec($authreq)); curl_close($authreq);$_SESSION['access_token'] = $authres->access_token;}if(isset($_SESSION['access_token'])) { // If all okay, get file contents ! $datareq = curl_init(); curl_setopt($datareq, CURLOPT_URL, $_SESSION['fileget']); curl_setopt($datareq, CURLOPT_HTTPHEADER,array('Authorization: Bearer '.$_SESSION['access_token'])); curl_setopt($datareq, CURLOPT_RETURNTRANSFER, true); curl_setopt($datareq, CURLOPT_SSL_VERIFYPEER, false); // temporary$result = curl_exec($datareq); curl_close($datareq);header('Content-type: text/html; charset=utf-8'); echo '<font style="size:large;color:red;">'; echo $result; echo '</font>';}else { // If fisrt access, jump to get auth code ! header('Location: https://login.microsoftonline.com/common/oauth2/authorize'.'?response_type=code'.'&client_id=c58c6ca6-1dd6-4314-bcdd-bf5671c1d659'.'&resource='.urlencode('https://o365demo01.sharepoint.com').'&redirect_uri='.urlencode('https://handlersample.azurewebsites.net/preview.php').'&prompt=none');}?>
補足 : この Preview ウィンドウは ifarme として表示されるので注意してください。
例えば、信頼済サイトで、別のゾーン (インターネット サイト) のページに iframe で遷移するとエラーになるため、ブラウザーのこれらの設定にも注意してください。
open.php も同様に、[編集] (Edit) ボタンが押された際に表示されるページの内容をプログラム コードで記述できます。
動作確認
では、実際の動きを確認してみましょう。
上述の通り、現時点では SharePoint Online のみが対応しています。
testfile.mat というテキスト ファイルを新規作成して SharePoint Online のドキュメント ライブラリーに保存 (アップロード) します。
まず、ドキュメント ライブラリーのファイルを表示すると、下図の通り、アイコンとして上記で指定したイメージ (上記の icon.png) が表示されます。
ファイル名の横の […] をクリックすると Preview ウィンドウが表示されますが、このウィンドウには、下図の通り、取得したテキスト ファイルの中身 (内容) が赤字で表示されます。
上図で [編集] (Edit) をクリックすると、同様に open.php が呼び出されます。
ここでは File Handler を単体で作成しましたが、上述の通り File Handler は Application の一部 (property) として登録されるため、実際の開発では、Office 365 API を使用した Application 本体のさまざま機能を提供して Office 365 にプラグインできるようにしておき、その機能の一部として File Handler (拡張子に応じた動作定義) を組み込んでおくと良いでしょう。
独自の印刷フォーマットや CAD 図面など、Office (Office 365) では提供していないカスタムのファイル フォーマットを自由にプラグインし、その動作を Add-in できます。
※ 変更履歴
2017/05 File Handler v2 の Preview リリースに伴い、v2 に関する追加点・変更点を追記
2017/05 新 Azure Portal (https://portal.azure.com/) に画面を変更
Categories: Uncategorized
1 reply»