Microsoft Graph 実務入門 #1 Graph とは — Microsoft 365 全体を開く一つの API

ツール Microsoft Graph Microsoft 365
読了 7分

会社で Microsoft 365 を使っているなら、あなたの組織にはすでに膨大なデータが一か所に集まっています。全社員のメールとカレンダー(Outlook)、組織図とアカウント(Entra ID)、ファイル(OneDrive・SharePoint)、会話(Teams)が全部ここに該当します。Microsoft Graph はこの全部を一つの API で開く扉です。「毎週月曜にチームのカレンダーを集めて Teams に要約を投稿する」「退職者アカウントのファイルを自動でバックアップする」「レポートを生成してメールで配信する」— こうした社内自動化は、すべてこの扉の向こうにあります。

このシリーズは 7 回にわたって、Graph を実務の自動化の観点で扱います。今回は全体の地図を描き、第 2 回で認証(アプリ登録、delegated と application 権限)、第 3 回で Python SDK の最初の呼び出し、第 4 回でメール・カレンダー、第 5 回でファイル(OneDrive・SharePoint)、第 6 回で Teams、第 7 回で運用(スロットリング、ページネーション、delta、変更通知)を扱います。

「一つのエンドポイント」が意味すること #

Graph 以前の Microsoft の API は製品ごとにばらばらでした。Exchange は EWS、SharePoint は独自の REST/CSOM、Entra ID(旧 Azure AD)はまた別の API を使っていました。製品ごとに認証方式と SDK が違うので、「メールを読んで SharePoint に保存する」という単純な自動化にも、二つの別世界を学ぶ必要がありました。

Graph はこれを一つに統合しました。すべてのリクエストを同じ API の入口から送れます。

Graph の URL 構造 
https://graph.microsoft.com/{バージョン}/{リソース}

GET https://graph.microsoft.com/v1.0/me                  # 自分のプロフィール
GET https://graph.microsoft.com/v1.0/me/messages         # 自分のメール
GET https://graph.microsoft.com/v1.0/me/calendar/events  # 自分の予定
GET https://graph.microsoft.com/v1.0/users               # 組織のユーザー一覧
GET https://graph.microsoft.com/v1.0/me/drive/root/children  # OneDrive のルート
GET https://graph.microsoft.com/v1.0/teams/{id}/channels     # チームのチャネル一覧

URL を読む感覚がそのまま Graph を読む感覚です。me は「認証されたユーザー自身」で、users/{id} に置き換えれば(権限があれば)他のユーザーを指します。リソースは階層でつながります。me → drive → root → children のように所有関係をパスでたどる構造なので、慣れるとドキュメントを見る前に URL を推測できるほど一貫しています。

認証も一つに統合されました。どのリソースを扱うにも Entra ID が発行するトークン一つで認証し、何ができるかはトークンに含まれる権限(スコープ)が決めます。この権限モデルが Graph 学習の実質的な関門で、第 2 回を丸ごとこのテーマに充てます。

v1.0 と beta — どちらを使うか #

URL のバージョンの位置には v1.0 と beta の二つが入ります。ルールは明確です。

  • v1.0 — 正式サポートのバージョンです。後方互換性が管理され、本番はここにだけ依存すべきです。
  • beta — プレビューです。新機能が先に来ますが、予告なく変わったり消えたりします。実験と検証にだけ使い、運用コードに入れないのが原則です。

実務でよくある事故は、beta にしかないフィールドを使っていて、ある日レスポンスの形が変わって自動化が静かに壊れるケースです。ドキュメントを見るとき、ページ上部のバージョン選択が v1.0 かを常に確認する習慣が必要です。

何ができるか — リソースの地図 #

Graph が開く領域を実務の自動化シナリオでまとめるとこうなります。

領域代表リソース自動化の例
組織・アカウント (Entra ID)users, groups入退社処理、組織図の同期、アカウント監査
メール (Outlook)messages, mailFoldersレポート配信、受信箱の仕分け、添付の収集
カレンダー (Outlook)events, calendars会議室の利用状況、チーム予定の集計、予定の自動作成
ファイル (OneDrive・SharePoint)drives, driveItems, sites文書バックアップ、成果物アップロード、共有リンク
コラボレーション (Teams)teams, channels, chatMessages通知の配信、チャネルのアーカイブ、メッセージ収集
セキュリティ・管理auditLogs, signIns, reportsサインイン監査、利用状況レポート

