Office 365 File Handler (カスタム ファイルのプラグイン)


※ 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=beta
Content-Type: application/json
Authorization: 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.6
Content-Type: application/json
Authorization: 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) は、下記の概念で実装 (プログラミング) します。

  1. Office 365 API 入門」で紹介している手順で access token を取得します。(上述でコピーした client id, client secret を使用します。resource には、下記 resourceid で渡される SharePoint Online の resource 名を指定します。)
    この HTTP Flow では、通常、SignIn 画面が表示されますが、今回は、既に Web Browser でログイン済の状態で使用されるため、SignIn 画面は表示せずにログインしているユーザーの access token が取得できます。
  2. 後述する 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-urlencoded
Accept:text/html, application/xhtml+xml, */*
Connection:Keep-Alive

resourceid=https%3A%2F%2Fo365demo01.sharepoint.com&culturename=ja-JP
&fileget=https%3A%2F%2Fo365demo01.sharepoint.com%2F_vti_bin%2Fwopi.ashx%2Ffiles%2F10e5a085f9194d8fb384e39e73156cea%2Fcontents%3Faccess_token%3DeyJ0eXAiOi...
&fileput=https%3A%2F%2Fo365demo01.sharepoint.com%2F_vti_bin%2Fwopi.ashx%2Ffiles%2F10e5a085f9194d8fb384e39e73156cea%2Fcontents%3Faccess_token%3DeyJ0eXAiOi...
&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 token
if(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/) に画面を変更

 

Comments (0)

Skip to main content