Работа с Excel в Microsoft Graph
Важно!
API версии /beta в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.
С помощью Microsoft Graph можно разрешать веб-приложениям и мобильным приложениям считывать и изменять книги Excel, хранящиеся в OneDrive, SharePoint или на других поддерживаемых платформах хранения. Ресурс Workbook (или файл Excel) содержит все остальные ресурсы Excel благодаря отношениям. Можно получить доступ к книге через интерфейс API Drive, указав расположение файла в URL-адресе. Например:
https://graph.microsoft.com/beta/me/drive/items/{id}/workbook/
https://graph.microsoft.com/beta/me/drive/root:/{item-path}:/workbook/
Вы можете получить доступ к набору объектов Excel (например, Table, Range или Chart) с помощью стандартных REST API, чтобы выполнять с книгой операции CRUD (создание, чтение, обновление и удаление). Например, https://graph.microsoft.com/beta/me/drive/items/{id}/workbook/
возвращает коллекцию объектов листа, включенных в книгу.
Примечание: REST API Excel поддерживает только книги в формате Office Open XML. Книги .xls расширений не поддерживаются.
Авторизация и области
Для проверки подлинности API Excel можно использовать конечную точку Microsoft Entra версии 20. Для всех API требуется заголовок HTTP Authorization: Bearer {access-token}.
Для использования ресурса Excel требуется одна из указанных ниже областей разрешений.
- Files.Read;
- Files.ReadWrite.
Сеансы и сохраняемость
Интерфейсы API Excel можно вызвать в одном из двух режимов.
- Постоянный сеанс — все изменения, внесенные в книгу, сохраняются (сохраненные). Это обычный режим работы.
- Неперсистентный сеанс — изменения, внесенные API, не сохраняются в исходном расположении. Вместо этого внутренний сервер Excel сохраняет временную копию файла, в которой отражены изменения, внесенные во время конкретного сеанса API. Когда истечет срок действия сеанса Excel, изменения будут потеряны. Этот режим удобен для приложений, которым нужно выполнять анализ или получать результаты вычислений или изображение диаграммы, не изменяя состояние документа.
Чтобы представить сеанс в API, воспользуйтесь заголовком workbook-session-id: {session-id}.
Примечание: Заголовок сеанса не требуется для работы API Excel. Однако для повышения производительности рекомендуется использовать заголовок сеанса. Если вы не используете заголовок сеанса, изменения, внесенные во время вызова API, сохраняются в файле.
Вызов API для получения сеанса
Запрос
Передайте объект JSON, установив для параметра persistchanges значение true или false.
POST https://graph.microsoft.com/beta/me/drive/items/01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN/workbook/createSession
content-type: Application/Json
authorization: Bearer {access-token}
{ "persistChanges": true }
Если для параметра задано persistChanges значение false, возвращается идентификатор сеанса, не относящееся к методу .
Отклик
HTTP code: 201 Created
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#microsoft.graph.sessionInfo",
"id": "{session-id}",
"persistChanges": true
}
Применение
Идентификатор сеанса, возвращенный из предыдущего вызова, передается в качестве заголовка при последующих запросах API в
заголовке HTTP workbook-session-id.
GET https://graph.microsoft.com/beta/me/drive/items/01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN/workbook/worksheets
authorization: Bearer {access-token}
workbook-session-id: {session-id}
Примечание. Если срок действия идентификатора сеанса истек, для сеанса будет возвращен код ошибки HTTP
404. В таком случае вы можете создать другой сеанс и продолжить работу. Можно использовать другой подход — периодически обновлять сеанс, чтобы он не был завершен. Обычно срок действия сохраняемого сеанса истекает через 5 минут бездействия. Срок действия несохраняемого сеанса истекает через 7 минут бездействия.
Стандартные сценарии Excel
В этом разделе приводятся примеры использования стандартных операций для объектов Excel.
Операции с листами
Список листов, являющихся частью книги
Запрос
GET https://graph.microsoft.com/beta/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/beta/$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/beta/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/beta/$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"
}
** Примечание. Листы также можно получить с помощью идентификатора. Однако в настоящее время идентификатор содержит символы { и "}", которые должны быть закодированы в URL-адресе, чтобы API работал. Пример. Чтобы получить лист с идентификатором {75A18F35-34AA-4F44-97CC-FDC3C05D9F40}, URL-адрес закодирует идентификатор в пути как /workbook/worksheets/%7B75A18F35-34AA-4F44-97CC-FDC3C05D9F40%7D.
Удаление листа
Запрос
DELETE https://graph.microsoft.com/beta/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/beta/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/beta/$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/beta/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/beta/$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
}
]
}
** Примечание. Идентификатор диаграммы содержит символы { и } (например, {00000000-0008-0000-0100-000003000000}), которые должны быть закодированы в URL-адресе, чтобы API работал. Пример. Чтобы получить объект диаграммы, URL-адрес закодирует идентификатор в пути как /charts/%7B00000000-0008-0000-0100-000003000000%7D.
Получение изображения диаграммы
Запрос
GET https://graph.microsoft.com/beta/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/beta/$metadata#Edm.String",
"value": "{base-64-string}"
}
Добавление диаграммы
Запрос
POST https://graph.microsoft.com/beta/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/beta/$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/beta/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/beta/$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/beta/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/beta/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/beta/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables/$/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/beta/$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/beta/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/beta/$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/beta/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/beta/$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/beta/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/beta/$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/beta/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/beta/$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/beta/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/beta/$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/beta/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/beta/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/beta/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/beta/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/beta/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/beta/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/beta/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/worksheets('test')/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/beta/$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/beta/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/beta/$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/beta/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/beta/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/beta/$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
Входное значение null в двумерном массиве
Входное значение null в двумерном массиве (для значений, числового формата, формулы) игнорируется в ресурсах Range и Table. Обновление предполагаемого целевого объекта (ячейки) не выполняется, когда null входные данные отправляются в виде значений или в числовом формате или сетке значений формул.
Например, чтобы обновить только определенные части Range, такие как числовой формат ячейки, и сохранить существующий числовой формат в других частях Range, установите числовой формат там, где это необходимо, и отправьте null для других ячеек.
В приведенном ниже запросе задаются только некоторые значения числового формата Range, в то время как в остальных случаях сохраняется имеющийся числовой формат (передаются значения null).
{
"values" : [["Eurasia", "29.96", "0.25", "15-Feb" ]],
"numberFormat" : [[null, null, null, "m/d/yyyy;@"]]
}
Входное значение null для свойства
null не является допустимым одним входным значением для всего свойства. Например, следующее недопустимо, так как для всех значений нельзя задать значение NULL или игнорироваться.
{
"values": null
}
Ниже указано недопустимое значение, так как значение NULL не является допустимым значением цвета.
{
"color" : null
}
Отклик — null
Представление свойств форматирования, состоящих из неуниформных значений, приводит к возврату значения NULL в ответе.
Например, Range может состоять из одной или нескольких ячеек. В случаях, когда отдельные ячейки, содержащиеся в указанном диапазоне, не имеют однородных значений форматирования, представление уровня диапазона не определено.
{
"size: : null,
"color" : null
}
Значение null также возвращается в отклике в указанных ниже случаях.
- Если при попытке получить определенное свойство объекта возникает ошибка, и для такого свойства можно задать значение null, свойство может возвращать в отклике значение null.
- Для объекта Range при получении диапазона для целой строки или целого столбца некоторые свойства могут возвращать значение null в качестве отклика. Если размер диапазона превышает верхнее ограничение (5M ячеек), некоторые свойства возвращают значение NULL в качестве значения.
Пустые входные и выходные данные
Пустые значения в запросах на обновление считаются указанием на очистку или сброс соответствующего свойства. Пустое значение представляется двумя двойными кавычками, не разделенными пробелом: ""
Примеры:
Для
valuesзначение диапазона очищено. Это аналогично очистке содержимого в приложении.Для
numberFormatчисловому формату присвоено значениеGeneral.Для
formulaиformulaLocaleзначения формулы очищены.
При операциях чтения будьте готовы получать пустые значения, если в ячейках нет содержимого. Если ячейка не содержит данных или значений, API возвращает пустое значение. Пустое значение представляется двумя двойными кавычками, не разделенными пробелом: ""
{
"values" : [["", "some", "data", "in", "other", "cells", ""]]
}
{
"formula" : [["", "", "=Rand()"]]
}
Range без ограничений
Чтение
Адрес Range без ограничений содержит только идентификаторы столбцов и строк, а также идентификаторы неопределенных строк и столбцов (соответственно). Пример:
C:C,A:F,A:XFD(содержит неопределенные строки).2:2,1:4,1:1048546(содержит неопределенные столбцы).
Когда API запрашивает Range без ограничений (getRange('C:C')), отклик содержит значение null для свойств на уровне ячеек, например values, text, numberFormat или formula. Другие свойства Range, например address или cellCount, отражают неограниченный диапазон.
Запись
Задание свойств уровня ячеек (например, значений, numberFormat и т. д.) для Range без ограничений не допускается, так как запрос на ввод может оказаться слишком большим для обработки.
Например, следующий запрос на обновление не является допустимым, так как запрошенный диапазон не связан.
PATCH /me/drive/root/workbook/worksheets('Sheet1')/range(address="A:B")
{
"values" : "Due Date"
}
При попытке выполнить операцию обновления для такого диапазона API возвращает ошибку.
Большой диапазон
Большой диапазон — это объект Range, размер которого слишком велик для одного вызова API. Множество факторов, например количество ячеек, значений, объектов numberFormat и формул, могут сделать запрос настолько большим, что он станет неподходящим для взаимодействия с API. Интерфейс API делает все возможное для возврата запрашиваемых данных или записи в них. Но обработка крупного запроса может привести к ошибке API из-за чрезмерного использования ресурсов.
Чтобы избежать этого, рекомендуем выполнять операции чтения и записи для нескольких объектов Range меньшего размера.
Копирование одного входного значения
Для поддержки обновления диапазона с использованием одинаковых значений или числового формата либо для применения одной и той же формулы ко всему диапазону в установленном интерфейсе API используется следующее соглашение. В Excel этот принцип аналогичен вводу значений или формул в диапазон в режиме CTRL+ВВОД.
API ищет значение одной ячейки и, если измерение целевого диапазона не соответствует измерению диапазона входных данных, он применяет обновление ко всему диапазону в модели CTRL+ВВОД со значением или формулой, указанными в запросе.
Примеры
Следующий запрос добавляет в выбранный диапазон текст "Sample text". В запросе диапазон содержит 200 ячеек, тогда как предоставленные входные данные имеют только одно значение ячейки.
PATCH /me/drive/root/workbook/worksheets('Sheet1')/range(address="A1:B100")
{
"values" : "Sample text"
}
Функции книги
Можно получить доступ к функциям книги через коллекцию функций, включенных в ресурс /Functions.
Запрос
https://graph.microsoft.com/beta/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/beta/$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 Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по