アプリから Office ファイルを開く

適用対象: 開発者

Microsoft Graph DriveItem メタデータと Microsoft 365 でサポートされている Office 起動パターンを使用して、SharePoint Embedded アプリから Office ファイルを開きます。

最初に ファイルのアップロード、ダウンロード、管理 を完了して、アプリに起動するファイルが含まれます。

Office エクスペリエンスを理解する

SharePoint Embedded Office ファイル エクスペリエンスは、Microsoft 365 ファイル エクスペリエンスと同様に機能します。 サポートされるエクスペリエンスは次のとおりです。

  • Office for the webで Office ドキュメントを開く。
  • Office デスクトップ クライアントで Office ドキュメントを開く。
  • ファイルの表示と編集。
  • Word、Excel、PowerPoint ファイルの自動保存。
  • Office ドキュメントのバージョン履歴。
  • コオーサリング。
  • 共有および共有可能なリンク。
  • コメントとメンション(文書化された制限付き)。
  • ファイルをアプリに関連付ける Office クライアントの階層リンク。

注:

アーカイブされたコンテナーに格納されているドキュメントは表示またはアクセスできません。 アプリは、適切なエラーを表示し、コンテナーの再アクティブ化などの次の手順でユーザーを誘導することで、アーカイブされた状態を処理する必要があります。

前提条件

Office ファイルを起動する前に、次のことを確認してください。

  • ファイルは SharePoint Embedded コンテナーに格納されます。
  • アプリは、ファイルの DriveItem メタデータを読み取ることができます。
  • ユーザーには、ファイルを表示または編集するためのアクセス許可があります。
  • ファイルの種類は、ターゲット Office クライアントでサポートされています。
  • アプリは、ブラウザーのリダイレクトまたは新しいウィンドウの動作を処理します。

DriveItem Web URL を取得する

アプリが Microsoft Graph から DriveItem を取得すると、応答に webUrlを含めることができます。

サポートされている Office ファイルの種類の場合、webUrlは、ドキュメントをOffice for the webで開く URL を指します。

サポートされている Office Web URL には、次の図形があります。

https://host/:w:r/contentstorage/sitecollection/_layouts/15/doc2.aspx?sourcedoc=guid&file=filename.docx&action=default&mobileredirect=true

要求の詳細については、「 DriveItem リソースを取得する」を参照してください。

Office for the webを起動する

アプリがブラウザーで Office を開く必要がある場合は、DriveItem webUrl を使用します。

  1. 選択したファイルの DriveItem を読み取ります。
  2. 応答に webUrlが含まれていることを確認します。
  3. ブラウザー のタブ、ウィンドウ、またはアプリで制御されるナビゲーション 画面で URL を開きます。
  4. 編集後にユーザーが戻ることができるように、アプリ コンテキストを保持します。
  5. ファイルのアクセス許可とコンテナー メンバーシップを確認して、アクセス拒否エラーを処理します。

注:

Office ファイルは、ユーザーが SharePoint Embedded に格納されているWord、Excel、およびPowerPointファイルを編集するときに自動保存を使用します。

既定の起動エクスペリエンスを構成する

既定では、Office URL には action=defaultが含まれます。

モードを強制するには、次のパターンでクエリ パラメーターを更新します。

System.UriBuilder builder = new System.UriBuilder(webUrl);
System.Collections.Specialized.NameValueCollection queryDictionary = System.Web.HttpUtility.ParseQueryString(builder.Query);
queryDictionary["action"] = "view";
builder.Query = queryDictionary.ToString();
string modifiedWebUrl = builder.ToString();

次のコマンドを使用します:

  • action=view 読み取り専用表示用。
  • action=edit ユーザーが編集アクセス許可を持っている場合の編集。
  • action=default Office が既定の動作を選択する必要がある場合。

サポートされている action 値については、「 Web アプリケーション Open Platform Interface アクション」を参照してください。

Office デスクトップ クライアントでファイルを開く

アプリでデスクトップ クライアントを直接開く必要がある場合は、Office URI スキームを使用します。

形式は次のとおりです。

<scheme-name>:<command-name>|<command-argument-descriptor>|<command-argument>

一般的な値は次のとおりです。

セグメント 値
スキーム名 ms-word、ms-excel、または ms-powerpoint
[ファイル ビューを開く] コマンド ofv
[ファイルの編集] コマンドを開く ofe
URL 記述子 u

例:

ms-word:ofv|u|https://contoso.com/document.docx
ms-powerpoint:ofe|u|https://contoso.com/presentation.pptx

注:

URI は、空白のウィンドウまたは新しいタブで開く必要があります。

デスクトップ クライアント URL を構築する

webUrlは Office Online for Office ドキュメントを指しているため、次の 2 つの手順でデスクトップ URI を構築します。

  1. 親フォルダーの webUrl を取得します。
  2. ファイル名を追加します。

パターンの例:

ms-word:ofe|u|{folder.WebUrl}/{item.Name}

結果の図形:

ms-word:ofe|u|https://contoso.sharepoint.com/contentstorage/CSP_1234765465/Document%20Library/MyDocument.docx

スキームの詳細については、「 Office URI スキーム」を参照してください。

リダイレクト動作を構成する

Microsoft 365 でサポートされているビューアーでファイルを開くことができない場合は、リダイレクト設定を使用してユーザーをアプリにルーティングします。

ApplicationRedirectUrl は、コンテナーの種類に対してアプリケーション リダイレクト URL を構成します。 ワークロードのファイルリターン シナリオを処理するアプリ ルートに使用します。

