graph-api-resilience-privacy

在SPA中安全、稳健地实现Microsoft Graph（含SharePoint Lists）调用。适用于最小权限范围、401/403/429/503处理、Retry-After指数退避、分页/差异获取、日志保密（不泄露令牌/个人信息）、面向用户的日语错误提示等任务。关键词：Microsoft Graph、retry-after、退避、429、503、分页

SKILL.md

--- frontmatter

name: graph-api-resilience-privacy
description: 'Microsoft Graph（SharePoint Lists含む）呼び出しをSPAで安全・堅牢に実装する。最小権限スコープ、401/403/429/503の扱い、Retry-After対応の指数バックオフ、ページング/差分取得、ログの秘匿（トークン/個人情報を出さない）、ユーザー向け日本語エラー表示のタスクで使う。キーワード: Microsoft Graph, retry-after, backoff, 429, 503, paging'
license: MIT

Graph API Resilience & Privacy Skill

目的

Microsoft Graph を使ったデータ取得/更新を、

•壊れにくく（429/一時障害に強い）
•漏らさず（トークン/個人情報をログに出さない）
•分かりやすく（日本語の失敗UX）実装できる状態にする。

設計ルール（このリポジトリ方針）

•Graph呼び出しは src/lib/graph に集約し、UIで fetch() を散らさない
•取得は必要最小限（select/fields絞り込み、ページング前提）
•監視/一覧更新は差分取得（Modified以降）を優先し、フルスキャンを避ける

エラー分類とユーザー表示（推奨）

•
401（未認証）
- •UI: 「セッションが切れました。再ログインしてください。」
- •対応: MSALで再ログイン導線
•
403（権限不足）
- •UI: 「権限がありません。管理者に連絡してください。」
- •対応: scope/ロール/SharePoint権限の見直し
•
429（レート制限） / 503（混雑・一時障害）
- •UI: 「混雑しています。しばらくしてから再試行してください。」
- •対応: 自動リトライ（上限あり）+ 手動リトライ導線

リトライ方針（必須）

•429/503 は 指数バックオフ + リトライ上限
•Retry-After ヘッダがあれば最優先で尊重
•“永遠に待つ” を避ける（最大試行回数 / 最大待機時間を定義）

ページング・差分取得

•一覧取得はページング前提（nextLinkの追従）
•“毎回全件” を避ける：lastModifiedDateTime 等の差分キーで取得範囲を絞る

ログ/計測（秘匿）

•絶対に出さない: アクセストークン、IDトークン、refresh token、Authorizationヘッダ
•個人情報は最小化: メールアドレス・氏名は原則ログに載せない
•代わりに出す: リクエスト種別、HTTPステータス、リトライ回数、待機時間、相関ID（あれば）

成果物（このスキルで必ず出す）

•Graphクライアントの共通関数方針（例：graphFetch()）
•429/503 のリトライ仕様（上限、待機、Retry-After）
•画面向けエラーメッセージ（日本語）のテンプレ

依頼例

•「Graphで一覧取得してるけど、429が出る。Retry-After対応のリトライを入れたい」
•「401/403/429 の時の画面表示と再試行導線を整えたい」
•「SharePoint Lists の取得を差分更新にしたい（5分間隔で十分）」

References

•docs/frontend-data-contract.md