Microsoft Graph における Excel
Excel も OneNote 同様 OneDrive、グループ、SharePoint ドキュメントなど様々な場所に存在します。それぞれの場所において、同一の操作が可能です。Excel は以下の要素で構成されており、それぞれが Microsoft Graph リソースとなります。
- ブック
- ワークシート
- 範囲
- テーブル
- グラフ
Microsoft Graph の Excel API は非常に充実しており、ブックレベルでの取得だけでなく、グラフの操作やテーブル操作までできるため、非常に多くのシナリオに対応します。
ブックリソース
ブックは Excel ファイルそのものです。ブックに対する操作をする際は、永続セッションまた非永続セッションというセッションを作成して操作をします。
- 永続セッション : ブックに加えられたすべての変更が保存されます。(既定)
- 非永続セッション : 変更は元の場所に保存されません。計算の結果やグラフのイメージを取得したりする必要があるが、ドキュメントには影響を与えないシナリオで使います。
主なシナリオ
- セッションの作成、更新、クローズ
- ブック内のリソースの一覧取得
ブックリソースの操作
いくつか代表的な操作を以下に紹介します。
セッションを作成する
ドライブにある Excel ファイルに対してセッションを作成します。永続か非永続かを persistSession に指定します。
POST: https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/createSession
{
"persistSession": true
}
await graphClient.Me.Drive.Items["id"].Workbook.CreateSession(true).Request().PostAsync();
セッションを閉じる
POST: https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/closeSession
workbook-session-id:{session_id}
await graphClient.Me.Drive.Items["id"].Workbook.CloseSession().Request(
new List<Option>() { new HeaderOption("workbook-session-id", "session_id") }
).PostAsync();
ワークシートリソース
Excel ブックのワークシートです。
主なシナリオ
- ワークシートの取得、作成、更新
- ワークシート上の特定セル、範囲や使用領域の取得
- ワークシートに関連するリソースの操作
ワークシートリソースの操作
いくつか代表的な操作を以下に紹介します。
ワークシートの追加
POST: https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/worksheets/
{
"name": "ワークシート名"
}
await graphClient.Me.Drive.Items["id"].Workbook.Worksheets.Request().AddAsync(new WorkbookWorksheet()
{
Name = "ワークシート名"
});
使用範囲の取得
ワークシート上にデータがあるセルの範囲とその値や型、式などをすべて取得できます。
GET: https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/worksheets/{worksheet_id}/usedrange
await graphClient.Me.Drive.Items["id"].Workbook.Worksheets["worksheet_id"].UsedRange().Request().GetAsync();
セルを取得する
ワークシート上の特定のセルを取得します。以下の例では A1 セルを取得しています。
await graphClient.Me.Drive.Items["id"].Workbook.Worksheets["worksheet_id"].Cell(0, 0).Request().GetAsync();
範囲リソース
Excel ブック上の任意の範囲を表すリソースです。
主なシナリオ
- 範囲の取得、更新、挿入、削除
- 範囲に対する書式の取得、更新
- 範囲の結合および結合解除
範囲リソースの操作
いくつか代表的な操作を以下に紹介します。
範囲の取得する
範囲を示すアドレスを指定して範囲を取得。以下の例は A1 から D3 の範囲を取得。
await graphClient.Me.Drive.Items["id"].Workbook.Worksheets["worksheet_id"].Range("A1:D3").Request().GetAsync();
範囲を更新する
任意の範囲の値を更新します。以下の例では A2 から B3 の 4 つのセルの値を更新しています。それぞれの列は配列をして表します。ここでは値だけを更新していますが、式や書式なども変更可能です。
{
"values" : [["de:code2018", "5/22/2018"],["de:code2018", "5/23/2018"]]
}
var values = await graphClient.Me.Drive.Items["id"].Workbook.Worksheets["worksheet_id"].Range("A2:B3").Request().PatchAsync(new WorkbookRange()
{
Values = JToken.Parse("[['de:code2018', '7/22/2018'],['de:code2018', '7/23/2018']]")
});
範囲を削除する
以下の例では、A2 から A3 のセルを削除して、上に詰めています。
{
"shift": "up"
}
C# SDK には現時点ではこの操作はサポートされていません。HttpClient を利用してください。
テーブルリソース
Excel ブック上の任意のテーブルを表すリソースです。
主なシナリオ
- テーブルの取得、追加、更新、削除
- 行や列の作成
- 範囲の操作
テーブルリソースの操作
いくつか代表的な操作を以下に紹介します。
テーブルの一覧および特定テーブルの取得
以下の例はワークブック内のすべてのテーブルや特定テーブルを取得しています。
GET: https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/tables
GET: https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/tables/{table_id}
await graphClient.Me.Drive.Items["id"].Workbook.Tables.Request().GetAsync();
await graphClient.Me.Drive.Items["id"].Workbook.Tables["table_id"].Request().GetAsync();
グラフリソース
Excel ブック上の任意のグラフを表すリソースです。
主なシナリオ
- グラフの取得、追加、更新、削除
- グラフの画像を取得
- グラフのデータをリセット
- 位置データの設定
グラフリソースの操作
いくつか代表的な操作を以下に紹介します。
グラフの作成
以下の例では A1 から C5 の範囲のデータを対象に、積み上げ式縦棒グラフを作っています。
POST: https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/worksheets/{worksheet_id}/charts/add
{
"type": "ColumnStacked",
"sourceData": "A1:C5",
"seriesBy": "Auto"
}
await graphClient.Me.Drive.Items["id"].Workbook.Worksheets["worksheet_id"].Charts.Add("ColumnStacked", "Auto", "A1:C5").Request().PostAsync();
グラフの画像を取得
結果は base64 文字列で返ります。
C# のメソッドは以下の通りですが、現時点ではうまく動きませんでした。HttpClient を使って直接 URL 呼び出ししてください。
await graphClient.Me.Drive.Items["id"].Workbook.Worksheets["worksheet_id"].Charts["chart_id"].Image().Request().GetAsync();
まとめ
Microsoft Graph を利用した Excel 操作は、非常に多くのことが出来るため、Excel 自動化の観点からも利用が大いに期待できます。
参照
Microsoft Graph での Excel 操作
Microsoft Graph でのブック操作
Microsoft Graph でのワークシート操作
Microsoft Graph での範囲操作
Microsoft Graph でのテーブル操作
Microsoft Graph でのグラフ操作