Microsoft Graphの変更通知が止まっても、受信アプリの画面が稼働中ならsubscriptionも有効とは限りません。まずsubscriptionの期限と対象resource、更新処理の結果、callbackの受信記録を分けて確認します。通知を再開することと、停止中に欠けたデータを取り直すことは別の作業です。
この記事はMicrosoft Graph v1.0のsubscriptionを管理する連携の診断手順です。特定のTeams連携製品が必ず同じ原因で停止するという説明ではありません。以下の台帳や運用例は架空で、subscriptionの作成・更新やGraph APIの実測は行っていません。
目次
通知の有効期限と処理の最終成功を並べる
管理台帳にsubscription ID、tenant、対象resource、expirationDateTime、通知先、最後の更新成功を対応付けます。表示上の「workflow active」はこの台帳の代用にはなりません。権限のある管理経路で現在のsubscriptionと照合し、保存していたIDだけを信じないようにします。
表は横にスクロールできます
| 状態 | 確認する事実 | 次の調査 |
|---|---|---|
| subscriptionの期限が近い | API応答の期限・更新実行結果 | 期限前更新の失敗箇所 |
| subscriptionが見当たらない | 作成者・tenant・対象resource | 閲覧対象の違いか、削除・失効か |
| 期限内だが受信がない | callbackとlifecycleの記録 | 再認可・受信・resource変更の有無 |
| 受信はあるがデータが古い | 後続queue・取得・DB反映 | 通知以降の処理停止 |
resourceごとにsubscriptionの最大期間が異なります。subscription resourceの公式資料（新しいタブで開く）で対象を確認し、別resourceの上限や利用者の回避策の実行間隔をコピーしません。要求した期限だけでなく、応答で確定した期限を保存します。
renewalとreauthorizationは同じではない
MicrosoftのUpdate subscription（新しいタブで開く）は、subscriptionの期限を更新するAPIです。一方、再認可だけの操作は期限延長と同じではありません。access tokenとsubscriptionの期限も別々に管理します。
表は横にスクロールできます
| 操作・イベント | 意味 | 確認する終点 |
|---|---|---|
| subscriptionの更新 | 期限延長と再認可を行う | 応答の新しい期限 |
| reauthorize | 再認可を行う | 期限延長まで済んだと扱わない |
| subscriptionRemoved | subscriptionが削除された通知 | 継続が必要なら再作成と同期 |
| missed | 一部通知が届かなかった通知 | resourceデータの再同期 |
公式lifecycle資料は、同じsubscriptionへreauthorizeとPATCH更新を10分以内に発行しないよう注意しています。両方が必要なら期限を更新する一回のPATCHで行う方法が説明されています。定期更新ジョブとlifecycle handlerが同時に走る設計では、対象IDごとに処理を調整し、重複した更新要求を無制御に送らないようにします。
更新失敗が権限や認証の問題なら、期限を長く要求し直すだけでは解消しません。対象resourceへのアクセスが現在も許可されているかを確認します。障害復旧を理由に必要以上のpermissionを追加する手順には進みません。
lifecycle通知はresourceごとの対応を確認する
Microsoft Graphのlifecycle通知（新しいタブで開く）にはreauthorizationRequired、subscriptionRemoved、missedがあります。ただし、すべてのresourceで三種類を受けられるわけではありません。公式のSupported resourcesでは再認可通知は全resource、削除・欠落通知にはそれぞれ対象resourceの制限があります。
たとえばTeams chatMessageで削除通知が対応していても、同じ前提でmissed通知まで届くと期待しません。対応表をresourceと通知種別の組合せで確認します。通知が来なかったことを、欠落がなかった証明にはできません。
既存subscriptionにlifecycleNotificationUrlがない場合、公式資料はPATCHで後付けできず、指定して作り直す必要があると説明しています。単なる期限更新とこの変更を混同しないでください。作り直す場合は、重複・空白期間・受信endpointの検証と再同期を含む変更として計画します。
handlerは通知の状態を分類する
受信側では登録済みsubscriptionとの対応や通知の正当性を確認し、対象IDとlifecycle種別を分けて処理します。一つのcollectionに複数通知が含まれる場合、先頭だけを見て全件を同じ状態にしません。受信受付と後続の復旧処理を追跡できるようにします。
表は横にスクロールできます
| lifecycle種別 | 復旧作業の方向 | 別に残す確認 |
|---|---|---|
| reauthorizationRequired | 有効な認証条件で再認可または期限更新 | 停止区間の変更回収 |
| subscriptionRemoved | 必要なアクセスを確認してsubscription再作成 | 新ID・期限と欠落区間 |
| missed | resourceの再同期 | 通知再開とデータ反映完了 |
handlerが成功応答を返しただけではGraph側の更新は完了しません。受付、更新要求、API応答、台帳保存、同期完了を別々の状態にします。具体的な再試行はAPIエラーに従い、429ならRetry-Afterなどを確認します。古い通知が届いても、新しいsubscriptionの状態を古いIDで上書きしない設計にします。
通知の再開後に欠落区間を回収する
通知が再び一件届いても、停止中の全変更が自動で届いたとは言えません。公式資料は、停止区間をresourceデータの同期で補う必要を説明し、delta queryなどを例示しています。利用resourceが対応する取得・同期APIを確認し、別resourceのdelta endpointを流用しません。
架空の台帳なら「最後のデータ同期成功09:00」「通知停止を検出10:30」「subscription再作成10:40」「再同期完了10:50」と分けます。10:40の通知再開を復旧完了とせず、対象データの追いつきと未処理queueを確認してから閉じます。通知の重複や再同期で同じ対象を処理しても、二重作成・二重通知にならないようにします。