urlTemplate設定は、Microsoft 365 がサポートされているビューアーなしでユーザーにファイルを送信する場所を制御します。 サポートされている Office Web ビューアー ファイル (Word、Excel、PowerPointなど) は、Office Web ビューアーで開きます。 埋め込みビューアーで PDF ファイルが開きます。 その他のファイルの種類は、構成時に urlTemplate を介してリダイレクトされます。 urlTemplateが構成されていない場合、Microsoft 365 はユーザーを Microsoft ヘルプ ページに送信します。

Microsoft Graph PATCH /storage/fileStorage/containerTypes/{containerTypeId} API を使用してsettings.urlTemplateを設定します。 ループバック アドレスに解決されない有効な絶対 https:// URL を使用します。

PATCH https://graph.microsoft.com/v1.0/storage/fileStorage/containerTypes/{containerTypeId}
Content-Type: application/json

{
  "settings": {
    "urlTemplate": "https://app.contoso.com/open?t={tenant-id}&d={drive-id}&i={item-id}"
  }
}

Microsoft 365 は、サポートされているトークンを解決し、その値を URL エンコードし、テンプレートに置き換えます。 一般的なトークンには、 {tenant-id}、 {drive-id}、 {folder-id}、 {item-id}、 {site-domain}、 {list-id}、 {site-url}が含まれます。

アプリが urlTemplate リダイレクトを受け取ったら、ユーザーを認証し、トークン値を解析し、Microsoft Graph を使用してファイルを取得します。 標準ファイル URL が必要な場合は、webUrlではなく DriveItem webDavUrl プロパティを使用します。

リダイレクトを設計する場合:

  • アプリに安定した運用 URL を使用します。
  • 開発 URL は、ローカルまたは試用版の作業にのみ使用します。
  • リダイレクト URI Microsoft Entra IDアプリ ルートに合わせて維持します。
  • Office アクションの後に、ユーザーが適切なアプリ内コンテキストに戻っていることを検証します。
  • 必要な Office クエリ パラメーターを削除する URL の書き換えを避けます。
  • 無効な値がnullとして格納されるため、更新後にurlTemplateを確認します。

共有と共同編集をサポートする

Office エクスペリエンスには、コラボレーション機能が含まれます。

ユーザーは、ドキュメントの共有、共有可能なリンクの作成、リアルタイムでの共同編集、プレゼンス インジケーターの表示、コメントの使用、サポートされている場所でのメンションの使用を行うことができます。

ユーザーが共有リンクを作成するときに、アクセス権を付与するユーザーを選択します。

共有スコープ リンクを使用できるユーザー
すべてのユーザー リンクを直接送信するか転送するかに関係なく、organization外のユーザーを含め、リンクを受け取るすべてのユーザー。
組織内のユーザー organizationの誰でも、直接送信された場合も転送された場合でも、リンクを持つユーザー。
特定のユーザー 指定したユーザーのみ。 招待が転送された場合は、既にアクセス権を持っているユーザーのみがリンクを使用できます。
既存のアクセス権をもつユーザー ファイルまたはフォルダーに既にアクセスできるユーザーをPeopleします。 このスコープでは、既存のアクセス許可は変更されません。

注:

メンションでは、対象ユーザーに Microsoft 365 ライセンスが割り当てられている必要があります。 メンションは、使用しているテナントのorganization内のユーザーに制限され、マルチテナント設定でゲストとユーザーを他のテナントから除外します。

バージョン履歴を使用する

バージョン管理は、SharePoint Embedded アプリに格納されているWord、Excel、PowerPoint ファイルに対して自動的に有効になります。

ユーザーは、変更を確認したり、バージョンを比較したり、以前のバージョンを復元したり、間違いから回復したり、共同編集セッションからの変更を確認したりできます。

階層リンク プロパティを使用する

Office クライアントは、Office ファイルをアプリケーションに関連付ける階層リンク スタイルの要素を表示できます。

階層リンク パターンは、アプリ用に構成されたコンテナー プロパティから構築されます。

現在のチャネルを使用して、階層リンク パターンと今後の Office アプリの機能強化を取得します。

Office 更新プログラム チャネルの情報については、「Microsoft 365 Appsの更新プログラム チャネルの概要」を参照してください。

Office の起動を検証する

各起動パスをテストします。

  1. Wordドキュメントをコンテナーにアップロードします。
  2. DriveItem を読み取り、 webUrlをキャプチャします。
  3. action=defaultでwebUrlを開きます。
  4. クエリ文字列を action=viewに変更します。
  5. クエリ文字列を action=editに変更します。
  6. デスクトップ起動用の Office URI スキームを構築します。
  7. 必要に応じて、アクセス許可ブロックの編集を確認します。
  8. 自動保存とバージョン履歴の動作を確認します。
  9. ユーザーがアプリに戻ることができるかどうかを確認します。

Office の起動のトラブルシューティング

現象 チェック
編集の代わりにビューで URL が開きます action パラメーターとユーザー編集アクセス許可。
デスクトップ クライアントが開かない Office URI スキーム、ブラウザー ポリシー、および新しいタブの動作。
ユーザーが共同編集できない ファイルの種類、アクセス許可、Office クライアントのサポート。
メンションでユーザーが見つからない Microsoft 365 ライセンスとテナント メンバーシップの制限。
階層リンクが正しく表示されない コンテナーのプロパティと Office の更新チャネル。
リダイレクトが間違ったルートに戻る ApplicationRedirectUrl とアプリ ルートの処理。

次の手順

アプリのプレビュー ファイルに埋め込み プレビューを追加します。

  • Last updated on