Microsoft Graph での Excel の操作
Microsoft Graph を使用すると、OneDrive for Business、SharePoint サイト、またはグループ ドライブに格納されている Excel ブックを、Web アプリケーションやモバイル アプリケーションで読み取ったり変更したりすることができます。 Workbook (つまり Excel ファイル) リソースには、リレーションシップを介するその他のすべての Excel リソースが含まれています。 ファイルの場所を URL で指定すれば、ドライブ API でブックにアクセスできます。 以下に例を示します。
https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/
https://graph.microsoft.com/v1.0/me/drive/root:/{item-path}:/workbook/
ブックに対して作成、読み取り、更新、削除 (CRUD) 操作を実行するための標準 REST API を使用して、一連の Excel オブジェクト (テーブル、範囲、グラフなど) にアクセスできます。 たとえば、GET https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/worksheets では、
ワークブックの一部であるワークシート オブジェクトのコレクションが返されます。
Excel REST API では、Office Open XML ファイル形式のブックのみがサポートされています。 .xls拡張ブックはサポートされていません。
注: OneDrive のコンシューマー向けのプラットフォームに保存されたブックは、サポートされていません。 現時点では、ビジネス プラットフォームに格納されているファイルのみが Excel REST API でサポートされています。
承認とスコープ
Microsoft ID プラットフォームを使用して Excel API を認証できます。 すべての API には、Authorization: Bearer {access-token} HTTP ヘッダーが必要です。
Excel リソースを使用するには、以下のいずれかのアクセス許可のスコープが必要です。
- Files.Read (読み取りアクション用)
- Files.ReadWrite (読み取りおよび書き込みアクション用)
セッションと永続化
次の 3 つのモードのいずれかで、Excel API を呼び出すことができます。
- 永続セッション - ブックに加えられたすべての変更は永続化 (保存) されます。 これは、最も効率的でパフォーマンスの高い操作のモードです。
- 非永続的セッション - API によって行われた変更は、ソースの場所に保存されません。 代わりに、その特定の API セッション中に加えられた変更を反映するファイルの一時コピーが Excel のバックエンド サーバーに保持されます。 Excel のセッションの有効期限が切れると、変更は失われます。 分析を行ったり、計算の結果やグラフのイメージを取得したりする必要があるものの、ドキュメントの状態には影響を与えないアプリには、このモードが便利です。
- セッションレス - セッション情報を伴わずに API 呼び出しが行われます。 Excel サーバーは、操作を実行するために毎回ブックのサーバーのコピーを見つける必要があるため、これは Excel API を呼び出す効率的な方法ではありません。 これは、1 つのオフ要求を行う場合に適しています。
API でセッションを表すには、workbook-session-id: {session-id} ヘッダーを使用します。
注: セッション ヘッダーは Excel API が機能するために必要ではありません。 しかし、パフォーマンスを向上させるためにセッション ヘッダーを使用することをお勧めします。 セッション ヘッダーを使用しない場合は、API の呼び出し時に行われた変更がファイルに永続化されます。
セッションを取得するための API の呼び出し
要求
persistchanges 値を true または false に設定して JSON オブジェクトを渡します。
POST https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN/workbook/createSession
content-type: Application/Json
authorization: Bearer {access-token}
{ "persistChanges": true }
の値 persistChanges が に false設定されている場合は、非永続セッション ID が返されます。
応答
HTTP code: 201 Created
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.sessionInfo",
"id": "{session-id}",
"persistChanges": true
}
使用方法
以前の呼び出しから返されたセッション ID は、後続の API 要求のヘッダーとして渡されます
workbook-session-id HTTP ヘッダー。
GET https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN/workbook/worksheets
authorization: Bearer {access-token}
workbook-session-id: {session-id}
注: セッション ID の有効期限が切れていた場合、そのセッションで
404HTTP エラー コードが返されます。 このようなシナリオでは、新しいセッションを作成して続行できます。 または、定期的にセッションを更新して維持するという方法もあります。 通常、永続セッションの有効期限は、非アクティブ状態が約 5 分間経過した後に切れます。 非永続セッションの有効期限は、非アクティブ状態が約 7 分間経過した後に切れます。
一般的な Excel のシナリオ
このセクションでは、Excel オブジェクトで使用できる一般的な操作の例を示します。
ワークシート操作
ブックのワークシート部分の一覧表示
要求
GET https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN/workbook/worksheets
accept: Application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
応答
HTTP code: 200 OK
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN')/workbook/worksheets",
"value": [
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN')/workbook/worksheets(%27%7B00000000-0001-0000-0000-000000000000%7D%27)",
"id": "{00000000-0001-0000-0000-000000000000}",
"name": "Sheet1",
"position": 0,
"visibility": "Visible"
},
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN')/workbook/worksheets(%27%7B00000000-0001-0000-0100-000000000000%7D%27)",
"id": "{00000000-0001-0000-0100-000000000000}",
"name": "Sheet57664",
"position": 1,
"visibility": "Visible"
}
]
}
新しいワークシートの追加
POST /{version}/me/drive/root:/workbook/worksheets
content-type: Application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{ "name": "Sheet32243" }
応答
HTTP code: 201 Created
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/{version}/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/root/$entity",
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN')/workbook/worksheets(%27%7B75A18F35-34AA-4F44-97CC-FDC3C05D9F40%7D%27)",
"id": "{75A18F35-34AA-4F44-97CC-FDC3C05D9F40}",
"name": "Sheet32243",
"position": 5,
"visibility": "Visible"
}
新しいワークシートの取得
名前に基づいてワークシートを取得します。
GET https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN/workbook/worksheets/Sheet32243
content-type: Application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
応答
HTTP code: 200 OK
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN')/workbook/worksheets/$entity",
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN')/workbook/worksheets(%27%7B75A18F35-34AA-4F44-97CC-FDC3C05D9F40%7D%27)",
"id": "{75A18F35-34AA-4F44-97CC-FDC3C05D9F40}",
"name": "Sheet32243",
"position": 5,
"visibility": "Visible"
}
** 注: ワークシートは ID を使用して取得することもできます。 ただし、現在、ID にはおよび '}' 文字が含まれています { 。API を機能させるには URL エンコードする必要があります。 例: ID が のワークシートを取得するには、パス内の {75A18F35-34AA-4F44-97CC-FDC3C05D9F40}ID を として /workbook/worksheets/%7B75A18F35-34AA-4F44-97CC-FDC3C05D9F40%7DURL でエンコードします。
ワークシートの削除
要求
DELETE https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN/workbook/worksheets('%7B75A18F35-34AA-4F44-97CC-FDC3C05D9F40%7D')
content-type: Application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
応答
HTTP code: 204 No Content
ワークシート プロパティの更新
要求
PATCH https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN/workbook/worksheets/SheetA
content-type: Application/Json
accept: application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{ "name": "SheetA", "position": 3 }
応答
HTTP code: 200 OK
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN')/workbook/worksheets/$entity",
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN')/workbook/worksheets(%27%7B00000000-0001-0000-0100-000000000000%7D%27)",
"id": "{00000000-0001-0000-0100-000000000000}",
"name": "SheetA",
"position": 3,
"visibility": "Visible"
}
グラフ操作
ワークシートの一部になっているグラフを一覧表示する
要求
GET https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJB6K563VVUU2ZC2FJBAHLSZZQXL/workbook/worksheets('%7B00000000-0001-0000-0000-000000000000%7D')/charts
accept: Application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
応答
HTTP code: 200 OK
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJB6K563VVUU2ZC2FJBAHLSZZQXL')/workbook/worksheets('%7B00000000-0001-0000-0000-000000000000%7D')/charts",
"value": [
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJB6K563VVUU2ZC2FJBAHLSZZQXL')/workbook/worksheets(%27%7B00000000-0001-0000-0000-000000000000%7D%27)/charts(%27%7B00000000-0008-0000-0100-000003000000%7D%27)",
"height": 235.5,
"id": "{00000000-0008-0000-0100-000003000000}",
"left": 276.0,
"name": "Chart 2",
"top": 0.0,
"width": 401.25
}
]
}
** 注: グラフ ID には、API を機能させるために URL エンコードする必要がある文字と}文字 (例: {00000000-0008-0000-0100-000003000000}) が含まれています{。 例: グラフ オブジェクトを取得するために、URL はパス内の ID を として /charts/%7B00000000-0008-0000-0100-000003000000%7Dエンコードします。
グラフの画像を取得する
要求
GET https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJB6K563VVUU2ZC2FJBAHLSZZQXL/workbook/worksheets('%7B00000000-0001-0000-0000-000000000000%7D')/charts('%7B00000000-0008-0000-0100-000003000000%7D')/Image(width=0,height=0,fittingMode='fit')
authorization: Bearer {access-token}
workbook-session-id: {session-id}
応答
HTTP code: 200 OK
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Edm.String",
"value": "{base-64-string}"
}
グラフの追加
要求
POST https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJB6K563VVUU2ZC2FJBAHLSZZQXL/workbook/worksheets('%7B00000000-0001-0000-0000-000000000000%7D')/charts/Add
content-type: Application/Json
accept: application/Json
authorization: Bearer {access-token}
{ "type": "ColumnClustered", "sourcedata": "A1:C4", "seriesby": "Auto" }
応答
HTTP code: 201 Created
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#chart",
"@odata.type": "#microsoft.graph.workbookChart",
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJB6K563VVUU2ZC2FJBAHLSZZQXL')/workbook/worksheets(%27%7B00000000-0001-0000-0000-000000000000%7D%27)/charts(%27%7B2D421098-FA19-41F7-8528-EE7B00E4BB42%7D%27)",
"height": 216.0,
"id": "{2D421098-FA19-41F7-8528-EE7B00E4BB42}",
"left": 0.0,
"name": "Chart 2",
"top": 0.0,
"width": 360.0
}
グラフの更新
PATCH https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJB6K563VVUU2ZC2FJBAHLSZZQXL/workbook/worksheets('%7B00000000-0001-0000-0000-000000000000%7D')/charts('%7B2D421098-FA19-41F7-8528-EE7B00E4BB42%7D')
content-type: Application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{ "height": 216.0, "left": 0, "name": "NewName", "top": 0, "width": 360.0 }
応答
HTTP code: 200 OK
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJB6K563VVUU2ZC2FJBAHLSZZQXL')/workbook/worksheets('%7B00000000-0001-0000-0000-000000000000%7D')/charts/$entity",
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJB6K563VVUU2ZC2FJBAHLSZZQXL')/workbook/worksheets(%27%7B00000000-0001-0000-0000-000000000000%7D%27)/charts(%27%7B2D421098-FA19-41F7-8528-EE7B00E4BB42%7D%27)",
"height": 216.0,
"id": "{2D421098-FA19-41F7-8528-EE7B00E4BB42}",
"left": 0.0,
"name": "NewName",
"top": 0.0,
"width": 360.0
}
グラフのソース データの更新
要求
POST https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJB6K563VVUU2ZC2FJBAHLSZZQXL/workbook/worksheets('%7B00000000-0001-0000-0000-000000000000%7D')/charts('%7B2D421098-FA19-41F7-8528-EE7B00E4BB42%7D')/setData
content-type: Application/Json
accept: application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{ "sourceData": "A1:C4", "seriesBy": "Auto" }
応答
HTTP code: 204 No Content
テーブルの操作
テーブル一覧の取得
要求
GET https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJB6K563VVUU2ZC2FJBAHLSZZQXL/workbook/worksheets('%7B00000000-0001-0000-0000-000000000000%7D')/tables
accept: Application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
応答
HTTP code: 200 OK
content-type: application/json;odata.metadata
テーブルの作成
要求
POST https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables/{table-id}/add
content-type: Application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{ "name": "NewTableName", "hasHeaders": true, "showTotals": false, "style": "TableStyleMedium4" }
応答
HTTP code: 201 Created
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables/$entity",
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%272%27)",
"id": "2",
"name": "NewTableName",
"showHeaders": true,
"showTotals": false,
"style": "TableStyleMedium4"
}
テーブルの更新
要求
PATCH https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables('2')
content-type: Application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{ "name": "NewTableName", "showHeaders": true, "showTotals": false, "style": "TableStyleMedium4" }
応答
HTTP code: 200 OK
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables/$entity",
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%272%27)",
"id": "2",
"name": "NewTableName",
"showHeaders": true,
"showTotals": false,
"style": "TableStyleMedium4"
}
テーブル行の一覧の取得
要求
GET https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables('4')/rows
authorization: Bearer {access-token}
workbook-session-id: {session-id}
応答
HTTP code: 200 OK
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables('4')/rows",
"value": [
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%274%27)/rows/itemAt(0)",
"index": 0,
"values": [
[
42019,
53,
34
]
]
},
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%274%27)/rows/itemAt(1)",
"index": 1,
"values": [
[
42020,
45,
39
]
]
},
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%274%27)/rows/itemAt(2)",
"index": 2,
"values": [
[
42021,
50,
31
]
]
},
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%274%27)/rows/itemAt(3)",
"index": 3,
"values": [
[
42022,
43,
39
]
]
},
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%274%27)/rows/itemAt(4)",
"index": 4,
"values": [
[
42023,
45,
41
]
]
},
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%274%27)/rows/itemAt(5)",
"index": 5,
"values": [
[
42024,
52,
40
]
]
}
]
}
テーブル列の一覧の取得
要求
GET https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables('4')/columns
authorization: Bearer {access-token}
workbook-session-id: {session-id}
応答
HTTP code: 200 OK
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables('4')/columns",
"value": [
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%274%27)/columns(%271%27)",
"id": "1",
"index": 0,
"name": "Date",
"values": [
[
"Date"
],
[
42019
],
[
42020
],
[
42021
],
[
42022
],
[
42023
],
[
42024
]
]
},
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%274%27)/columns(%272%27)",
"id": "2",
"index": 1,
"name": "High (F)",
"values": [
[
"High (F)"
],
[
53
],
[
45
],
[
50
],
[
43
],
[
45
],
[
52
]
]
},
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%274%27)/columns(%273%27)",
"id": "3",
"index": 2,
"name": "Low (F)",
"values": [
[
"Low (F)"
],
[
34
],
[
39
],
[
31
],
[
39
],
[
41
],
[
40
]
]
}
]
}
テーブル行の追加
要求
POST https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables('4')/rows
content-type: Application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{ "values": [ [ "Jan-15-2016", "49", "37" ] ], "index": null }
応答
HTTP code: 201 Created
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables('4')/rows/$entity",
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%274%27)/rows(null)",
"index": 6,
"values": [
[
"Jan-15-2016",
49,
37
]
]
}
テーブル列の追加
要求
POST https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables('2')/columns
content-type: Application/Json
accept: application/Json
{ "values": [ [ "Status" ], [ "Open" ], [ "Closed" ] ], "index": 2 }
応答
HTTP code: 201 Created
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables('2')/columns/$entity",
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%272%27)/columns(%274%27)",
"id": "4",
"index": 2,
"name": "Status",
"values": [
[
"Status"
],
[
"Open"
],
[
"Closed"
]
]
}
テーブル行の削除
要求
DELETE https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables('4')/rows/$/itemAt(index=6)
authorization: Bearer {access-token}
workbook-session-id: {session-id}
応答
HTTP code: 204 No Content
テーブル列の削除
要求
DELETE https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables('4')/columns('3')
authorization: Bearer {access-token}
workbook-session-id: {session-id}
応答
HTTP code: 204 No Content
テーブルを範囲に変換する
要求
POST https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables('1')/convertToRange
authorization: Bearer {access-token}
workbook-session-id: {session-id}
応答
HTTP code: 200 OK
content-type: application/json;odata.metadata
テーブルの並べ替え
要求
POST https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN/workbook/worksheets('Sheet15799')/tables('table2')/sort/apply
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{
"fields" : [
{ "key": 0,
"ascending": true
}
]
}
応答
HTTP code: 204 No Content
テーブル フィルター
要求
POST https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN/workbook/worksheets('Sheet15799')/tables('table2')/columns(id='2')/filter/apply
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{
"criteria" :
{ "filterOn": "custom",
"criterion1": ">15",
"operator": "and",
"criterion2": "<50"
}
}
応答
HTTP code: 204 No Content
フィルターのクリア
要求
POST https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN/workbook/worksheets('Sheet15799')/tables('table2')/columns(id='2')/filter/clear
authorization: Bearer {access-token}
workbook-session-id: {session-id}
応答
HTTP code: 204 No Content
範囲の操作
範囲の取得
要求
GET https://graph.microsoft.com/v1.0/me/drive/items/{item-id}/workbook/worksheets/{worksheet-id}/range(address='A1:B2')
authorization: Bearer {access-token}
workbook-session-id: {session-id}
応答
HTTP code: 200 OK
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#range",
"@odata.type": "#microsoft.graph.workbookRange",
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/worksheets(%27%7B00000000-0001-0000-0300-000000000000%7D%27)/range(address=%27A1:B2%27)",
"address": "test!A1:B2",
"addressLocal": "test!A1:B2",
"cellCount": 4,
"columnCount": 2,
"columnHidden": false,
"columnIndex": 0,
"formulas": [
[
"",
""
],
[
"",
""
]
],
"formulasLocal": [
[
"",
""
],
[
"",
""
]
],
"formulasR1C1": [
[
"",
""
],
[
"",
""
]
],
"hidden": false,
"numberFormat": [
[
"General",
"General"
],
[
"General",
"General"
]
],
"rowCount": 2,
"rowHidden": false,
"rowIndex": 0,
"text": [
[
"",
""
],
[
"",
""
]
],
"values": [
[
"",
""
],
[
"",
""
]
],
"valueTypes": [
[
"Empty",
"Empty"
],
[
"Empty",
"Empty"
]
]
}
範囲の更新
PATCH https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/worksheets('test')/range(address='test!A1:B2')
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{ "values": [ [ "Test", "Value" ], [ "For", "Update" ] ] }
HTTP code: 200 OK
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#range",
"@odata.type": "#microsoft.graph.workbookRange",
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/worksheets(%27%7B00000000-0001-0000-0300-000000000000%7D%27)/range(address=%27test!A1:B2%27)",
"address": "test!A1:B2",
"addressLocal": "test!A1:B2",
"cellCount": 4,
"columnCount": 2,
"columnHidden": false,
"columnIndex": 0,
"formulas": [
[
"Test",
"Value"
],
[
"For",
"Update"
]
],
"formulasLocal": [
[
"Test",
"Value"
],
[
"For",
"Update"
]
],
"formulasR1C1": [
[
"Test",
"Value"
],
[
"For",
"Update"
]
],
"hidden": false,
"numberFormat": [
[
"General",
"General"
],
[
"General",
"General"
]
],
"rowCount": 2,
"rowHidden": false,
"rowIndex": 0,
"text": [
[
"Test",
"Value"
],
[
"For",
"Update"
]
],
"values": [
[
"Test",
"Value"
],
[
"For",
"Update"
]
],
"valueTypes": [
[
"String",
"String"
],
[
"String",
"String"
]
]
}
範囲の並べ替え
要求
POST https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN/workbook/worksheets('Sheet15799')/usedRange/sort/apply
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{
"fields" : [
{ "key": 0,
"ascending": true
}
]
}
応答
HTTP code: 204 No Content
名前付きアイテム
要求
GET https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/names
authorization: Bearer {access-token}
workbook-session-id: {session-id}
応答
HTTP code: 200 OK
content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/names",
"value": [
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/names(%27data%27)",
"name": "data",
"type": "Range",
"value": "Range!$A$1:$D$3",
"visible": true
},
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/names(%27myrange%27)",
"name": "myrange",
"type": "Range",
"value": "Range!$E$1:$F$7",
"visible": true
},
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/names(%27range1%27)",
"name": "range1",
"type": "Range",
"value": "Range!$I$1:$M$11",
"visible": true
}
]
}
Null の操作
2 次元配列での null の入力
範囲およびテーブル リソースでは、2 次元配列内の (値、番号書式、数式に対する) null の入力は無視されます。 値または数値形式または数式グリッドの値で入力が送信された場合 null 、目的のターゲット (セル) に対する更新は行われません。
たとえば、範囲の特定の部分 (セルの番号書式など) のみを更新し、範囲のその他の部分では既存の番号書式を保持する場合は、必要な部分で番号書式を設定し、他のセルに対しては null を送信します。
次の設定要求では、範囲内のある部分の番号書式のみを設定し、残りの部分では (null 値を渡すことで) 既存の番号書式を保持します。
{
"values" : [["Eurasia", "29.96", "0.25", "15-Feb" ]],
"numberFormat" : [[null, null, null, "m/d/yyyy;@"]]
}
プロパティに対する null の入力
null は、プロパティ全体に対して有効な 1 つの入力ではありません。 たとえば、値全体を null に設定したり、無視したりできないため、次は無効です。
{
"values": null
}
null は有効な色の値ではないので、ここでは無効です。
{
"color" : null
}
null 応答
均一でない値で構成された書式設定プロパティを表現すると、null 値が応答で返されます。
たとえば、範囲は 1 つ以上のセルで構成できます。 指定された Range に含まれる個々のセルに均一な書式設定値がない場合、範囲レベルの表現は未定義です。
{
"size: : null,
"color" : null
}
null 値は、次の場合にも返されます。
- オブジェクトの特定のプロパティを取得しようとしてエラーが発生し、このプロパティを null に設定できる場合、プロパティは応答で null 値を返すことがあります。
- Range オブジェクトの場合、行全体または列全体の範囲を取得すると、一部のプロパティが応答として null を返すことがあります。 範囲サイズが上限 (5M セル) を超える場合、一部のプロパティは値として null を返します。
空の入力と出力
更新要求にある空の値は、それぞれのプロパティをクリアまたはリセットする命令として扱われます。 空の値は、間にスペースを入れない 2 つの二重引用符によって表されます。""
例:
valuesの場合は、範囲の値がクリアされます。これは、アプリケーションの内容をクリアするのと同じです。numberFormatの場合は、番号書式がGeneralに設定されます。formulaおよびformulaLocaleの場合は、数式の値がクリアされます。
読み取り操作では、セルの内容が空白の場合に空白の値を受け取ることが予想されます。 セルにデータや値が含まれていない場合、API は空の値を返します。 空の値は、間にスペースを入れない 2 つの二重引用符によって表されます。""
{
"values" : [["", "some", "data", "in", "other", "cells", ""]]
}
{
"formula" : [["", "", "=Rand()"]]
}
無制限の範囲
読み取り
無制限の範囲のアドレスは、列識別子のみがあって行識別子が未指定であるか、あるいは行識別子のみがあって列識別子が未指定です。たとえば、次のとおりです。
C:C、A:F、A:XFD(行が未指定)2:2、1:4、1:1048546(列が未指定)
API が無制限の Range (getRange('C:C')) を取得する要求を行うと、返される応答には、、text、 numberFormatformulaなどのvaluesセル レベルのプロパティが含まれますnull。 や cellCount などのaddressその他の Range プロパティは、無制限の範囲を反映します。
書き込み
無制限のセル範囲にセル レベルのプロパティ (values、numberFormat など) を設定することは、入力要求が長すぎて処理できない可能性があるため、許可されていません。
たとえば、要求された範囲が無制限であるため、次は有効な更新要求ではありません。
PATCH /me/drive/root/workbook/worksheets/{id}/range(address="A:B")
{
"values" : "Due Date"
}
このような Range に対して更新操作が試行されると、API はエラーを返します。
広い範囲
広い範囲とは、1 つの API の呼び出しに対してサイズが大きすぎる範囲を意味します。 範囲に含まれる、セル数、値、番号書式、数式などの多くの要因によって、応答のサイズが大きくなりすぎて API での操作に適さなくなることがあります。 API は、要求されたデータを返したり、それに書き込んだりしようと最善を尽くします。 しかし、大きなサイズが関係していると、リソース使用率が大きくなるために、API エラー状態になることがあります。
これを回避するには、広い範囲の読み取りや書き込みは、よりサイズの小さい複数の範囲に分けて実行することをお勧めします。
単一の入力のコピー
同じ値または番号書式での範囲の更新や、範囲全体への同じ数式の適用をサポートするため、set API では以下の方法が用いられています。 Excel では、この動作は、Ctrl+Enter モードで範囲に値や数式を入力することに似ています。
API は 単一のセル値 を検索し、ターゲット範囲ディメンションが入力範囲ディメンションと一致しない場合は、Ctrl + Enter モデルの範囲全体に更新が適用され、要求で指定された値または数式が適用されます。
例
次の要求では、"Sample text" というテキストで選択範囲が更新されます。 範囲には 200 個のセルがあるのに対し、指定された入力にはセル値が 1 つだけです。
PATCH /me/drive/root/workbook/worksheets/{id}/range(address="A1:B100")
{
"values" : "Sample text"
}
ブックの関数
/Functions リソースに含まれている関数のコレクションを介して、ブックの関数にアクセスできます。
要求
https://graph.microsoft.com/v1.0/me/drive/root:/book1.xlsx:/workbook/functions/pmt
content-type: Application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{
"rate": 4.5,
"nper": 12,
"pv": -1250
}
応答
HTTP code: 200 OK
content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#workbookFunctionResult",
"@odata.type": "#microsoft.graph.workbookFunctionResult",
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/root/workbook/functions/pmt()",
"error": null,
"value": 5625.00000734125
}
エラー情報
HTTP エラー コードとエラー オブジェクトで、エラーが返されます。 エラー code と message は、エラーの原因を説明します。
次に例を示します。
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": {
"code": "ItemAlreadyExists",
"message": "A resource with the same name or identifier already exists.",
"innerError": {
"request-id": "214ca7ea-9ea4-442e-9c67-71fdda0a559c",
"date": "2016-07-28T03:56:09"
}
}
}
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示