アプリ内のファイルをプレビューする

適用対象: 開発者

ファイルをダウンロードしたり、Office の完全な編集エクスペリエンスを開いたりすることなく、ユーザーが SharePoint Embedded コンテンツを検査できるように、ファイルプレビュー UX を追加します。

Office の編集が必要な場合は、[ アプリから Office ファイルを開く ] を完了します。軽量プレビューについては、この記事を使用してください。

プレビューフローについて

プレビューフローには、次の 2 つの手順があります。

Microsoft Graph DriveItem プレビューエンドポイントを呼び出します。
iframe または新しいブラウザーページで返された URL を使用します。

Graph エンドポイントは次のとおりです。

POST https://graph.microsoft.com/{version}/drives/{driveId}/items/{itemId}/preview

ここで、

{version} は、 v1.0などの Microsoft Graph バージョンです。
{driveId} は、 b!で始まるコンテナー ID です。
{itemId} は DriveItem ID です。

標準 API リファレンスについては、「 DriveItem のプレビュー」を参照してください。

サポートされているファイルの種類を把握する

Microsoft 365 では、一般的なドキュメント、画像、ビデオ、PDF 形式など、さまざまな種類のファイルのプレビューがサポートされています。

たとえば、次のような情報が含まれます。

PDF ファイル。
JPG およびその他のイメージファイル。
MP4 およびその他のサポートされているメディアファイル。
Microsoft 365 プレビューエクスペリエンスでサポートされている Office ファイル。

現在の一覧については、「 OneDrive、SharePoint、Teams でファイルをプレビューするためにサポートされるファイルの種類」を参照してください。

注:

ファイルの種類のサポートは、サービス機能、テナントポリシー、クライアントエクスペリエンスによって異なる場合があります。プレビューエラーを常に適切に処理します。

ネイティブ PDF の表示

SharePoint Embedded ネイティブ PDF 表示エクスペリエンスでは、 ファイル内の検索、ファイルに埋め込まれた コメントと付箋の表示 、印刷 (2026 年 3 月の追加) がサポートされています。これらの機能は、ベータ版と v1.0 Microsoft Graph エンドポイントの両方の driveItem: preview API を通じて利用できます。

クエリパラメーターを使用して PDF プレビューアーを強化する

driveItem の webUrl プロパティにクエリパラメーターを追加して、SharePoint Embedded PDF プレビューアーを強化します。 webUrlを取得するには、GET /drives/{drive-id}/items/{item-id}?$select=webUrlなど、driveItem GET API を呼び出します。

JSON でエンコードされた embed クエリ文字列としてパラメーターを渡します。同じオブジェクトに 1 つ以上のパラメーターを含めることができます。

<webUrl>?&embed={"<param1>":<value>,"<param2>":<value>}

パラメーター	効果
`mpp`	印刷アイコンと Ctrl + P 印刷を有効にします。たとえば、「 `<webUrl>?&embed={"mpp":true}` 」のように入力します。
`mpsn`	PDF に付箋が含まれている場合に付箋の内容を表示します。たとえば、「 `<webUrl>?&embed={"mpsn":true}` 」のように入力します。

前提条件

プレビューを作成する前に、次のことを確認してください。

ファイルは SharePoint Embedded コンテナーに格納されます。
アプリは、コンテナー ID と DriveItem ID を認識しています。
アプリは Microsoft Graph トークンを取得できます。
呼び出し元には、ファイルを読み取るアクセス許可があります。
ファイルの種類はプレビューでサポートされています。
UI で iframe をホストするか、新しいページを開くことができます。

プレビューリンクを作成する

サービスレイヤーからプレビューエンドポイントを呼び出します。

次の C# SDK パターンを使用します。

ItemPreviewInfo preview = await graphServiceClient.Drives[driveId].Items[itemId]
    .Preview()
    .Request()
    .PostAsync();

応答には、プレビュー URL 情報が含まれます。

{
  "getUrl": "https://www.onedrive.com/embed?foo=bar&bar=baz",
  "postParameters": "param1=value&param2=another%20value",
  "postUrl": "https://www.onedrive.com/embed_by_post"
}

使用可能な場合は、 getUrl を使用します。

注意

getUrl 現在、アプリケーションでのみ使用できる暗号化されたトークンが含まれています。この動作は変更される可能性があります。

取得した URL に nb=true を追加して、上部のバナーを削除します。

例:

https://contoso.sharepoint.com/restOfUrl/embed.aspx?param1=value&nb=true

これは、ユーザーエクスペリエンスとコンプライアンス要件に適合する場合にのみ使用します。

プレビューを iframe に埋め込む

プレビュー URL をホストするアプリページを作成します。

図形の例:

