ファイルのアップロード、ダウンロード、管理

適用対象: Developer

Microsoft Graph ファイルと DriveItem API を使用して、SharePoint Embedded コンテナー内のファイルを管理します。

コンテナー ID を用意するには 、最初にコンテナーを作成して管理 します。

SharePoint Embedded は、Microsoft 365 機能が組み込まれた API のみのドキュメント ストアをアプリに提供します。 ファイル管理は Microsoft Graph を介して完全にプログラムで行われ、SharePoint UI はありません。 ライフサイクル全体には、アップロードとダウンロード、フォルダー、バージョン管理、ごみ箱、93 日間のコンテンツの復元が含まれます。 コンテンツは Microsoft Search API を介して検索でき、テナントの Microsoft Purview コンプライアンスを継承します。 アプリのエンド ユーザーは、基本的なファイル操作に Microsoft 365 ライセンスを必要としません。

ファイル ストレージを理解する

SharePoint Embedded コンテナーは、アプリケーション コンテンツのストレージ境界です。

各コンテナーは、Microsoft Graph ファイル ストレージと DriveItem API を介してファイル コンテンツを公開します。

アプリケーション・データ・モデルを使用して、各コンテナーを所有するビジネス・オブジェクト、アプリが作成するフォルダー、読み取りと書き込みが可能なユーザーまたはサービス、およびアプリが保存するファイルIDを決定します。

アーキテクチャについては、「 SharePoint Embedded アプリのアーキテクチャ」を参照してください。

Microsoft Graph ファイル ストレージ API の使用

次の Microsoft Graph 参照から始めます。

重要

文書化されている Microsoft Graph DriveItem とファイル ストレージ API を使用します。 SharePoint Embedded 固有のファイル API 名を作成しないでください。

前提条件

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

  • アプリは Microsoft Graph トークンを取得できます。
  • アプリには FileStorageContainer.Selected の同意があります。
  • アプリには、目的の操作に対するコンテナーの種類のアクセス許可があります。
  • ターゲット コンテナーが存在します。
  • 委任された呼び出しの場合、ユーザーはコンテナーのメンバーです。
  • アプリは、必要なコンテナー ID と DriveItem ID を格納します。

コンテナー ID をドライブにマップする

Microsoft Graph DriveItem API では、 driveIdを使用します。 SharePoint Embedded の場合、ドライブ ID は b! で始まるコンテナー ID です。

アプリで:

  1. コンテナーの作成時に返されるコンテナー ID を格納します。
  2. ドライブ識別子を必要とする DriveItem API を呼び出す場合は、コンテナー ID を使用します。
  3. アップロードまたはフォルダーの作成操作によって返されるアイテム ID を格納します。
  4. URL から ID を再構築することは避けます。

ファイルをアップロードする

DriveItems には Microsoft Graph のアップロード パターンを使用します。

小さいファイル (最大 250 MB) の場合は、DriveItems について説明されているシンプルなアップロード API を使用し、アイテムのコンテンツに 1 回 PUT します。

大きなファイル (250 MB を超える) の場合は、Microsoft Graph で説明されているアップロード セッションを使用し、アップロードが完了するまでバイト範囲のチャンク (たとえば、320 KB の倍数) でファイルを送信します。

アップロード フローでは、以下を実行します。

  1. 書き込みアクセスを検証します。
  2. コンテナー内の保存先フォルダーを選択します。
  3. パスが存在しない場合は、最初にフォルダーを作成します。
  4. 適切な Graph メソッドを使用してファイル バイトをアップロードします。
  5. 返された DriveItem ID を格納します。
  6. ファイル名、サイズ、状態を表示します。

ヒント

ビジネス メタデータをアプリケーション データベースに保持し、ファイル コンテンツを SharePoint Embedded に保持します。

ファイルをダウンロードする

ファイル コンテンツには、Microsoft Graph ドライブ項目のダウンロード機能を使用します。

