Trabalhando com o Excel no Microsoft Graph
Você pode usar o Microsoft Graph para permitir que aplicativos web e dispositivos móveis leiam e modifiquem as pastas de trabalho do Excel armazenadas no OneDrive for Business, o site do SharePoint ou drive do grupo. O recurso Workbook (ou arquivo do Excel) contém todos os outros recursos do Excel por meio de relações. Você pode acessar uma pasta de trabalho por meio da API Drive identificando a localização do arquivo na URL. Por exemplo:
https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/
https://graph.microsoft.com/v1.0/me/drive/root:/{item-path}:/workbook/
Você pode acessar um conjunto de objetos do Excel (como Table, Range ou Chart) usando APIs REST padrão para realizar operações de criação, leitura, atualização e exclusão (CRUD) na pasta de trabalho. Por exemplo, GET https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/worksheets
retorna uma coleção de todos os objetos da planilha que fazem parte da pasta de trabalho.
A API REST do Excel dá suporte apenas a pastas de trabalho formatadas por arquivo XML do Office Open. As .xls pastas de trabalho de extensão não têm suporte.
Observação: o suporte para pastas de trabalho armazenadas na plataforma de Consumidor do OneDrive ainda não está disponível. Neste momento, somente os arquivos armazenados na plataforma de negócios têm suporte por APIs REST do Excel.
Autorização e escopos
Você pode usar o plataforma de identidade da Microsoft para autenticar APIs do Excel. Todas as APIs exigem o cabeçalho HTTP Authorization: Bearer {access-token}.
Um dos seguintes escopos de permissão é obrigatório para usar o recurso do Excel:
- Files.Read (para ações de leitura)
- Files.ReadWrite (para ações de leitura e gravação)
Sessões e persistência
As APIs do Excel podem ser chamadas em um destes três modos:
- Sessão persistente – Todas as alterações feitas na pasta de trabalho são persistentes (salvas). Esse é o modo de operação mais eficiente e com desempenho mais elevado.
- Sessão não persistente – as alterações feitas pela API não são salvas no local de origem. Em vez disso, o servidor back-end do Excel mantém uma cópia temporária do arquivo que reflete as alterações feitas durante essa sessão de API específica. Quando a sessão do Excel expirar, as alterações serão perdidas. Esse modo é útil para aplicativos que precisam fazer uma análise ou obter os resultados de um cálculo ou de uma imagem de gráfico, mas não afeta o estado do documento.
- Sem sessão ‒ a chamada à API é feita sem informações sobre a sessão. Os servidores do Excel precisam localizar a cópia do servidor da pasta de trabalho sempre para executar a operação e, portanto, essa não é uma maneira eficiente de chamar APIs do Excel. É adequado para fazer uma solicitação desativada.
Para representar a sessão na API, use o cabeçalho workbook-session-id: {session-id}.
Observação: O cabeçalho de sessão não é obrigatório para uma API do Excel funcionar. No entanto, recomendamos que você use o cabeçalho de sessão para melhorar o desempenho. Se você não usar um cabeçalho de sessão, as alterações feitas durante a chamada da API serão mantidas como persistentes no arquivo.
Chamada à API para obter uma sessão
Solicitação
Passe um objeto JSON definindo o valor de persistchanges como true ou false.
POST https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN/workbook/createSession
content-type: Application/Json
authorization: Bearer {access-token}
{ "persistChanges": true }
Quando o valor de é definido como false, uma id de persistChanges sessão não persistent é retornada.
Resposta
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
}
Uso
A ID de sessão retornada da chamada anterior é transmitida como um cabeçalho em solicitações de API subsequentes no
cabeçalho HTTP workbook-session-id.
GET https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN/workbook/worksheets
authorization: Bearer {access-token}
workbook-session-id: {session-id}
Observação: se a id da sessão tiver expirado, um código de erro HTTP
404será retornado na sessão. Nesse cenário, você pode optar por criar uma nova sessão e continuar. Outra abordagem seria atualizar a sessão periodicamente para manter a sessão ativa. Geralmente, a sessão persistente expira após cerca de 5 minutos de inatividade. A sessão não persistente expira após cerca de 7 minutos de inatividade.
Cenários comuns do Excel
Esta seção fornece exemplos das operações comuns que você pode usar em objetos do Excel.
Operações de planilha
Listar a parte de planilhas da pasta de trabalho
Solicitação
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}
Resposta
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"
}
]
}
Adicionar uma nova planilha
POST /{version}/me/drive/root:/workbook/worksheets
content-type: Application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{ "name": "Sheet32243" }
Resposta
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"
}
Obter uma nova planilha
Obter uma planilha com base no nome.
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}
Resposta
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"
}
** Observação: as planilhas também podem ser recuperadas usando a ID. No entanto, atualmente, a ID contém { e caracteres '}', que precisam ser codificados em URL para que a API funcione. Exemplo: para obter uma planilha com iD de {75A18F35-34AA-4F44-97CC-FDC3C05D9F40}, a URL codifica a ID no caminho como /workbook/worksheets/%7B75A18F35-34AA-4F44-97CC-FDC3C05D9F40%7D.
Excluir uma planilha
Solicitação
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}
Resposta
HTTP code: 204 No Content
Atualizar as propriedades da planilha
Solicitação
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 }
Resposta
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"
}
Operações de gráfico
Listar gráficos que fazem parte da planilha
Solicitação
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}
Resposta
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
}
]
}
** Observação: a ID do gráfico contém { e } caracteres (exemplo: {00000000-0008-0000-0100-000003000000}), que precisa ser codificada por URL para que a API funcione. Exemplo: para obter um objeto gráfico, a URL codifica a ID no caminho como /charts/%7B00000000-0008-0000-0100-000003000000%7D.
Obter imagem do gráfico
Solicitação
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}
Resposta
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}"
}
Adicionar um gráfico
Solicitação
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" }
Resposta
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
}
Atualizar um gráfico
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 }
Resposta
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
}
Atualizar dados de origem do gráfico
Solicitação
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" }
Resposta
HTTP code: 204 No Content
Operações de tabela
Obter lista de tabelas
Solicitação
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}
Resposta
HTTP code: 200 OK
content-type: application/json;odata.metadata
Criar tabela
Solicitação
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" }
Resposta
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"
}
Atualizar tabela
Solicitação
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" }
Resposta
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"
}
Obter lista de linhas de tabelas
Solicitação
GET https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables('4')/rows
authorization: Bearer {access-token}
workbook-session-id: {session-id}
Resposta
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
]
]
}
]
}
Obter lista de colunas de tabelas
Solicitação
GET https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables('4')/columns
authorization: Bearer {access-token}
workbook-session-id: {session-id}
Resposta
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
]
]
}
]
}
Adicionar uma linha de tabela
Solicitação
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 }
Resposta
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
]
]
}
Adicionar uma coluna de tabela
Solicitação
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 }
Resposta
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"
]
]
}
Excluir linha de tabela
Solicitação
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}
Resposta
HTTP code: 204 No Content
Excluir coluna de tabela
Solicitação
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}
Resposta
HTTP code: 204 No Content
Converter tabela em intervalo
Solicitação
POST https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables('1')/convertToRange
authorization: Bearer {access-token}
workbook-session-id: {session-id}
Resposta
HTTP code: 200 OK
content-type: application/json;odata.metadata
Classificação de tabela
Solicitação
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
}
]
}
Resposta
HTTP code: 204 No Content
Filtro de tabela
Solicitação
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"
}
}
Resposta
HTTP code: 204 No Content
Limpar filtro
Solicitação
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}
Resposta
HTTP code: 204 No Content
Operações de intervalo
Obter intervalo
Solicitação
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}
Resposta
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"
]
]
}
Atualização de intervalo
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"
]
]
}
Classificação de intervalo
Solicitação
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
}
]
}
Resposta
HTTP code: 204 No Content
Itens nomeados
Solicitação
GET https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/names
authorization: Bearer {access-token}
workbook-session-id: {session-id}
Resposta
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
}
]
}
Trabalhar com nulos
entrada nula em uma matriz 2D
A entrada null em uma matriz bidimensional (para valores, formato de número ou fórmula) é ignorada nos recursos Range e Table. Nenhuma atualização ocorre no destino pretendido (célula) quando null a entrada é enviada em valores ou formato de número ou grade de fórmulas de valores.
Por exemplo, para atualizar somente partes específicas de Range, como o formato de número de uma célula, e para manter o formato de número existente em outras partes de Range, defina o formato de número onde for obrigatório e envie null para as outras células.
Na solicitação de definição a seguir, somente algumas partes do formato de número de Range são definidas, enquanto o formato de número existente na parte restante é mantido (por meio da transmissão de nulos).
{
"values" : [["Eurasia", "29.96", "0.25", "15-Feb" ]],
"numberFormat" : [[null, null, null, "m/d/yyyy;@"]]
}
entrada nula para uma propriedade
null não é uma entrada única válida para toda a propriedade. Por exemplo, o seguinte não é válido porque os valores inteiros não podem ser definidos como nulos ou ignorados.
{
"values": null
}
Aqui também não é válido, pois nulo não é um valor de cor válido.
{
"color" : null
}
Resposta nula
Representação de propriedades de formatação que consiste em valores não uniformes que resultam no retorno de um valor nulo na resposta.
Por exemplo, um intervalo pode consistir em uma ou mais células. Nos casos em que as células individuais contidas no Intervalo especificado não têm valores de formatação uniformes, a representação de nível de intervalo é indefinida.
{
"size: : null,
"color" : null
}
Um valor nulo também é retornado na resposta nos seguintes casos:
- Se ocorrer um erro ao tentar obter uma determinada propriedade de um objeto e essa propriedade puder ser definida como nula, a propriedade pode retornar um valor nulo na resposta.
- Para um objeto Range, ao obter um intervalo para linha inteira ou coluna inteira, algumas propriedades podem retornar nulo como a resposta. Se o tamanho do intervalo exceder a limitação superior (células de 5M), algumas propriedades retornarão nulas como o valor.
Entrada e saída em branco
Valores em branco em solicitações de atualização são tratados como uma instrução para limpar ou redefinir a respectiva propriedade. Um valor em branco é representado por aspas duplas sem espaço entre elas: ""
Exemplos:
Para
values, o valor do intervalo é removido. Isso equivale a limpar o conteúdo do aplicativo.Para
numberFormat, o formato de número é definido comoGeneral.Para
formulaeformulaLocale, os valores de fórmula são excluídos.
Para operações de leitura, espera-se receber valores em branco caso o conteúdo das células esteja em branco. Quando a célula não inclui dados ou valores, a API retorna um valor em branco. O valor em branco é representado por aspas duplas sem espaço entre elas: ""
{
"values" : [["", "some", "data", "in", "other", "cells", ""]]
}
{
"formula" : [["", "", "=Rand()"]]
}
Intervalo não associado
Leitura
Um endereço de intervalo não associado contém apenas os identificadores de coluna ou de linha e identificador não especificado de linha ou de coluna, respectivamente, como:
C:C,A:F,A:XFD(inclui linhas não especificadas)2:2,1:4,1:1048546(inclui colunas não especificadas)
Quando a API faz uma solicitação para recuperar um intervalo não associado (getRange('C:C')), a resposta retornada contém null para as propriedades em nível de célula, como values, text, numberFormat ou formula. Outras propriedades de Range, como address ou cellCount, refletirão o intervalo não associado.
Gravação
O sistema não permite a definição de propriedades de nível da célula (como values, numberFormat, etc.) em um intervalo não associado, pois a solicitação de entrada pode ser muito extensa para ser manipulada.
Por exemplo, o seguinte não é uma solicitação de atualização válida porque o intervalo solicitado está desvinculado.
PATCH /me/drive/root/workbook/worksheets/{id}/range(address="A:B")
{
"values" : "Due Date"
}
Quando uma operação de atualização é tentada em tal Intervalo, a API retorna um erro.
Intervalo longo
Um intervalo longo significa um intervalo cujo tamanho é muito grande para uma única chamada de API. Muitos fatores, como o número de células, os valores, os formatos de número e as fórmulas incluídas no intervalo, podem fazer com que a resposta seja tão extensa a ponto de se tornar inadequada para interação com a API. A API faz a melhor tentativa para retornar ou gravar os dados solicitados. No entanto, o tamanho extenso envolvido pode resultar em uma condição de erro da API devido à intensa utilização de recursos.
Para evitar isso, convém fazer leituras ou gravações para um intervalo longo em vários tamanhos de intervalo menores.
Cópia de entrada única
Para dar suporte a atualização de um intervalo com os formatos de número ou valores idênticos, ou para a aplicação de uma mesma fórmula em um intervalo, você deve usar a seguinte convenção na API de configuração. No Excel, esse comportamento é semelhante a inserir valores ou fórmulas em um intervalo no modo Ctrl+Enter.
A API procura um único valor de célula e, se a dimensão do intervalo de destino não corresponder à dimensão do intervalo de entrada, ela aplica a atualização a todo o intervalo no modelo CTRL+Enter com o valor ou a fórmula fornecida na solicitação.
Exemplos
A solicitação a seguir atualiza o intervalo selecionado com "Texto de amostra". O intervalo tem 200 células, enquanto a entrada fornecida tem apenas um valor de célula.
PATCH /me/drive/root/workbook/worksheets/{id}/range(address="A1:B100")
{
"values" : "Sample text"
}
Funções de pasta de trabalho
Você pode acessar as funções de pasta de trabalho por meio de uma coleção de funções incluídas no recurso /Functions.
Solicitação
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
}
Resposta
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
}
Informações do erro
Erros são retornados com um código de erro HTTP e um objeto de erro. Um code de erro e uma message explicam o motivo do erro.
Apresentamos um exemplo a seguir.
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"
}
}
}
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de