Webhook を使用してファイルとコンテナーの変更に対応する

適用対象: 開発者

アプリが SharePoint Embedded コンテナー内のファイルの変更に対応する必要がある場合は、Microsoft Graph Webhook を使用します。 サブスクリプションは、サブスクライブされたリソースが変更されたときに HTTPS エンドポイントを呼び出すように Microsoft Graph に指示します。

通知エンドポイントを作成する

POST要求を受け入れる HTTPS エンドポイントを公開します。 ローカル開発時に、ngrok を使用してローカル サーバーに要求をトンネリングします。

ngrok http 3001

Microsoft Graph は、サブスクリプションを作成するときに、 validationToken クエリ パラメーターを送信してエンドポイントを検証します。 HTTP 200 を使用して、そのトークンをプレーン テキストとして返します。

export const onReceiptAdded = async (req: Request, res: Response) => {
  const validationToken = req.query['validationToken'];
  if (validationToken) {
    res.send(200, validationToken, { "Content-Type": "text/plain" });
    return;
  }

  const driveId = req.query['driveId'];
  if (!driveId) {
    res.send(200, "Notification received without driveId, ignoring", { "Content-Type": "text/plain" });
    return;
  }

  console.log(`Received driveId: ${driveId}`);
  res.send(200, "");
}

ルートが通知を処理する前に、API サーバーにルートを登録し、要求本文とクエリ解析を有効にします。

server.use(restify.plugins.bodyParser(), restify.plugins.queryParser());
server.post('/api/onReceiptAdded', async (req, res, next) => {
  try {
    const response = await onReceiptAdded(req, res);
    res.send(200, response);
  } catch (error: any) {
    res.send(500, { message: `Error in API server: ${error.message}` });
  }
  next();
});

コンテナー ドライブをサブスクライブする

Microsoft Graph を使用してサブスクリプションを作成します。 このパターンでは、SharePoint Embedded コンテナー ID はドライブ ID です。

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "updated",
  "notificationUrl": "https://contoso.example/api/onReceiptAdded?driveId={container-id}",
  "resource": "drives/{container-id}/root",
  "expirationDateTime": "2026-06-25T03:58:34.088Z",
  "clientState": ""
}

drives/{container-id}/rootの下の変更をサブスクライブし、ハンドラーがコンテナーを識別できるように通知 URL にdriveId={container-id}を追加します。

有効期限の計算

ドライブアイテムのサブスクリプションの有効期間は最大 4,230 分です。 サブスクリプションを作成する前に、要求前スクリプトまたはバックエンド スケジューラを使用して有効期限を設定します。

var now = new Date();
var duration = 1000 * 60 * 4230;
var expiry = new Date(now.getTime() + duration);
pm.environment.set("ContainerSubscriptionExpiry", expiry.toISOString());

サブスクリプション ID、リソース、コンテナー ID、有効期限を格納します。 有効期限が切れる前に各サブスクリプションを更新します。

通知を安全に処理する

Webhook 要求からすばやく返します。 キューのバックグラウンド作業、Microsoft Graph で現在のファイルまたはコンテナーの状態をフェッチし、通知が重複または遅延する可能性があるため、べき等の処理を行います。

ドキュメント処理、インデックス更新、ユーザー通知、ワークフロー トリガーなどのアクションに Webhook を使用します。 不在通知または期限切れのサブスクリプションについては、定期的な調整ジョブを保持します。

フローを確認する

サブスクリプションを作成し、コンテナー内のファイルをアップロードまたは更新し、エンドポイントが予想されるドライブ ID をログに記録することを確認します。 検証が失敗した場合は、パブリック HTTPS URL、validationToken応答コンテンツ タイプ、およびサーバーがルート実行前にクエリ パラメーターを解析するかどうかをチェックします。

次の手順

• コンテナーのアーカイブと復元