Trabajar con Excel en Microsoft Graph
Puede utilizar Microsoft Graph para permitir que las aplicaciones web y móviles lean y modifiquen los libros de Excel almacenados en OneDrive para la Empresa, sitios de SharePoint o unidad de grupo. El recurso Workbook (o el archivo de Excel) contiene todos los demás recursos de Excel mediante relaciones. Puede acceder a un libro a través de la API de Drive si identifica la ubicación del archivo en la dirección URL. Por ejemplo:
https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/
https://graph.microsoft.com/v1.0/me/drive/root:/{item-path}:/workbook/
Puede obtener acceso a un conjunto de objetos de Excel (como una tabla, intervalo o gráfico) mediante las API de REST estándares para realizar operaciones de creación, lectura, actualización y eliminación (CRUD) en el libro. Por ejemplo: GET https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/worksheets
devuelve una colección de objetos de hoja de cálculo que forman parte del libro.
La API REST de Excel solo admite libros con formato de archivo Open XML de Office. No .xls se admiten los libros de extensión.
Nota: Aún no se admiten los libros almacenados en la plataforma para consumidores de OneDrive. En este momento, solo las API REST de Excel admiten los archivos almacenados en la plataforma empresarial.
Autorización y ámbitos
Puede usar el Plataforma de identidad de Microsoft para autenticar las API de Excel. Todas las API requieren el encabezado HTTP Authorization: Bearer {access-token}.
Uno de los siguientes ámbitos de permiso es necesario para utilizar el recurso de Excel:
- Files.Read (para acciones de lectura)
- Files.ReadWrite (para acciones de lectura y escritura)
Sesiones y persistencia
Se puede llamar a las API de Excel de tres modos:
- Sesión persistente - Todos los cambios realizados en el libro son persistentes (se guardan). Este es el modo de operación más eficiente y eficaz.
- Sesión no persistente: los cambios realizados por la API no se guardan en la ubicación de origen. En su lugar, el servidor backend de Excel conserva una copia temporal del archivo que refleja los cambios realizados durante esa sesión API en concreto. Cuando expira la sesión de Excel, se pierden los cambios. Este modo es útil para aplicaciones que necesitan realizar análisis u obtener los resultados de un cálculo o una imagen de gráfico, pero no afecta al estado de documento.
- Sin sesión - Se realiza la llamada a la API sin información de la sesión. Los servidores de Excel tienen que buscar la copia del servidor del libro cada vez para realizar la operación y, por tanto, esta no es una manera eficaz de llamar a las API de Excel. Es adecuado para realizar una solicitud off.
Para representar la sesión en la API, utilice el encabezado workbook-session-id: {session-id}.
Nota: El encabezado de sesión no es necesario para que funcione una API de Excel. Sin embargo, recomendamos que utilice el encabezado de sesión para mejorar el rendimiento. Si no utiliza un encabezado de sesión, los cambios realizados durante la llamada API sí persisten en el archivo.
Llamada API para obtener una sesión
Solicitud
Transmita un objeto JSON estableciendo el valor persistchanges en true o false.
POST https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN/workbook/createSession
content-type: Application/Json
authorization: Bearer {access-token}
{ "persistChanges": true }
Cuando el valor de persistChanges se establece en false, se devuelve un identificador de sesión no persistente.
Respuesta
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
El identificador de sesión devuelto de la llamada anterior se pasa como un encabezado en las subsiguientes solicitudes API en
el encabezado 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}
Nota: Si el identificador de sesión ha caducado, se devuelve un código de error HTTP
404en la sesión. En este tipo de escenario, puede crear una nueva sesión y continuar. Otra solución sería actualizar la sesión periódicamente para mantener la sesión activa. Normalmente, la sesión persistente caduca después de 5 minutos de inactividad. La sesión no persistente caduca después de 7 minutos de inactividad.
Escenarios comunes de Excel
Esta sección proporciona ejemplos de las operaciones comunes que puede utilizar en objetos de Excel.
Operaciones de hojas de cálculo
Enumerar las hojas de cálculo que forman parte del libro
Solicitud
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}
Respuesta
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"
}
]
}
Agregar una hoja de cálculo nueva
POST /{version}/me/drive/root:/workbook/worksheets
content-type: Application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{ "name": "Sheet32243" }
Respuesta
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"
}
Obtener una hoja de cálculo nueva
Obtener una hoja de cálculo basada en el nombre.
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}
Respuesta
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"
}
** Nota: Las hojas de cálculo también se pueden recuperar con el identificador. Sin embargo, actualmente el identificador contiene { y caracteres "}", que deben codificarse como dirección URL para que la API funcione. Ejemplo: para obtener una hoja de cálculo con el identificador de {75A18F35-34AA-4F44-97CC-FDC3C05D9F40}, la dirección URL codifica el identificador en la ruta de acceso como /workbook/worksheets/%7B75A18F35-34AA-4F44-97CC-FDC3C05D9F40%7D.
Eliminar una hoja de cálculo
Solicitud
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}
Respuesta
HTTP code: 204 No Content
Actualizar las propiedades de la hoja de cálculo
Solicitud
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 }
Respuesta
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"
}
Operaciones de gráficos
Enumerar los gráficos que forman parte de la hoja de cálculo.
Solicitud
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}
Respuesta
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
}
]
}
** Nota: El identificador de gráfico contiene { y } los caracteres (ejemplo: {00000000-0008-0000-0100-000003000000}), que deben codificarse como dirección URL para que la API funcione. Ejemplo: Para obtener un objeto de gráfico, la dirección URL codifica el identificador en la ruta de acceso como /charts/%7B00000000-0008-0000-0100-000003000000%7D.
Obtener imagen de gráfico
Solicitud
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}
Respuesta
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}"
}
Agregar un gráfico
Solicitud
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" }
Respuesta
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
}
Actualizar un 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 }
Respuesta
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
}
Actualizar los datos de origen del gráfico
Solicitud
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" }
Respuesta
HTTP code: 204 No Content
Operaciones de tabla
Obtener una lista de tablas
Solicitud
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}
Respuesta
HTTP code: 200 OK
content-type: application/json;odata.metadata
Crear tabla
Solicitud
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" }
Respuesta
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"
}
Actualizar tabla
Solicitud
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" }
Respuesta
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"
}
Obtener una lista de las filas de la tabla
Solicitud
GET https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables('4')/rows
authorization: Bearer {access-token}
workbook-session-id: {session-id}
Respuesta
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
]
]
}
]
}
Obtener una lista de las columnas de la tabla
Solicitud
GET https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables('4')/columns
authorization: Bearer {access-token}
workbook-session-id: {session-id}
Respuesta
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
]
]
}
]
}
Agregar una fila a la tabla
Solicitud
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 }
Respuesta
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
]
]
}
Agregar una columna a la tabla
Solicitud
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 }
Respuesta
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"
]
]
}
Eliminar fila de la tabla
Solicitud
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}
Respuesta
HTTP code: 204 No Content
Eliminar columna de la tabla
Solicitud
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}
Respuesta
HTTP code: 204 No Content
Convertir tabla a intervalo
Solicitud
POST https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables('1')/convertToRange
authorization: Bearer {access-token}
workbook-session-id: {session-id}
Respuesta
HTTP code: 200 OK
content-type: application/json;odata.metadata
Ordenar tabla
Solicitud
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
}
]
}
Respuesta
HTTP code: 204 No Content
Filtro de tabla
Solicitud
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"
}
}
Respuesta
HTTP code: 204 No Content
Borrar filtro
Solicitud
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}
Respuesta
HTTP code: 204 No Content
Operaciones de intervalo
Obtener intervalo
Solicitud
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}
Respuesta
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"
]
]
}
Actualizar 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"
]
]
}
Ordenar intervalo
Solicitud
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
}
]
}
Respuesta
HTTP code: 204 No Content
Elementos con nombre
Solicitud
GET https://graph.microsoft.com/v1.0/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/names
authorization: Bearer {access-token}
workbook-session-id: {session-id}
Respuesta
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
}
]
}
Trabajar con valores NULL
entrada NULL en una matriz bidimensional
La entrada null dentro de una matriz bidimensional (para valores, formato numérico, fórmulas) se omite en los recursos Range y Table. No se realiza ninguna actualización en el destino previsto (celda) cuando null la entrada se envía en valores o en formato de número o cuadrícula de fórmulas de valores.
Por ejemplo, para actualizar solamente partes específicas del intervalo, como el formato numérico de una celda, y conservar el formato numérico existente en otras partes del intervalo, establezca el formato numérico donde sea necesario y envíe null para las demás celdas.
En la siguiente solicitud de establecimiento, solo se establecen algunas partes del formato numérico de intervalo, mientras se conserva el formato numérico existente en la parte restante (pasando valores NULL).
{
"values" : [["Eurasia", "29.96", "0.25", "15-Feb" ]],
"numberFormat" : [[null, null, null, "m/d/yyyy;@"]]
}
entrada NULL para una propiedad
null no es una entrada única válida para toda la propiedad. Por ejemplo, lo siguiente no es válido porque los valores completos no se pueden establecer en null ni omitirse.
{
"values": null
}
Esto no es válido, ya que null no es un valor de color válido.
{
"color" : null
}
Respuesta NULL
La representación de propiedades de formato con valores no uniformes produce la devolución de un valor NULL en la respuesta.
Por ejemplo, un intervalo puede consistir en una o más celdas. En los casos en los que las celdas individuales contenidas en el rango especificado no tienen valores de formato uniformes, la representación del nivel de rango no está definida.
{
"size: : null,
"color" : null
}
También se devolverá un valor nulo en la respuesta en los siguientes casos:
- Si se produce un error al intentar obtener una propiedad específica de un objeto y esta propiedad se puede establecer como null, esta puede devolver un valor nulo en la respuesta.
- Para un objeto de rango, cuando se obtiene un rango para toda la fila o columna, algunas propiedades pueden devolver null como respuesta. Si el tamaño del rango supera la limitación superior (celdas de 5 M), algunas propiedades devuelven null como valor.
Entrada y salida en blanco
Los valores en blanco en las solicitudes de actualización se tratan como una instrucción para borrar o restablecer la propiedad correspondiente. Un valor en blanco se representa mediante dos comillas dobles sin espacio en medio: ""
Ejemplos:
En el caso de
values, el valor del rango se borra. Esto equivale a borrar el contenido de la aplicación.En el caso de
numberFormat, el formato numérico se establece enGeneral.En cuanto a
formulayformulaLocale, los valores de la fórmula se borran.
En las operaciones de lectura, lo que cabe esperar es recibir valores en blanco si el contenido de las celdas está en blanco. Si la celda no contiene datos ni valores, la API devuelve un valor en blanco. Un valor en blanco se representa mediante dos comillas dobles sin espacio en medio: ""
{
"values" : [["", "some", "data", "in", "other", "cells", ""]]
}
{
"formula" : [["", "", "=Rand()"]]
}
Intervalo sin delimitar
Lectura
Una dirección de intervalo sin delimitar solo contiene identificadores de columna o fila e identificadores de fila o columna no especificadas (respectivamente), tales como:
C:C,A:F,A:XFD(contiene filas no especificadas)2:2,1:4,1:1048546(contiene columnas no especificadas)
Cuando la API realiza una solicitud para recuperar un intervalo sin delimitar (getRange('C:C')), la respuesta devuelta contiene null para las propiedades de nivel de celda, como values, text, numberFormat o formula. Otras propiedades de intervalo como address o cellCount reflejarán el intervalo sin delimitar.
Write
El establecimiento de propiedades de nivel de celda (como valores, formato numérico, etc.) en el intervalo sin delimitar no está permitido, ya que la solicitud de entrada podría ser demasiado grande para controlarla.
Por ejemplo, lo siguiente no es una solicitud de actualización válida porque el intervalo solicitado no está enlazado.
PATCH /me/drive/root/workbook/worksheets/{id}/range(address="A:B")
{
"values" : "Due Date"
}
Cuando se intenta realizar una operación de actualización en un intervalo de este tipo, la API devuelve un error.
Intervalo grande
Un intervalo grande es aquel cuyo tamaño es demasiado grande para una sola llamada API. Numerosos factores contenidos en el intervalo, como el número de celdas, los valores, el formato numérico y las fórmulas, pueden hacer que la respuesta sea tan grande que resulte inadecuada para la interacción con la API. La API hace lo que puede para devolver o escribir en los datos solicitados. Sin embargo, el gran tamaño puede generar una condición de error de la API debido al elevado uso de recursos.
Para evitarlo, recomendamos la lectura o la escritura del intervalo grande en varios tamaños de intervalo pequeños.
Copia de entrada única
Para poder actualizar un intervalo con los mismos valores o formato numérico o aplicar la misma fórmula en un intervalo, se usa la siguiente convención en la API establecida. En Excel, este comportamiento es similar a la entrada de valores o fórmulas en un intervalo en el modo CTRL+ENTRAR.
La API busca un valor de celda única y, si la dimensión de rango de destino no coincide con la dimensión del rango de entrada, aplica la actualización a todo el rango del modelo CTRL+Entrar con el valor o la fórmula proporcionados en la solicitud.
Ejemplos
La siguiente solicitud actualiza el intervalo seleccionado con el texto "Sample text". El rango tiene 200 celdas, mientras que la entrada proporcionada solo tiene un valor de celda.
PATCH /me/drive/root/workbook/worksheets/{id}/range(address="A1:B100")
{
"values" : "Sample text"
}
Funciones de libro
Puede acceder a las funciones del libro a través de una colección de funciones incluidas en el recurso /Functions.
Solicitud
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
}
Respuesta
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
}
Información de error
Los errores se devuelven con un código de error HTTP y un objeto de error. Los errores code y message explican el motivo del error.
A continuación se muestra un ejemplo.
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"
}
}
}
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de