ファイル ハンドラー 2.0 を使用してカスタムのプレビュー、オープン、およびアクションをファイルに追加する

  • [アーティクル]

ファイル ハンドラーは、Microsoft 365 アドインの一種で、カスタムのファイルの種類をサービスに統合します。それにより、独自の形式で豊富な操作性を提供することができます。

ファイル ハンドラーを使用すると、OneDrive for Business および SharePoint ドキュメント ライブラリで、次のようなユーザー エクスペンスを実現できます。

  • カスタマイズしたファイル アイコン (独自のファイル拡張子に対応)
  • ブラウザーでの新しいファイルの作成 (独自のファイル拡張子に対応)
  • ファイルのプレビュー (独自のファイル拡張子に対応)
  • 豊富な表示/編集機能 (すべてのファイル拡張子に対応)
  • アプリを開始するカスタム アクション (すべてのファイル拡張子に対応)
  • 複数の選択およびフォルダーに対する処理のサポート (カスタム アクションのみ)

詳細については、「ファイル ハンドラーのソリューションの例」を参照してください。

重要

ファイル ハンドラーの構成は、最適なパフォーマンスを得るためにシステム全体に積極的にキャッシュされます。 構成の変更が反映されるまでに、24 - 48 時間かかります。 ファイル ハンドラーを構成する方法の詳細については、「登録する」を参照してください。

ファイル ハンドラー 2.0 の変更内容

ファイル ハンドラーの 2.0 へのアップグレードにより、SharePoint Online と OneDrive for Business の追加のシナリオに対応できるようになります。

  • より信頼性の高いファイルへのアクセス (ファイルのメタデータ、アクセス許可、および共有を含む) のための Microsoft Graph API の使用。
  • ファイル ハンドラー アドインを起動する、カスタム テキストとアイコンの付いたカスタム アクション ボタンの追加。

ファイル ハンドラーの内容

ファイル ハンドラーは、次に示すコンポーネントで構成されています。

  • ファイル ハンドラー エンドポイント。 ファイル ハンドラーのエクスペリエンスを可能にするプロバイダー ホスト型のアプリ。 このエンド ポイントは、ファイル ハンドラーに登録されたファイルの作成、プレビュー、および編集のエクスペリエンスをオプションで提供します。
  • ファイル ハンドラー マニフェスト。 Office 365 とファイル ハンドラー エンドポイントとの相互作用を定義するメタデータのセット。
  • Azure Active Directory に登録されているアプリケーション。 このアプリケーションは、Microsoft Graph を介して選択したファイルへのアクセスを承認するために使用され、ファイル ハンドラー マニフェストが登録されます。

ファイル ハンドラー エンドポイント

ファイル ハンドラー エンドポイントはクラウドでホストされるアプリであり、そのアプリが処理する種類のファイルを作成したり、プレビューしたり、開いたり、保存したりするための機能ロジックが含まれています。 Microsoft 以外のスタックなど、任意のスタックでホストできます。 ファイル ハンドラーは Azure Active Directory を使用して Office 365 リソースへのアクセスの承認を得るため、アプリケーションは Azure AD に登録する必要があります。 Azure AD へのアプリケーションの登録の詳細については、「Microsoft Graph 用のアプリの登録」を参照してください。

ファイル ハンドラーの完全な例については、「ファイル ハンドラーのソリューションの例」を参照してください。

ファイル ハンドラー マニフェスト

マニフェストは、Office 365とファイル ハンドラー エンドポイントの間の相互作用を定義します。 マニフェストは、ディレクトリ内のアプリケーション オブジェクトの addIns コレクションを使用して、Azure Active Directory に登録されます。 ファイル ハンドラー マニフェストの登録を登録または更新するには、「 方法: ファイル ハンドラーを手動で登録する」を参照してください。

ファイル ハンドラー マニフェストの例:

{
    "id": "guid",
    "type": "FileHandler",
    "properties": [
        { "key": "version", "value": "2" },
        { "key": "appIcon", "value": "{\"svg\":\"https://example.org/icon.svg\",\"png1x\":\"https://example.org/icon@1x.png\",\"png1.5x\":\"https://example.org/icon@1.5x.png\",\"png2x\":\"https://example.org/icon@2x.png\"}" },
        { "key": "fileTypeDisplayName", "value": "Contoso Document File" },
        { "key": "fileTypeIcon", "value": "{\"svg\":\"https://example.org/icon.svg\",\"png1x\":\"https://example.org/icon@1x.png\",\"png1.5x\":\"https://example.org/icon@1.5x.png\",\"png2x\":\"https://example.org/icon@2x.png\"}" },
        { "key": "actionMenuDisplayName", "value": "Contoso Actions" },
        { "key": "actions", "value": "json" }
    ]
}

それぞれのファイル ハンドラー マニフェストには、properties 配列の一部として、次に示すキー/値のペアが含まれています。

プロパティ名 型 説明
version String ファイル ハンドラーのバージョンを指定します。 この値は、2 に設定する必要があります。 ファイル ハンドラー 2.0 の場合は必須。
appIcon String、エンコードされた JSON ファイル ハンドラー アプリケーションを表すために使用される、さまざまな形式のアイコンの URL のコレクション。 省略可能。
fileTypeDisplayName String ファイルの種類についての既定のロケールでの説明。 オプション。
fileTypeIcon String、エンコードされた JSON このファイル ハンドラーで処理されるファイルの種類を表すために使用される、さまざまな形式のアイコンの URL のコレクション。 省略可能。
actionMenuDisplayName String 省略可能。 このファイル ハンドラーに関連付けられているアクションがメニューに折りたたまれるときに使用される、既定のロケールで表示される文字列。
actions String、エンコードされた JSON このファイル ハンドラー拡張機能で実装するアクションのコレクション。 詳細については、「アクションを指定する」を参照してください。 必須です。