<!DOCTYPE html>
<html>
  <body>
    <h2>Preview</h2>
    <p>Preview of {file name}:</p>
    <iframe src="{preview URL}" height="200" width="300" id="preview" title="File preview"></iframe>
  </body>
</html>

運用環境では、次の情報も提供します。

わかりやすい iframe タイトル。
応答性の高いサイズ設定。
読み込み状態。
エラー状態。
フォールバックダウンロードまたはオープンアクション。

プレビューを動的に読み込む

CORS の問題を作成したり、トークンを公開したりする場合は、ブラウザースクリプトから Microsoft Graph を直接呼び出さないでください。

次のサーバー側エンドポイントを使用します。

ユーザーを認証します。
要求されたファイルへのアクセスを検証します。
Graph トークンを取得します。
DriveItem プレビューエンドポイントを呼び出します。
プレビュー URL をクライアントに返します。

次のサーバー側パターンを使用します。

[HttpGet]
[AuthorizeForScopes(Scopes = new string[] { "Files.Read.All" })]
public async Task<ActionResult<string>> GetPreviewUrl(string driveId, string itemId)
{
  return url + "&nb=true";
}

その後、クライアントは URL を要求し、iframe ソースを設定できます。

async function preview(driveId, itemId) {
  const url = `/GetPreviewUrl?driveId=${driveId}&itemId=${itemId}`;
  const response = await fetch(url, {
      credentials: 'include',
  }).then(response => response.text());
  document.getElementById('preview').src = response + "&nb=true";
}

デザインプレビュー UX

適切なプレビュー UX では、次の手順を実行する必要があります。

ファイル名を表示します。
読み込みインジケーターを表示します。
iframe に十分な領域を予約します。
Office ファイルに対して Office で開くアクションを指定します。
プレビューが使用できない場合は、ダウンロードアクションを指定します。
キーボードアクセシビリティを維持します。
プレビューフレーム内にフォーカスを閉じ込めないようにします。
わかりやすい言語でエラーを説明します。

プレビューエラーの処理

失敗	処理
サポートされていないファイルの種類	代わりに、ダウンロードまたは開いているアクションを表示します。
アクセス許可がありません	アクセスを要求するか、もう一度サインインするようにユーザーに依頼します。
有効期限が切れた URL	新しいプレビュー URL を要求します。
CORS エラー	Graph 呼び出しをサーバー側エンドポイントに移動します。
ファイルの削除	ファイルの一覧を更新し、古い選択を削除します。
サービスエラー	1 回再試行してから、安定したフォールバックを表示します。

重要

プレビュー URL を永続的な識別子としてキャッシュしないでください。コンテナー ID と DriveItem ID を格納し、必要に応じて新しいプレビュー URL を作成します。

セキュリティで保護されたプレビュー要求

プレビューは、保護されたコンテンツに対する読み取り操作として扱います。

サービスでは、次の手順を実行する必要があります。

サインインしているユーザーまたはサービスコンテキストを検証します。
呼び出し元がコンテナーの内容を読み取ることができるかどうかを確認します。
要求された項目が予期されるコンテナーに属していることを確認します。
ブラウザーに Graph トークンを公開しないようにします。
機密性の高いトークンを含むプレビュー URL のログ記録は避けてください。
ユーザーがサインアウトしたときにアプリ側プレビューセッションを期限切れにします。

プレビューエクスペリエンスを検証する

複数のファイルの種類とユーザーを使用してテストする:

PDF ファイルをアップロードします。
イメージファイルをアップロードします。
Office ファイルをアップロードします。
各ファイルのプレビュー URL を作成します。
各プレビューを iframe でレンダリングします。
読み取りアクセス権を持つユーザーをテストします。
アクセス権のないユーザーをテストします。
ファイルを削除し、エラーが処理されていることを確認します。
期限切れのプレビュー URL を更新します。
フォールバックアクションが機能することを確認します。

次のビルドタスクに接続する

プレビューが機能したら、検出エクスペリエンスを追加して、ユーザーがコンテナーとファイル間でコンテンツを見つけられるようにします。

[ コンテナーとファイルの検索] に進みます。

次の手順

コンテナーとファイルを検索する

Last updated on 2026-07-15

アプリ内のファイルをプレビューする

プレビュー フローについて

サポートされているファイルの種類を把握する

ネイティブ PDF の表示

クエリ パラメーターを使用して PDF プレビューアーを強化する

前提条件

プレビュー リンクを作成する

プレビュー バナーを削除する

プレビューを iframe に埋め込む

プレビューを動的に読み込む

デザイン プレビュー UX

プレビュー エラーの処理

セキュリティで保護されたプレビュー要求

プレビュー エクスペリエンスを検証する

次のビルド タスクに接続する