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

適用対象: Developer

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

最初に [ファイルのアップロード、ダウンロード、管理] を完了して、アプリを起動できるようにします。

Office ファイルを SharePoint Embedded コンテナーに格納すると、アプリはビルドせずに完全なコラボレーションスタックにリンクされます。 Word、Excel、PowerPoint ファイルでは、リアルタイムの共同編集、自動保存、自動バージョン履歴、共有可能なリンクと@mentionsを介した共有 (範囲が設定されたアクセスレベル) がサポートされています。コラボレーションエンジンを構築する必要はありません。編集は Office for the web (新しいブラウザータブまたはウィンドウ) または Office デスクトップクライアントで開くため、ユーザーはアプリの UI を離れて編集できます。インラインのアプリ内表示が必要な場合は、読み取り専用プレビューを埋め込みます。決定コンテキストについては、「 Office 共同編集をビルドせずに追加する」を参照してください。

注:

@mentions Microsoft 365 ライセンスを持つ受信者にのみ通知します。 SharePoint 埋め込み共有では、電子メール招待状は送信されません。

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

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

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

注:

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

Office 統合を制御する

Office 統合は、SharePoint Embedded コンテナーの種類に対して既定で有効になっています。承認されたユーザーは、アプリのカスタムユーザーインターフェイス以外の Office エクスペリエンスを使用するなど、サポートされているファイルを Office for the web および Office デスクトップクライアントで開くことができます。アプリで、アプリ制御のエクスペリエンス内にとどまるためにファイルアクセスが必要な場合は、fileStorageContainerTypeSettings の isOfficeRestricted プロパティを true に設定することで、コンテナーの種類に対する Office 統合を無効にできます。

isOfficeRestricted 現在、Microsoft Graph ベータエンドポイントを通じてのみ使用できます。 v1.0 ではまだ利用できません。プロパティ定義については、「 fileStorageContainerTypeSettings リソースの種類」を参照してください。

ベータエンドポイントに対して Microsoft Graph PATCH /storage/fileStorage/containerTypes/{containerTypeId} API を使用してsettings.isOfficeRestrictedを設定します。

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

{
  "settings": {
    "isOfficeRestricted": true
  }
}

Office 統合が無効になっている場合、ユーザーは影響を受けるコンテナーからファイルを Office for the web クライアントまたは 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 を使用します。

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

注:

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 アプリケーションのオープンプラットフォームインターフェイスのアクション」を参照してください。

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 ドキュメント用の Office Online を指すため、次の 2 つの手順でデスクトップ URI を作成します。

親フォルダーの webUrl を取得します。
ファイル名を付加します。

パターンの例:

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 がサポートされているビューアーなしでユーザーを送信するファイルを制御します。サポートされている Word、Excel、PowerPoint などの Office Web ビューアーファイルは、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 は、ローカル作業または試用版の作業にのみ使用してください。
Microsoft Entra ID リダイレクト URI をアプリルートに合わせて調整します。
Office アクションの後、ユーザーが適切なアプリ内コンテキストに戻ることを検証します。
必要な Office クエリパラメーターを削除するような URL の書き換えは避けます。
無効な値が null として格納されるため、更新後にurlTemplateを確認してください。

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

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

ユーザーは、共有リンクを作成するときに、アクセスを許可するユーザーを選択します。

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

注:

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

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

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

ユーザーは、変更の表示、バージョンの比較、以前のバージョンの復元、間違いの回復、共同編集セッションからの変更のレビューを行うことができます。

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

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

Microsoft 365 Apps 用の最新チャネル更新チャネルを使用して、ユーザーが最新の Office 階層リンクの動作と今後の Office アプリの機能強化を受け取るようにします。

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

Office の起動の検証

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

コンテナーに Word 文書をアップロードします。
DriveItem を読み取り、 webUrlをキャプチャします。
action=default で webUrl を開きます。
クエリ文字列を action=view に変更します。
クエリ文字列を action=edit に変更します。
デスクトップを起動するための Office URI スキームを作成します。
必要に応じて、アクセス許可のブロック編集を確認します。
自動保存とバージョン履歴の動作を確認します。
ユーザーがアプリに戻ることができることを確認します。

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

現象	チェック
URL が編集ではなくビューで開く	`action` パラメーターとユーザー編集アクセス許可が必要です。
デスクトップクライアントが開かない	Office URI スキーム、ブラウザーポリシー、および新しいタブの動作。
ユーザーが共同編集できない	ファイルの種類、アクセス許可、Office クライアントサポート。
メンションしてもユーザーが見つからない	Microsoft 365 ライセンスとテナントメンバーシップの制限。
階層リンクが正しく表示されない	コンテナーのプロパティと Office 更新プログラムチャネル。
リダイレクトが間違ったルートに戻る	`ApplicationRedirectUrl` アプリルートの処理。
Office for the web または Office デスクトップクライアントでファイルが開かない	`isOfficeRestricted` を通じてコンテナーの種類に対して Office 統合が無効になっていないことを確認し、ユーザーのファイルのアクセス許可と既存のクライアント固有の起動要件をチェックします。

次の手順

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

Last updated on 2026-08-28