Microsoft Graph で Excel レポート自動化 — セッション、テーブル、グラフ画像

ツール Microsoft Graph Excel
読了 5分

週次レポートのたびに誰かが DB から数字を抜き出して Excel に貼り付け、グラフを更新しているなら、その作業は Microsoft Graph 実務入門で扱った道具で丸ごと自動化できます。Graph の workbook API は、OneDrive と SharePoint にある Excel ファイルを開かずに読み書きする API です。この記事ではその中核であるセッション管理、テーブル操作、グラフ画像の取得を整理します。アプリ登録と認証は実務入門 #2 を前提とします。

入り口 — ファイルパスの後ろに /workbook #

workbook API の URL は、ドライブアイテムのアドレスの後ろに /workbook を付ける構造です。

リクエスト例 
GET /me/drive/items/{item-id}/workbook/worksheets
GET /sites/{site-id}/drive/items/{item-id}/workbook/tables

この後ろにワークシート、テーブル、範囲(range)、グラフ、名前定義(named item)がリソースとしてぶら下がります。ファイル自体のアップロード・ダウンロードは実務入門 #5 で扱ったドライブ API の仕事で、workbook API は開いたブックの中身を扱います。

セッション — 性能と保存の有無を決めるスイッチ #

workbook API を使うとき最初に理解すべきなのがセッションです。呼び出し方が 3 つに分かれます。

モード作り方特徴
永続セッションcreateSession に persistChanges: true変更がファイルに保存される。最も効率的で実務のデフォルト
非永続セッションpersistChanges: false変更は一時コピーにだけ適用され、セッション終了で消える
セッションなしヘッダー省略呼び出しごとにサーバーがファイルを探し直す。遅い。単発用
セッション作成 
POST /me/drive/items/{item-id}/workbook/createSession
Content-Type: application/json

{ "persistChanges": true }

レスポンスのセッション ID を、以降のすべての呼び出しに workbook-session-id ヘッダーで渡します。2 回以上呼び出すならセッションを作るのが正解です。サーバーがブックをメモリに載せたまま連続処理するので、呼び出しあたりの遅延が大きく減ります。

非永続セッションは電卓として使うときに輝きます。テンプレートの Excel に値を流し込み、数式の結果やグラフだけを取り出して、ファイルは元のままにしたい場合、persistChanges: false のセッションの中で作業すればファイルに触れずに結果だけ持ち帰れます。テンプレート Excel を計算エンジンとして使うパターンです。

運用の注意点を 2 つ。セッションは無操作で期限切れになります(永続は約 5 分、非永続は約 7 分)。期限切れのセッションで呼び出すと 404 になるので、長い処理は期限切れを前提にセッション再生成のロジックを入れます。またセッション作成に時間がかかることがあり、Prefer: respond-async ヘッダーでの長時間実行パターン(ポーリング)が使えます。時折出る 504 はリトライが正解です。

読み取り — usedRange とテーブル #

シートのデータがある領域だけを読む最も簡単な方法が usedRange です。

usedRange の読み取り 
GET /me/drive/items/{id}/workbook/worksheets/{name}/usedRange

値や書式のある最小の長方形範囲が、values(2 次元配列)、formulas、text とともに返ってきます。特定の領域だけ必要なら range(address='A1:D20') で絞ります。

ただしレポート自動化なら、範囲よりテーブルを基準にするほうがはるかに堅牢です。範囲のアドレスは行が増えるとずれますが、テーブルは名前でアクセスでき、サイズがデータに合わせて自動で伸びるからです。

テーブル読み取りと行追加 
GET  /me/drive/items/{id}/workbook/tables                       # テーブル一覧
GET  /me/drive/items/{id}/workbook/tables('SalesTable')/rows    # 行の読み取り

POST /me/drive/items/{id}/workbook/tables('SalesTable')/rows
{ "values": [["2026-09-15", "キーボード", 12, 348000]] }         # 行の追加

レポートパイプラインの基本形がこれです。元データはテーブルに行として積み、集計はテーブルを参照する数式・ピボット・グラフに自動更新させます。 コードは行の追加だけに責任を持ち、集計は Excel がやります。

グラフ — 作って、画像として取り出す #

レポート自動化の仕上げはグラフです。グラフを追加し、既存グラフの参照範囲を更新し、何より画像としてレンダリングして受け取れます。

グラフ作成と画像取得 
POST /me/drive/items/{id}/workbook/worksheets('Report')/charts/add
{ "type": "ColumnClustered", "sourceData": "A1:B12", "seriesBy": "Auto" }

GET /me/drive/items/{id}/workbook/worksheets('Report')/charts('Chart 1')/image

image 呼び出しは base64 文字列を返します。デコードすれば PNG になるので、メール本文に添付したり(実務入門 #4 のメール送信と組み合わせ)、Teams の通知に入れる流れがコード数行で完成します。「Excel を開いてグラフをキャプチャする」手作業の置き換えです。ひとつ罠があり、グラフ ID には {、} の文字が含まれます。URL に入れるときは必ずエンコード(%7B、%7D)が必要です。

権限 — Excel API は委任中心です #

ここがこの API の最大の実務的制約です。workbook API の権限表を見ると、アプリケーション権限がサポートされないエンドポイントが多くあります(usedRange などは委任の Files.ReadWrite のみ記載)。人なしで回るデーモン自動化を、アプリ権限ひとつできれいに作るのは難しいということです。

実務の選択肢はこう整理できます。

  1. 委任権限 + 自動化アカウント: 専用アカウントで委任トークンを確保して回す方式。Teams 通知でも使われた回避策で(実務入門 #6)、アカウントとトークンの寿命管理が付いてきます。
  2. データ層で解決: 無人自動化が目的なら、Excel は計算・表現の層としてだけ使い、データの投入はアプリ権限が完全なドライブ API で CSV・ファイルを上げる構造に迂回する手もあります。
  3. エンドポイントごとの権限表確認: サポート状況はエンドポイントごとに違い、変わりうるので、使う予定の呼び出しの権限表をドキュメントで確認するのが必須の手順です。

まとめ #

  • workbook API はドライブアイテムの後ろに /workbook を付けて Excel の中身(シート、テーブル、範囲、グラフ)を扱います。ファイルのアップロードはドライブ API の仕事です。
  • 2 回以上呼び出すならセッションを作ります。persistChanges: true が実務のデフォルト、false はファイルに触れない電卓モードです。セッションは数分の無操作で期限切れになるので再生成ロジックが必要です。
  • レポートパイプラインはテーブルへの行追加として作り、集計・グラフ更新は Excel の数式に任せます。
  • グラフは base64 画像として取り出してメール・通知にそのまま入れられます。グラフ ID の波かっこは URL エンコード必須です。
  • Excel API は委任権限中心なので、無人自動化の設計前にエンドポイントごとの権限表確認が必須で、自動化アカウントかデータ層の迂回が現実的な選択肢です。
X