先に押さえておきたいポイントが一つあります。Graph の力は個別の機能ではなく、これらの領域が一つのトークン、一つの SDK の中で組み合わさることにあります。「SharePoint の名簿を読んで → 各ユーザーのカレンダーを確認して → 結果をメールで送って → Teams に要約を残す」が一つのスクリプトになります。

OData — 一覧を扱う共通の文法 #

一覧型のリソースには OData クエリパラメータという共通の文法が適用されます。どのリソースでも同じように動くので、一度覚えれば全領域で使えます。

OData クエリの例 
# 必要なフィールドだけ (レスポンス削減 — 実務の基本)
GET /v1.0/me/messages?$select=subject,from,receivedDateTime

# 条件フィルタ
GET /v1.0/users?$filter=department eq 'Engineering'

# ソート + 件数制限
GET /v1.0/me/messages?$orderby=receivedDateTime desc&$top=10

# 件数だけ
GET /v1.0/users/$count

特に $select は習慣にする価値があります。Graph のデフォルトのレスポンスはフィールドが多いので、必要なものだけ選べばレスポンスの大きさと処理時間が大きく減り、第 7 回で扱うスロットリングの予算も節約できます。

Graph Explorer — コードなしで今日始める #

Graph の最良の学習ツールは、Microsoft が提供するウェブコンソールの Graph Explorer です(アドレスは aka.ms/ge です)。ブラウザで Graph のリクエストを直接実行でき、二つのモードがあります。

  • サインインなし — サンプル組織の架空データを相手にリクエストを練習できます。いますぐ GET /v1.0/me を実行できるという意味です。
  • 会社アカウントでサインイン — 自分のアカウントの実データで実行されます。リクエストごとに必要な権限を教えてくれて、その場で同意(consent)できるので、第 2 回で扱う権限の概念を手を動かして覚えるのに最適です。

Explorer にはもう一つ実務的な使い道があります。右側のコードスニペットタブが、いま実行したリクエストを各言語の SDK コードに変換してくれます。「Explorer でリクエストを完成させて → コードに移す」は、このシリーズ全体で繰り返す作業の流れです。

何が Graph ではないか — 境界線 #

過度な期待を避けるために、境界も押さえておきます。

  • Azure のリソース管理は Graph ではありません。 VM を作りストレージを管理するのは Azure Resource Manager(ARM)API の領域です。Graph は Microsoft 365 と Entra ID のデータを扱います。
  • Power Automate との関係 — ノーコード自動化ツールの Power Automate のコネクタも、内部ではかなりの部分 Graph を呼んでいます。クリック数回で済む単純なフローは Power Automate が速く、条件が複雑だったり、既存システムと絡んだり、バージョン管理が必要だったりする自動化には Graph の直接呼び出しが向いています。このシリーズが扱うのは後者です。
  • オンプレミスの Exchange・SharePoint サーバーは対象外です。Graph はクラウド(Microsoft 365)の API です。

まとめ #

  • Microsoft Graph は、メール、カレンダー、ファイル、Teams、組織データまで、Microsoft 365 全体を graph.microsoft.com 一つで開く統合 API です。認証も Entra ID のトークン一つに統一されています。
  • 本番は v1.0 だけを使います。beta は予告なく変わるプレビューです。
  • URL は me、users/{id}、所有関係の階層パスで読み、一覧は OData($select、$filter、$top)という共通の文法で扱います。$select は習慣にします。
  • Graph Explorer でコードなしに今日始められ、完成したリクエストを SDK コードに変換するスニペットタブが実務の作業の流れの出発点です。
  • Graph の力は領域の組み合わせです。名簿を読み、予定を確認し、メールを送り、Teams に残すことが一つのスクリプトになります。

次回はこの扉を開ける鍵、認証です。Entra ID のアプリ登録から delegated と application 権限の違い、管理者の同意まで扱います。シリーズで最も重要な回です。

X