microsoft-graph

Microsoft Graph API オーケストレーションスキル

Microsoft Graph は、Microsoft 365、Windows、Enterprise Mobility + Security にわたる Microsoft Cloud リソースにアクセスするための統合 REST API エンドポイントです。ベース URL：https://graph.microsoft.com/{version}/{resource}

API バージョン： v1.0（本番環境）または beta（プレビュー）
認証： Azure AD による OAuth 2.0
データ形式： JSON

タスクに応じたリソースの読み込み方

タスク	サービス	リソースを読み込む
認証のセットアップ、アプリの登録、資格情報の管理	アプリケーションと認証	resources/authentication-apps.md
ユーザー、グループ、組織、ディレクトリの管理	ID とアクセス	resources/identity-access.md
メール、フォルダー、添付ファイル、ルール、署名	メール操作	resources/mail-operations.md
カレンダー、イベント、スケジュール設定、会議、空き時間	カレンダーとスケジュール設定	resources/calendar-scheduling.md
ファイルやフォルダーのアップロード、共有、OneDrive、SharePoint	ファイルとストレージ	resources/files-storage.md
Teams、チャネル、チャット、プレゼンス、オンライン会議	Teams とコミュニケーション	resources/teams-communications.md
Planner のタスク、To Do リスト、OneNote ノートブック	計画とノート	resources/planning-notes.md
セキュリティアラート、コンプライアンス、デバイス管理、レポート	セキュリティとガバナンス	resources/security-governance.md

オーケストレーションプロトコル

フェーズ 1：タスクを分析する

次の問いに答えて、必要なサービス領域を特定します。

• どのリソースですか？（ユーザー、ファイル、メッセージ、イベントなど）
• どの操作ですか？（読み取り、作成、更新、削除）
• 誰が操作しますか？（サインインしているユーザーまたはサービスアカウント）
• どのアクセス許可ですか？（委任またはアプリケーション）

フェーズ 2：適切なリソースを読み込む

上記の選択表を使って、リソースファイルを確認します。各リソースには次の内容が含まれています。

• ベースパスを含むエンドポイントの完全なリファレンス
• すべての CRUD 操作のリクエスト／レスポンス例
• クエリパラメーターとフィルターオプション
• 必要なアクセス許可（委任およびアプリケーション）
• エラー処理のパターンとベストプラクティス
• 一般的なワークフローとパターン

フェーズ 3：確実に実装する

各リソースには、ユースケースに合わせた実践的で、そのままコピーして使える例が掲載されています。

Graph 共通の概念

標準クエリパラメーター：

$select=prop1,prop2              Choose properties to return
$filter=startsWith(name,'A')     Filter results by condition
$orderby=name desc               Sort results (asc or desc)
$top=25                          Limit to 25 results (default 20)
$skip=50                         Skip first 50 results
$expand=members                  Include related/nested data
$count=true                      Include total count in response
$search="keyword"                Full-text search across content

標準 CRUD 操作：

GET /me/messages?$select=subject&$top=10        # Read
POST /me/events {"subject": "Meeting", ...}     # Create
PATCH /users/{id} {"jobTitle": "Manager"}       # Update
DELETE /me/messages/{id}                        # Delete

ページネーション： 完全なデータセットを取得するには、レスポンスに含まれる @odata.nextLink を常にたどってください。

バッチリクエスト： POST /$batch を使用すると、1～20 件の操作を 1 回の呼び出しにまとめられます。

差分クエリ： GET /users/delta を使用すると、@odata.deltaLink を通じて前回のクエリ以降の変更を追跡できます。

エラーレスポンス形式：

{"error": {"code": "Code", "message": "Description"}}

一般的なステータスコード：

• 200/201/204：成功
• 400：無効なリクエスト
• 401：認証が必要です
• 403：アクセス許可が不足しています
• 404：リソースが見つかりません
• 429：レート制限に達しました（Retry-After ヘッダーを確認してください）
• 500-503：サーバーエラー（指数バックオフを実装してください）

リソースファイル一覧

ファイル	主な内容	行数
authentication-apps.md	アプリ登録、OAuth、認証情報	350+
identity-access.md	ユーザー、グループ、組織、ディレクトリ	350+
mail-operations.md	メール、フォルダー、添付ファイル、ルール	400+
calendar-scheduling.md	イベント、定期開催、会議、空き時間／予定あり	350+
files-storage.md	OneDrive、SharePoint、アップロード、共有	400+
teams-communications.md	Teams、チャネル、チャット、プレゼンス	350+
planning-notes.md	Planner、To Do、OneNote	350+
security-governance.md	セキュリティ、コンプライアンス、デバイス、レポート	400+

ベストプラクティス

パフォーマンス： 特定のプロパティには$selectを使用し、ページネーションを実装し、トークンをキャッシュし、一括操作にはバッチ処理を使用し、同期シナリオには差分クエリを適用します

セキュリティ： トークンは安全に保管し（コード内には決して保存しないでください）、最小権限のアクセス許可を要求し、Azure ではマネージド ID を使用し、認証情報を90日ごとにローテーションし、すべての応答を検証します

開発： まずbetaエンドポイントでテストし、非推奨の通知を監視し、再試行には指数バックオフを実装し、レート制限を遵守し、Graph の正常性ステータスを確認します

トラブルシューティング：

• 401 Unauthorized → トークンの有効性とスコープを確認します
• 403 Forbidden → Azure AD でアクセス許可が構成されていることを確認します
• 404 Not Found → リソース ID とリソースが存在することを確認します
• 429 Too Many Requests → 指数バックオフによる再試行を実装します

ツールと SDK のリソース

対話型テスト： Graph Explorer（https://developer.microsoft.com/graph/graph-explorer）

SDK：

• .NET：Microsoft.Graph NuGet
• JavaScript/TypeScript：@microsoft/microsoft-graph-client npm
• Python：msgraph-sdk-python pip

ドキュメント：

• API リファレンス：https://docs.microsoft.com/graph/api/overview
• アクセス許可のリファレンス：https://docs.microsoft.com/graph/permissions-reference
• 変更履歴：https://docs.microsoft.com/graph/changelog

---

スキルバージョン： 2.1 | API バージョン： v1.0（本番）、beta（プレビュー） | 更新日： 2025年12月