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


※ 2015/09  File Handler は GA しました。

Office 365 API

(Skype API は こちら)

こんにちは。

今週は、Office 365 File Handler を紹介します。

今後、Office 365 では、さまざま形で 3rd party のカスタム アプリのプラグインが可能になります。
ここで紹介する Office 365 File Handler を使用すると、印刷フォーマットや CAD 図面など、独自の拡張子を持ち、独自の Preview 機能や編集 (Edit) 機能を提供するアプリケーションを Office 365 に登録できます。

なお、現在は、SharePoint、OneDrive for Business、Outlook Web App の添付ファイルに対応しています。

 

File Handler の登録 (Registration)

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 application and/or web 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 も登録しておいてください。)

Permission には、Office 365 unified api の [Read and write files that the user selects] を付与します。

File Handler の動作は、application property (app manifest) に addIns プロパティとして設定します。
例えば、下記では、拡張子 .mat のファイルの場合、Preview として https://handlersample.azurewebsites.net/preview.php、Open として https://handlersample.azurewebsites.net/open.php の Web が呼び出されます。(id には、一意の GUID を設定してください。)

{
  "odata.metadata": "https://graph.windows.net/...",
  "odata.type": "Microsoft.DirectoryServices.Application",
  "objectType": "Application",
  "objectId": "cd9e5bdb-41d7-4cc9-badf-8f200d84cd19",
  "deletionTimestamp": null,
  "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"
        }
      ]
    }
  ],
  "appId": "c58c6ca6-1dd6-4314-bcdd-bf5671c1d659",
  "appRoles": [],
  . . .

}

この設定変更をおこなうには、通常、Azure Portal を使って [Download Manifest] と [Uploda Manifest] を使用すれば良いのですが、現段階では api-version として beta を指定する必要があるため、Graph API を使用して更新してください
具体的には、下記の通り PATCH コマンドを使って addIns プロパティを設定すると良いでしょう。(下記の access token の取得方法は「Azure Active Directory の Graph API の活用」を参照してください。Application の objectId は Graph Explorer などを使用して確認できます。)

PATCH https://graph.windows.net/o365demo01.onmicrosoft.com/
applications/cd9e5bdb-41d7-4cc9-badf-8f200d84cd19/
?api-version=beta
Content-Type: application/json
Authorization: BEARER 

{
  "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"
        }
      ]
    }
  ]
}

 

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 できます。

Comments (0)

Skip to main content