msgraph-sdk

Microsoft Graph SDK

Microsoft Graph をアプリケーションに統合して Microsoft 365 のデータとサービスにアクセスする場合に、このスキルを使用してください。

記憶だけに頼らず、対象言語の現在の Microsoft Graph SDK ドキュメントと SDK バージョンに基づいて実装してください。

まず対象言語を特定する

1. プロジェクトに .cs、.csproj、または .sln ファイルが含まれている場合、またはユーザーが C# のガイダンスを求めている場合は、.NET のワークフローを使用してください。references/dotnet.md に従ってください。
2. プロジェクトに package.json、.ts、または .js ファイルが含まれている場合、またはユーザーが Node.js／ブラウザーのガイダンスを求めている場合は、TypeScript / JavaScript のワークフローを使用してください。references/typescript.md に従ってください。
3. プロジェクトに .py、pyproject.toml、または requirements.txt ファイルが含まれている場合、またはユーザーが Python のガイダンスを求めている場合は、Python のワークフローを使用してください。references/python.md に従ってください。
4. 複数の言語が含まれている場合は、編集対象ファイルの言語に合わせるか、ユーザーに確認してください。

常に最新のドキュメントを参照する

• Microsoft Graph の概要：https://learn.microsoft.com/graph/overview
• Graph Explorer（ライブで呼び出しを試す）：https://developer.microsoft.com/graph/graph-explorer
• Graph のアクセス許可リファレンス：https://learn.microsoft.com/graph/permissions-reference
• 利用可能な場合は、Microsoft Docs MCP ツールを使用して、最新の API 仕様と SDK サンプルを取得してください。

認証 — 適切な方式を選択する

適切でない認証フローを選ぶことは、Graph 統合で最もよくある間違いです。認証コードを書く前に、次の判断基準を適用してください。

シナリオ	使用するフロー
ユーザーのいないバックグラウンドサービス／デーモン	クライアント資格情報（アプリのみ）
サインイン済みユーザーに代わって動作するエージェントまたは API	On-Behalf-Of（OBO）
Azure 上で動作するアプリ（Function、Container App、VM）	マネージド ID（シークレットより優先）
CLI ツールまたはローカル開発スクリプト	デバイスコードまたは対話型ブラウザー
シングルページアプリ（ブラウザーのみ）	認可コード + PKCE

• ユーザーコンテキストが必要な場合にクライアント資格情報を使用しないでください。Graph はアクセス許可レベル（アプリケーションと委任）でこれを強制します。
• Azure でホストされるアプリでは DefaultAzureCredential を優先してください。まずマネージド ID を試し、ローカル開発用に適切にフォールバックします。
• シークレットをハードコードしないでください。環境変数、Azure Key Vault、または Secret Manager を使用してください。

SDK の基本的な使用パターン

クライアントの構築

GraphServiceClient は一度だけ構築して再利用してください（内部でトークンのキャッシュを管理します）。

Azure Identity ライブラリの資格情報を渡してください。生の HTTP クライアントを手動で構築しないでください。

呼び出しの実行

• フルーエントビルダー API を使用してください：client.Users[userId].Messages.GetAsync(...)。
• 非同期呼び出しでは必ず await を使用してください。
• 返されるフィールドを制限するには $select を指定してください。Graph はデフォルトで大きなペイロードを返します。
• メモリ内で返されたコレクションをフィルターするのではなく、サーバー側で $filter を使用してください。
• 関連するリソースが少量の場合は、$expand を使用して 1 回の呼び出しで取得してください。

ページネーション

Graph のコレクションはページ分割されます。すべての項目が 1 回の応答で届くと想定しないでください。

• 応答に @odata.nextLink があるか確認してください。
• SDK の PageIterator ヘルパー（3 種類すべての SDK で利用可能）を使用して、ページを自動的にたどってください。
• ページサイズを制御するには $top を設定してください（最大値はリソースによって異なりますが、通常は 999 です）。

高度なパターン

バッチリクエスト

$batch エンドポイントを使用して、独立した Graph 呼び出しを最大 20 件まで 1 つの HTTP リクエストにまとめられます。次の場合にバッチ処理を使用してください。

• ダッシュボードや、複数のリソースを事前に必要とするエージェントのデータを初期化する場合。
• 呼び出し回数の多い操作でレイテンシを削減する場合。

バッチ応答は順不同で届きます。各リクエストに割り当てた id フィールドを使って対応付けてください。

差分クエリ

コレクション全体をポーリングする代わりに、差分クエリを使用して変更を段階的に同期します。