実行時のファイル ハンドラー

ファイル ハンドラー アドインは、呼び出されたアクションのファイル ハンドラー マニフェストで指定されたエンドポイント URL を使用して呼び出されます。 何が起こるかを理解するために、ユーザーがクリックしてファイルをプレビューするシナリオを見てみましょう。 そのファイルの種類の登録済みファイル ハンドラーがある場合、Office 365は、プレビュー アクションに指定された URL に POST 要求を行うことで、ファイル ハンドラー アプリを呼び出します。 POST 要求の本文には、Office 365選択されたファイルを指定するアクティブ化パラメーターが含まれます。 newFile、open、custom などの他のアクションも同じ方法で呼び出されます。

アクティブ化パラメーター

前のシナリオでは、ファイル ハンドラー アプリでは、選択したファイルを操作するために、ファイル、テナント、Office 365 クライアントなどに関するアクティブ化パラメーターと呼ばれる詳細が必要です。 Office 365には、ユーザーのアクションに関連付けられているファイル ハンドラー エンドポイントに POST 要求で送信されるフォーム データとして、これらの詳細が含まれます。 これらのパラメーターは、MIME 型 application/x-www-form-urlencoded の要求に含まれ、要求の本文でエンコードされた URL です。

次に示すパラメーターは、アクティブ化パラメーターで提供されます。

パラメーター名 型 説明
cultureName string ユーザーの現在の表示言語のロケール識別子。
client string ファイル ハンドラーを呼び出した Office 365 アプリケーション。たとえば、"SharePoint" や "OneDrive" など。
userId string ファイル ハンドラーを呼び出したユーザーの UPN/ログイン用電子メール。
domainHint string organizations または consumers を示すドメインのヒントの文字列。
items URL の JSON 文字列のコレクション 選択したアイテムへの Microsoft Graph URL のコレクション。

これらの値は、フォーム値として POST 要求内でエンコードされます。

次に、ファイル ハンドラー エンドポイントに送信される要求の例を示します。

POST https://contoso.com/_api/filehandlers/preview
Content-Type: application/x-www-form-urlencoded

cultureName=en-us&client=OneDrive&userId=rgregg%40contoso.com&items=%5B%22https%3A%2F%2Fgraph.microsoft.com%2Fv1.0%2Fme%2Fdrive%2Fitems%2F4D679BEA-6F9B-4106-AB11-101DDE52B06E%22%5D

注: アイテム コレクションに返される URL が非常に長くなる場合があります (ただし、その長さは最大 URL 長の 2048 文字未満です)。 各 URL には、ファイル ハンドラー アプリが完全信頼のアクセス許可スコープのないコンテンツにアクセスできるように、URL に埋め込みのトークンが含まれています。 ただし、ファイル ハンドラーのエンドポイントでは、長い URL が返されることを想定し、正しく処理できるようにする必要があります。

ASP.NET 開発者の場合は、これらの値にアクセスするために、Request.Form コレクションを使用できます。次に例を示します。

var itemsJson = Request.Form["items"];
var itemUrls = JsonConvert.DecodeObject<string[]>(items);

アクティブ化パラメーターは、リクエストの着信時にサーバー側キャッシュまたは応答の Cookie によってキャッシュする必要があります。 最初のファイル ハンドラー要求では、ほとんどの場合、ファイル ハンドラー アプリは、Azure Active Directory OAuth2 エクスペリエンスを通じて accessToken を取得するために、ユーザーをリダイレクトする必要があります。 アクティブ化パラメーターは、このリダイレクトが発生する前に永続化されていないと失われることになります。

アクティブ化パラメーターを Cookie にキャッシュするためのデータ オブジェクト モデルとハンドラー メソッドの使用例は、下の「ファイル ハンドラーのソリューションの例」に示した C# または TypeScript の例を参照してください。

ファイル ハンドラーのソリューションの例

ファイル ハンドラー 2.0 によるシームレスな認証

ファイル ハンドラーでは、アクティブ化パラメーターを含む要求を受け取った後で、Microsoft Graph に API 呼び出しを実行するためのアクセス トークンを取得する必要があります。 アプリは、サインインしているユーザーのアクセス トークンを取得するために、Azure Active Directory 認証エンドポイントを呼び出す必要があります。 シングルサインオンを有効にして、ユーザーにアカウントを選択するダイアログが表示されないようにするために、login_hint パラメーターを使用して、userId アクティブ化パラメーターの値を提供できます。

一部のシナリオでは、ファイル ハンドラーによりユーザーのサインインを求める必要があります。 ファイル ハンドラーが preview アクションとして実行されている場合、IFRAME 内のサインイン エクスペリエンスにはリダイレクトできないため、そのファイル ハンドラー用のサインイン エクスペリエンスをポップアップ表示する必要があります。

ファイル ハンドラーの可用性

次の表は、ファイル ハンドラーをサポートする Office 365 サービスの一覧です。

サービス名 ファイル ハンドラー 2.0 ファイル ハンドラー 1.0
SharePoint Online 一般公開 (GA) GA
OneDrive for Business GA GA
OneDrive 個人用 使用不可 使用不可
Outlook Web App 使用不可 GA