ダウンロード フローでは、次の手順を実行します。

  1. 読み取りアクセスを検証します。
  2. コンテナー ID と DriveItem ID を解決します。
  3. DriveItem API を使用して、ファイル コンテンツまたはダウンロード URL を要求します。
  4. コンテンツをユーザーまたはサービスにStreamします。
  5. 有効期間の短いダウンロード URL の有効期限を処理します。
  6. 監査要件に従ってログに記録します。

フォルダーを作成する

DriveItem フォルダー作成 API を使用してコンテンツを整理します。

Office 起動 URL の予測可能なコンテンツ構造、ワークフロー ステージ、関連するアップロード、安定した親アイテム用のフォルダーを作成します。

フォルダーを作成する場合:

  1. フォルダーが存在するかどうかを確認します。
  2. 不足しているパス セグメントのみを作成します。
  3. 必要に応じてフォルダーの DriveItem ID を格納します。
  4. 名前付け規則を一貫して適用します。

ファイル コンテンツの更新

Microsoft Graph ドライブアイテムの更新またはアップロード セッション パターンを使用してコンテンツを置き換えます。

コンテンツを置き換える前に、次の手順を実行します。

  • 書き込みアクセス許可を確認します。
  • 同時実行チェックが必要な場合は、現在のメタデータを読み取ります。
  • サポートされている場合は、DriveItem ID を保持します。
  • Graph が成功したら、アプリのメタデータを更新します。

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

「Office の 動作のためにアプリから Office ファイルを開く 」を参照してください。

アイテムの名前を変更するか移動する

文書化された DriveItem の更新操作と移動操作がサポートされている場合は使用します。

現在のドライブアイテムを読み取り、コピー先フォルダーを確認し、操作を適用し、保存されているパスまたは表示名を更新し、可能な限りドライブアイテム ID を永続参照として保持します。

ファイルの削除

アクティブ コンテンツ エクスペリエンスにファイルを表示しなくなった場合は、削除操作を使用します。

削除する前に:

  • ユーザーの意図を確認します。
  • 書き込みまたは削除のアクセス許可を確認します。
  • アプリに論理的な削除が必要かどうかを決定します。
  • Graph が成功を返した後にのみ、アプリの状態を更新します。

ファイルを復元する

DriveItems とサービス エクスペリエンスについて文書化されている Microsoft Graph および SharePoint のファイル復元機能を使用します。

削除されたアイテムまたはバージョンを特定し、アクセス許可を確認し、復元を実行し、アイテム リストを更新し、復元した場所を通知します。

注:

recycleBinItem: 復元 では、Microsoft Graph ベータ版 (2025 年 10 月) で代替キーとして driveItemId がサポートされます。 元の driveItem の ID がわかっている場合は、最初にごみ箱を列挙せずに、対応する recycleBinItem を直接復元できます。

正確なファイル操作の要求と応答の詳細については、Microsoft Graph DriveItem のドキュメントを参照してください。

Office に接続してエクスペリエンスをプレビューする

アップロード後、より充実したエクスペリエンスを追加します。

ファイル操作の検証

スモーク テストを作成します:

  1. テスト コンテナーを作成します。
  2. フォルダーを作成する。
  3. ファイルをアップロードします。
  4. 返された DriveItem メタデータを読み取ります。
  5. ファイルをダウンロードします。
  6. 内容を置き換えます。
  7. ファイル名を変更します。
  8. ファイルを削除します。
  9. サポートされている場合は復元します。
  10. テスト コンテナーをクリーンアップします。

ファイル操作のトラブルシューティング

現象 チェック
アップロードに失敗する WriteContent アクセス許可とユーザー ライター ロール。
ダウンロードに失敗する ReadContent アクセス許可とユーザー閲覧者ロール。
フォルダーの作成に失敗する 親フォルダー ID と書き込みアクセス許可。
プレビューに失敗する ファイルの種類のサポートとプレビュー URL の生成。
Office の起動時に間違ったモードが開く 起動 URL action パラメーターまたは Office URI スキーム。
ユーザーによってアクセスが異なる 代理アクセスでは、アプリのアクセス許可とメンバーシップが交差します。

次の手順

アプリから Open Office ファイルで Office の起動エクスペリエンスを有効にします。

  • Last updated on