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

適用対象: 開発者

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

コンテナー ID を取得できるように、最初に [コンテナーの作成と管理 ] を完了します。

ファイル ストレージについて

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 をドライブにマップする

プレビュー ソースでは、Graph プレビュー エンドポイントが driveIdを使用し、SharePoint Embedded の場合、ドライブ ID は b! で始まるコンテナー ID です。

アプリで次の手順を実行します。

  1. コンテナーの作成時に返されたコンテナー ID を格納します。

  2. ドライブ識別子を必要とする DriveItem API を呼び出すときは、コンテナー ID を使用します。

  3. アップロードまたはフォルダーの作成操作によって返されるアイテム ID を格納します。

  4. URL から ID を再構築しないでください。

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

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

小さなファイル (最大 250 MB) の場合は、DriveItems に記載されている簡単なアップロード API を使用し、アイテムのコンテンツに対する単一の PUT を使用します。

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

アップロード フローでは、次の手順を実行します。

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

ヒント

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

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

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

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

  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 更新またはアップロード セッション パターンを使用して、コンテンツを置き換えます。

コンテンツを置き換える前に:

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

SharePoint Embedded に格納されている Office ファイルでは、Word、Excel、およびPowerPoint ファイルに対してバージョン管理が自動的に有効になっています。

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

アイテムの名前を変更または移動する

サポートされている場合は、ドキュメントに記載されている DriveItem の更新操作と移動操作を使用します。

セーフ フローでは、現在の DriveItem を読み取り、移動先フォルダーを確認し、操作を適用し、保存されたパスまたは表示名を更新し、可能な場合は DriveItem ID を永続的な参照として保持する必要があります。

ファイルを削除する

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

削除する前に:

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

ファイルを復元する

DriveItems とサービス エクスペリエンスに関するドキュメントに記載されている Microsoft Graph と SharePoint ファイルの復元機能を使用します。

復元フローでは、削除されたアイテムまたはバージョンを識別し、アクセス許可を確認し、復元を実行し、項目一覧を更新し、復元された場所を伝える必要があります。

注:

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

注:

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

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

アップロード後、より豊富なエクスペリエンスを追加します。

ファイル操作を検証する

煙テストを作成します。

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

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

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

次の手順

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

  • Last updated on