• 最初の呼び出し：GET /users/delta は、すべての項目と @odata.deltaLink を返します。
• 以降の呼び出し：deltaLink を使用すると、前回の同期以降に変更された項目のみを受け取れます。
• 対応対象：ユーザー、グループ、メッセージ、予定表イベント、Teams チャネルなど。
• 同期の実行間は、deltaLink をデータベースや BLOB などに永続的に保存します。

変更通知（Webhook）

POST /subscriptions でリソースの変更をサブスクライブします。

• Graph は、HTTPS の通知 URL に変更イベントを配信します。
• サブスクリプションには有効期限があります。expirationDateTime（リソースによって上限は異なり、通常、メールや予定表では 1～3 日、ユーザーやグループでは最大 4230 分）より前に更新してください。
• サブスクリプションのハンドシェイクを検証します。作成時に Graph は validationToken クエリパラメーターを送信するため、プレーンテキストでそのまま返し、HTTP 200 を応答します。
• ライフサイクル通知（notificationUrl + lifecycleNotificationUrl）を使用して、イベントの取りこぼしや再認証に対応します。
• 大量のイベントが発生するシナリオでは、リソースデータ付きの変更通知を優先します（追加の暗号化設定が必要です）。

スロットリング

Graph は頻繁にスロットリングを行います。必ず HTTP 429 に対応してください。

• Retry-After ヘッダーを読み取ります。固定のバックオフ時間ではなく、待機する秒数が正確に指定されています。
• 設定すると、SDK の組み込みリトライミドルウェアが 429 を自動的に処理します。明示的に有効にしてください。
• Graph に数百件の並列リクエストを送るファンアウトパターンは避け、代わりにバッチ処理またはキューイングを使用します。

アクセス許可

認証コードを書く前に、アクセス許可を適切に設定してください。スコープを誤ると、後からデバッグが難しい 403 エラーが発生します。

• アプリケーションのアクセス許可は、ユーザーなしで実行されます（デーモン／サービス）。管理者の同意が必要です。
• 委任されたアクセス許可は、サインイン済みユーザーのコンテキストで実行されます。一部は管理者の同意が必要です。
• 必要な最小限のアクセス許可を要求します。Graph のアクセス許可リファレンスには、すべての操作について最小権限の選択肢が記載されています。
• コーディングを始める前に、Graph Explorer で実際に必要なアクセス許可をテストします。
• Azure のアプリ登録で、API のアクセス許可を付与し、Microsoft Graph を選択して、種類（Application または Delegated）を選び、必要に応じて管理者の同意を付与します。

よく使う Graph リソース — クイックリファレンス

目的	リソースパス
サインイン済みユーザーのプロフィールを取得する	GET /me
ユーザーのメールボックスのメッセージを一覧表示する	GET /me/messages
メールを送信する	POST /me/sendMail
予定表イベントを一覧表示する	GET /me/events
ユーザーの OneDrive のルートを取得する	GET /me/drive/root/children
ユーザーが参加している Teams を一覧表示する	GET /me/joinedTeams
Teams チャネルにメッセージを投稿する	POST /teams/{id}/channels/{id}/messages
SharePoint サイトのリストを一覧表示する	GET /sites/{siteId}/lists
M365 全体を検索する	POST /search/query
テナント内の全ユーザーを一覧表示する（アプリのみ）	GET /users
グループのメンバーを取得する	GET /groups/{id}/members

同様に、SDK のフルーエント API を使用して、コード内でこれらのリソースにアクセスします。

ワークフロー

1. 対象の言語を決定し、対応するリファレンスファイルを読みます。
2. 認証シナリオを特定し、上の表から適切なフローを選びます。
3. 実装方法を決める前に、最新の SDK ドキュメントと Graph Explorer の例を取得します。
4. 最小権限のアクセス許可を適用し、Graph のアクセス許可リファレンスで確認します。
5. 最初からページネーションを実装します。レスポンスが 1 ページだけとは限りません。
6. 初日からスロットリング用のリトライミドルウェアを有効にします。
7. 同期するシナリオでは、ポーリングより差分クエリを優先します。
8. 選択したリファレンスファイルに記載された、言語固有のパッケージ名、認証プロバイダーの設定、コードパターンを使用します。

完了条件

• 認証フローがシナリオに合致しており、ユーザーコンテキストでの呼び出しでクライアント資格情報をデフォルトで使用していません。
• GraphServiceClient を一度だけ構築し、再利用しています。
• すべてのコレクション読み取りでページネーションを処理しています。
• スロットリング（429）を、再試行ミドルウェアまたは Retry-After の明示的な処理によって処理しています。
• 権限を必要最小限に絞っています。
• シークレットや資格情報をハードコードしていません。
• コードが、選択した言語の現在の SDK バージョンのパターンに準拠しています。