Si tienes apps existentes basadas en la API de Hojas de cálculo de Google v3, puedes migrar a la API de Hojas de cálculo de Google v4. La versión 4 se basa en JSON, tiene una interfaz más fácil de usar y agrega una cantidad sustancial de funciones que no es posible usar en la versión 3.
En esta página, se proporciona una asignación entre los comandos anteriores de la API de Hojas de cálculo v3 y sus operaciones equivalentes en la API de Hojas de cálculo v4. La asignación se enfoca principalmente en la colección spreadsheets.values, que proporciona la funcionalidad directa de lectura y escritura de celdas. La colección hojas de cálculo se encarga de otros aspectos, como agregar hojas o actualizar sus propiedades. Ten en cuenta que las estructuras JSON de la API de la versión 4 no son retrocompatibles con las estructuras XML que se usan en la versión 3.
Para obtener más información sobre los recursos disponibles en la API de Hojas de cálculo v4, consulta la referencia de la API.
Notación y términos
La API de la versión 3 se refiere a las hojas dentro de una hoja de cálculo en particular como "hojas de trabajo". Es sinónimo del término "hojas" que usa la API de v4.
A menudo, las APIs requieren que especifiques un ID de hoja de cálculo de la hoja de cálculo con la que estás trabajando. También suelen requerir el ID de la hoja que se manipula. Estos valores aparecen como parte de la URL del extremo de la API, como parámetros de consulta o como parte del cuerpo de una solicitud. En esta página, los marcadores de posición spreadsheetId y sheetId hacen referencia a los IDs de la hoja de cálculo y de la hoja, respectivamente. Cuando uses los métodos descritos en esta página, reemplaza los IDs reales en estas ubicaciones.
La API de la versión 3 también asigna un ID a las filas recuperadas con su feed de lista, que se representa en esta página con el marcador de posición rowId.
Autoriza solicitudes
Cuando se ejecuta la app, les solicita a los usuarios que otorguen ciertos permisos. Los permisos que se solicitan se determinan según los alcances que especifiques en la app.
API de v3
La API de Hojas de cálculo v3 opera con un solo permiso de autorización:
https://spreadsheets.google.com/feeds
que es un alias para
https://www.googleapis.com/auth/spreadsheets
Se puede usar cualquiera de los formatos de alcance.
API de v4
La API de Hojas de cálculo v4 usa uno o más de los siguientes conjuntos de permisos:
https://www.googleapis.com/auth/spreadsheets.readonly https://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/drive.readonly https://www.googleapis.com/auth/drive
Usa alcances de solo lectura si tu aplicación no necesita realizar modificaciones en las hojas o propiedades de las hojas de un usuario. Usa los permisos de las hojas de cálculo en lugar de los de Drive si la aplicación no necesita acceso general a Drive.
Visibilidad
En versiones anteriores de la API, el término visibilidad se usa para hacer referencia a la disponibilidad de una hoja de cálculo determinada.
API de v3
La versión 3 de la API de Hojas de cálculo expresa la visibilidad directamente en sus extremos. Una hoja de cálculo public se "publicó en la Web" y, por lo tanto, la API puede acceder a ella sin autorización, mientras que una hoja de cálculo private requiere autenticación. La visibilidad se especifica en el extremo después del ID de la hoja de cálculo:
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
API de v4
En la nueva API de Hojas de cálculo v4, no hay una declaración explícita de visibilidad. Las llamadas a la API se realizan con IDs de hoja de cálculo. Si la aplicación no tiene permiso para acceder a la hoja de cálculo especificada, se muestra un error. De lo contrario, la llamada continúa.
Proyección
La API de Hojas de cálculo v3 usa el término proyección para referirse al conjunto de datos que muestra una llamada a la API determinada, ya sea todo o un subconjunto fijo definido dentro de la API. La versión 4 de la API de Hojas de cálculo no usa la proyección, sino que te permite tener más control sobre los datos que se muestran.
API de v3
Solo hay dos parámetros de configuración de proyección posibles en la API de Hojas de cálculo v3. La proyección full muestra toda la información disponible, mientras que basic muestra un subconjunto de datos más pequeño y fijo (para los feeds de hojas de cálculo, listas y celdas).
Al igual que la visibilidad, la proyección se debe especificar en el extremo de la API (después de la configuración de visibilidad):
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic
El subconjunto más pequeño de datos que proporciona la proyección basic es valioso para hacer que el código sea más eficiente, pero no se puede personalizar.
API de v4
Si bien la versión 4 de la API de Hojas de cálculo puede mostrar un conjunto de datos completo, no define subconjuntos fijos análogos a la configuración de visibilidad basic de la versión 3 de la API de Hojas de cálculo.
Los métodos de la colección hoja de cálculo limitan la cantidad de datos que muestran mediante el uso de un parámetro de consulta fields.
Por ejemplo, la siguiente consulta solo muestra los títulos de todas las hojas de una hoja de cálculo en particular:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title
Crear una hoja de cálculo
API de v3
La versión 3 de la API de Hojas de cálculo no proporciona un medio para crear hojas de cálculo nuevas. En su lugar, se puede usar el método Files.create de la API de Drive para crear archivos de hoja de cálculo nuevos. Esto requiere que la aplicación declare el alcance de https://www.googleapis.com/auth/drive.
API de v4
El método Files.create de la API de Drive también se puede usar con la versión 4 de la API de Hojas de cálculo, pero requiere que la aplicación proporcione el permiso https://www.googleapis.com/auth/drive.
Como alternativa equivalente, la API de Hojas de cálculo v4 proporciona un método spreadsheets.create, que también puede agregar hojas de manera opcional, establecer las propiedades de la hoja de cálculo y agregar rangos con nombre. Por ejemplo, el siguiente comando crea una hoja de cálculo nueva y le asigna el nombre “NewTitle”:
POST https://sheets.googleapis.com/v4/spreadsheets
{
"properties": {"title": "NewTitle"}
}Lista de hojas de cálculo para el usuario autenticado
API de v3
El feed de la API de Hojas de cálculo v3 permite que una aplicación recupere una lista de todas las hojas de cálculo a las que puede acceder el usuario autenticado. El extremo del feed de hoja de cálculo es el siguiente:
GET https://spreadsheets.google.com/feeds/spreadsheets/private/full
API de v4
La versión 4 de la API de Hojas de cálculo no proporciona esta operación específica. Te recomendamos que migres tu app para usar el permiso drive.file en combinación con el selector de Google para la selección de hojas de cálculo.
En los casos en que se requiera enumerar las hojas de cálculo, se puede replicar a través del método Files.list de la API de Drive con una consulta mimeType:
GET https://www.googleapis.com/drive/v3/files
?q=mimeType='application/vnd.google-apps.spreadsheet'El uso del método files.list de la API de Drive para mostrar una lista de todas las hojas de cálculo de un usuario requiere un permiso restringido.
Cómo recuperar metadatos de una hoja
La versión 3 de la API de Hojas de cálculo proporciona un feed para acceder a los metadatos de la hoja que se encuentran en una hoja de cálculo determinada (se accede a los datos de las filas y las celdas a través de un feed independiente). Los metadatos incluyen información como los títulos de las hojas y la información de tamaño.
El método spreadsheets.get de la API de Hojas de cálculo v4 proporciona acceso a esta información y mucho más.
API de v3
Se puede acceder al feed de hoja de cálculo desde este extremo de la API (con un encabezado de autorización apropiado):
GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
La respuesta a esta solicitud tiene una estructura similar a esta, con los datos de cada hoja contenidos en un <entry> independiente:
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
xmlns:gs="http://schemas.google.com/spreadsheets/2006"
xmlns:gd="http://schemas.google.com/g/2005"
gd:etag='W/"D0cERnk-eip7ImA9WBBXGEg."'>
<id>https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<title type="text">Groceries R Us</title>
<link rel="alternate" type="text/html"
href="https://spreadsheets.google.com/ccc?key=spreadsheetId"/>
<link rel="http://schemas.google.com/g/2005#feed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<author>
<name>Fitzwilliam Darcy</name>
<email>fitz@example.com</email>
</author>
<openSearch:totalResults>1</openSearch:totalResults>
<openSearch:startIndex>1</openSearch:startIndex>
<openSearch:itemsPerPage>1</openSearch:itemsPerPage>
<entry gd:etag='"YDwqeyI."'>
<id>https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<title type="text">Sheet1</title>
<content type="text">Sheet1</content>
<link rel="http://schemas.google.com/spreadsheets/2006#listfeed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full"/>
<link rel="http://schemas.google.com/spreadsheets/2006#cellsfeed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version"/>
<gs:rowCount>100</gs:rowCount>
<gs:colCount>20</gs:colCount>
</entry>
</feed>
API de v4
El método spreadsheets.get se puede usar para adquirir propiedades de hoja y otros metadatos, mucho más de lo que está disponible con la API de Hojas de cálculo v3. Si solo
deseas leer las propiedades de la hoja, establece el parámetro de consulta
includeGridData en false para evitar la inclusión de los datos de la celda de la hoja de cálculo:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?includeGridData=false
La respuesta Spreadsheet contiene un array de objetos Sheet. Los títulos de las hojas y la información de tamaño se pueden encontrar específicamente en el elemento SheetProperties de estos objetos. Por ejemplo:
{
"spreadsheetId": spreadsheetId,
"sheets": [
{"properties": {
"sheetId": sheetId,
"title": "Sheet1",
"index": 0,
"gridProperties": {
"rowCount": 100,
"columnCount": 20,
"frozenRowCount": 1,
"frozenColumnCount": 0,
"hideGridlines": false
},
...
},
...
},
...
],
...
}Cómo agregar una hoja a una hoja de cálculo
Ambas APIs te permiten agregar hojas nuevas a una hoja de cálculo existente.
API de v3
La API de Hojas de cálculo v3 puede agregar hojas de cálculo nuevas a una hoja de cálculo si realiza la siguiente solicitud POST (autenticada). Puedes especificar el tamaño de la hoja nueva:
POST https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:gs="http://schemas.google.com/spreadsheets/2006">
<title>Expenses</title>
<gs:rowCount>50</gs:rowCount>
<gs:colCount>10</gs:colCount>
</entry>
API de v4
Para agregar hojas nuevas, realiza una solicitud AddSheet en el método spreadsheets.batchUpdate. Como parte del cuerpo de la solicitud, puedes especificar las propiedades de la hoja nueva. Todas las propiedades son opcionales. Es un error proporcionar un título que se usa para una hoja existente.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [{
"addSheet": {
"properties": {
"title": "Expenses",
"sheetType": "GRID",
"gridProperties": {
"rowCount": 50,
"columnCount": 10
}
}
}
}],
}Cómo cambiar el título y el tamaño de una hoja
La API de Hojas de cálculo v3 te permite actualizar los títulos y el tamaño de las hojas. La API de Hojas de cálculo v4 también permite esto, pero también se puede usar para actualizar otras propiedades de la hoja. Ten en cuenta que reducir el tamaño de una hoja puede hacer que los datos de las celdas recortadas se borren sin advertencia.
API de v3
Para cambiar el título o el tamaño de una hoja de cálculo, primero recupera el feed de la hoja de cálculo y busca la entrada de la hoja de cálculo deseada, que contiene una URL de edit.
Actualiza los metadatos de la hoja de cálculo y envíalos como el cuerpo de una solicitud PUT a la URL de edición. Por ejemplo:
PUT https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
<entry>
<id>
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId
</id>
<updated>2007-07-30T18:51:30.666Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#worksheet"/>
<title type="text">Expenses</title>
<content type="text">Expenses</content>
<link rel="http://schemas.google.com/spreadsheets/2006#listfeed"
type="application/atom+xml" href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full"/>
<link rel="http://schemas.google.com/spreadsheets/2006#cellsfeed"
type="application/atom+xml" href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version"/>
<gs:rowCount>45</gs:rowCount>
<gs:colCount>15</gs:colCount>
</entry>
API de v4
Para actualizar el tamaño, el título y otras propiedades de la hoja, realiza una solicitud updateSheetProperties en el método spreadsheets.batchUpdate. El cuerpo de la solicitud POST debe contener las propiedades que se cambiarán, y el parámetro fields debe enumerarlas de forma explícita (si deseas actualizar todas las propiedades, usa fields:"*" como abreviatura para enumerarlas todas). Por ejemplo, lo siguiente especifica que las propiedades de tamaño y título de la hoja deben actualizarse para la hoja con el ID determinado:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"updateSheetProperties": {
"properties": {
"sheetId": sheetId,
"title": "Expenses",
"gridProperties": {
"rowCount": 45,
"columnCount": 15,
}
},
"fields": "title,gridProperties(rowCount,columnCount)"
}
}
],
}Para recuperar el sheetId de una hoja, usa el método spreadsheets.get de la hoja de cálculo.
Cómo borrar una hoja
Cualquiera de las APIs puede quitar hojas de una hoja de cálculo determinada.
API de v3
Para borrar una hoja de cálculo, primero recupera el feed de hojas de cálculo y, luego, envía una solicitud DELETE en la URL edit de la entrada de hoja de cálculo de destino.
DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
API de v4
Para borrar una hoja, realiza una solicitud DeleteSheet en el método spreadsheets.batchUpdate. El cuerpo de la solicitud POST solo debe contener el sheetId para que se borre la hoja. Por ejemplo:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteSheet": {
"sheetId": sheetId
}
}
],
}Para recuperar el sheetId de una hoja individual, usa el método spreadsheets.get de la hoja de cálculo.
Cómo recuperar datos de filas
El feed de filas de lista es uno de los dos métodos que proporciona la API de Hojas de cálculo v3 para acceder a los datos dentro de las celdas de una hoja de cálculo (el otro es el feed de celdas). El feed de filas está diseñado para admitir operaciones comunes de hojas de cálculo (lectura fila por fila, adición de filas, ordenamiento), pero hace ciertas suposiciones que lo hacen inadecuado para algunas tareas. Específicamente, el feed de lista supone que las filas en blanco son terminaciones del feed y que los encabezados obligatorios están presentes en la primera fila de una hoja.
En cambio, la versión 4 de la API de Hojas de cálculo no usa métodos de acceso específicos de la fila. En su lugar, se accede a los datos de las celdas de la hoja haciendo referencia a los rangos específicos necesarios con la notación A1. Los rangos pueden ser bloques de celdas, filas, columnas o hojas completas. La API también puede acceder a conjuntos de celdas disjuntos.
API de v3
Para determinar la URL de un feed basado en una lista para una hoja de cálculo determinada, recupera el feed de hoja de cálculo y busca la URL del feed de lista en la entrada de hoja de cálculo que te interese.
Para recuperar un feed basado en una lista, envía una solicitud GET a la URL del feed de lista con un encabezado de autorización adecuado. Por ejemplo:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
La respuesta a esta solicitud contiene, entre otras cosas, entradas correspondientes a filas específicas. Se hace referencia a las celdas individuales con los nombres proporcionados en la fila del encabezado de la hoja (obligatoria). Por ejemplo, esta es una entrada de una sola fila:
<entry gd:etag='"S0wCTlpIIip7ImA0X0QI"'>
<id>rowId</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#list"/>
<title type="text">Bingley</title>
<content type="text">Hours: 10, Items: 2, IPM: 0.0033</content>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version"/>
<gsx:name>Bingley</gsx:name>
<gsx:hours>10</gsx:hours>
<gsx:items>2</gsx:items>
<gsx:ipm>0.0033</gsx:ipm>
</entry>
De forma predeterminada, las filas que se muestran en el feed de lista se muestran en orden. La versión 3 de la API de Hojas de cálculo proporciona parámetros de consulta para cambiar ese orden.
Orden inverso:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full?reverse=true
Ordenar por una columna específica:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?orderby=column:lastnameLa API de Hojas de cálculo v3 también permite filtrar filas específicas a través de una consulta estructurada (a la que se hace referencia mediante encabezados de columna):
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?sq=age>25%20and%20height<175API de v4
Con la versión 4 de la API de Hojas de cálculo, las filas se pueden recuperar por rango con los métodos spreadsheets.values.get o spreadsheets.values.batchGet. Por ejemplo, la siguiente fórmula muestra todas las filas de "Hoja1":
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1
La respuesta a esta solicitud tiene una estructura similar a la siguiente:
{
"range": "Sheet1",
"majorDimension": "ROWS",
"values": [["Name", "Hours", "Items", "IPM"],
["Bingley", "10", "2", "0.0033"],
["Darcy", "14", "6", "0.0071"]]
}Las celdas vacías finales no se incluyen en la respuesta cuando se recuperan filas, columnas o hojas completas.
La API de Hojas de cálculo v4 no tiene equivalentes para los parámetros de consulta de orden de filas que proporciona la API de Hojas de cálculo v3. El orden inverso es trivial. Simplemente, procesa el array values que se muestra en orden inverso. El orden por columna no es compatible con las operaciones de lectura, pero es posible ordenar los datos de la hoja (con una solicitud SortRange) y, luego, leerlos.
Actualmente, la API de Hojas de cálculo v4 no tiene un equivalente directo para las consultas estructuradas de la API de Hojas de cálculo v3. Sin embargo, puedes recuperar los datos relevantes y ordenarlos según sea necesario en tu aplicación.
Agrega una fila de datos nueva
Puedes agregar una fila nueva de datos a una hoja con cualquiera de las APIs.
API de v3
Para determinar la URL de un feed basado en una lista para una hoja de cálculo determinada, recupera el feed de hoja de cálculo y busca la URL de la publicación en la entrada de la hoja de cálculo que te interesa.
Para agregar una fila de datos, envía una solicitud POST a la URL de publicación con un encabezado de autorización adecuado. Por ejemplo:
POST https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
El cuerpo de la solicitud POST debe contener una entrada para los datos de fila que se agregarán, con celdas individuales a las que se hace referencia mediante encabezados de columna:
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:gsx="http://schemas.google.com/spreadsheets/2006/extended">
<gsx:hours>2</gsx:hours>
<gsx:ipm>0.5</gsx:ipm>
<gsx:items>60</gsx:items>
<gsx:name>Elizabeth</gsx:name>
</entry>
Las filas nuevas se agregan al final de la hoja especificada.
API de v4
Con la versión 4 de la API de Hojas de cálculo, puedes agregar filas con el método spreadsheets.values.append. En el siguiente ejemplo, se escribe una fila nueva de datos debajo de la última tabla en "Hoja1" de una hoja de cálculo.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}Además, la API de Hojas de cálculo v4 también te permite adjuntar celdas con propiedades y formatos específicos mediante las solicitudes AppendCells en una spreadsheets.batchUpdate.
Cómo editar una fila con datos nuevos
Ambas APIs permiten que los datos de las filas se actualicen con valores nuevos.
API de v3
Para editar una fila de datos, examina el feed de lista para encontrar la entrada de la fila que deseas actualizar. Actualiza el contenido de esa entrada según sea necesario. Asegúrate de que el valor de ID de la entrada que uses coincida exactamente con el ID de la entrada existente.
Una vez que se haya actualizado la entrada, envía una solicitud PUT con la entrada como cuerpo de la solicitud a la URL edit proporcionada en esa entrada de fila con un encabezado de autorización adecuado. Por ejemplo:
PUT https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
<entry gd:etag='"S0wCTlpIIip7ImA0X0QI"'>
<id>rowId</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#list"/>
<title type="text">Bingley</title>
<content type="text">Hours: 10, Items: 2, IPM: 0.0033</content>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version"/>
<gsx:name>Bingley</gsx:name>
<gsx:hours>20</gsx:hours>
<gsx:items>4</gsx:items>
<gsx:ipm>0.0033</gsx:ipm>
</entry>
API de v4
Con la versión 4 de la API de Hojas de cálculo, puedes editar una fila con la notación A1 de la fila que deseas editar y emitir una solicitud spreadsheets.values.update para reemplazar esa fila. El rango especificado solo debe hacer referencia a la primera celda de la fila. La API infiere las celdas que se actualizarán según los valores proporcionados con la solicitud. Si, en su lugar, especificas un rango de varias celdas, los valores que proporciones deben ajustarse a ese rango. De lo contrario, la API mostrará un error.
En el siguiente ejemplo de solicitud y cuerpo de solicitud, se agregan datos a la cuarta fila de "Hoja1":
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A4
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}También puedes actualizar los datos de las filas desde el método spreadsheet.values.batchUpdate. Es más eficiente usar este método si realizas varias actualizaciones de filas o celdas.
Además, la API de Hojas de cálculo v4 también te permite editar las propiedades de las celdas y su formato con las solicitudes UpdateCells o RepeatCell en una spreadsheets.batchUpdate.
Cómo borrar una fila
Ambas APIs admiten la eliminación de filas. Una fila borrada se quita de la hoja de cálculo, y las filas debajo de ella se suben una fila.
API de v3
Para borrar una fila, primero recupera la fila que quieres borrar del feed de lista y, luego, envía una solicitud DELETE a la URL edit proporcionada en la entrada de la fila.
Esta es la misma URL que se usa para actualizar la fila.
DELETE https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
Si quieres asegurarte de no borrar una fila que otro cliente cambió desde que la recuperaste, incluye un encabezado HTTP If-Match que contenga el valor de ETag de la fila original. Para determinar el valor de la etiqueta E de la fila original, examina el atributo gd:etag del elemento de entrada.
Si quieres borrar la fila independientemente de si otra persona la actualizó desde que la recuperaste, usa If-Match: * y no incluyas la ETag. (en este caso, no necesitas recuperar la fila antes de borrarla).
API de v4
La eliminación de filas con la API de Hojas de cálculo v4 se controla mediante una llamada al método spreadsheet.batchUpdate con una solicitud DeleteDimension. Esta solicitud también se puede usar para quitar columnas y desarrolladores, y elegir quitar solo parte de una fila o columna. Por ejemplo, la siguiente secuencia quita la 6ª fila de una hoja con el ID determinado (los índices de fila se basan en cero, con startIndex inclusivo y endIndex exclusivo):
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteDimension": {
"range": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 5,
"endIndex": 6
}
}
}
],
}El sheetId de una hoja se puede recuperar con el método spreadsheet.get.
Cómo recuperar datos de celdas
La API de Hojas de cálculo v3 proporciona un feed de celdas para el acceso básico a todos los datos almacenados en una hoja de cálculo. Para el acceso de lectura, el feed de celdas puede proporcionar todo el contenido de la hoja o un rango de las celdas de la hoja definido por un conjunto de parámetros de consulta, pero solo como un solo bloque. Los rangos disjuntos se deben recuperar por separado con solicitudes GET adicionales.
La versión 4 de la API de Hojas de cálculo puede recuperar cualquier conjunto de datos de celdas de una hoja (incluidos varios rangos disjuntos). La versión 3 de la API de Hojas de cálculo solo puede mostrar el contenido de las celdas como valores de entrada (como los ingresaría un usuario en un teclado) o los resultados de una fórmula (si es numérica). La versión 4 de la API de Hojas de cálculo otorga acceso completo a los valores, las fórmulas, el formato, los hipervínculos, la validación de datos y otras propiedades.
API de v3
Para determinar la URL de un feed basado en celdas para una hoja de cálculo determinada, examina el feed de la hoja de cálculo y busca la URL del feed de celdas en la entrada de la hoja de cálculo que te interesa.
Para recuperar un feed basado en celdas, envía una solicitud GET a la URL del feed de celdas con un encabezado de autorización adecuado. Por ejemplo:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
Para hacer referencia a las celdas, se usan números de fila y columna. Para recuperar un solo rango específico, puedes usar los parámetros de consulta max-row, min-row, max-col y min-col. Por ejemplo, la siguiente fórmula recupera todas las celdas de la columna 4 (D), a partir de la fila 2:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
?min-row=2&min-col=4&max-col=4La API de Hojas de cálculo v3 muestra el inputValue de las celdas recuperadas, el valor que un usuario escribiría en la interfaz de usuario de Hojas de cálculo de Google para manipular la celda. El inputValue puede ser un valor literal o una fórmula. A veces, la API también muestra un numericValue, por ejemplo, cuando una fórmula genera un número. Por ejemplo, una respuesta puede incluir entradas de celda similares en estructura a las siguientes:
<entry gd:etag='"ImB5CBYSRCp7"'>
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4</id>
<updated>2006-11-17T18:27:32.543Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#cell"/>
<title type="text">D4</title>
<content type="text">5</content>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4/srevc"/>
<gs:cell row="4" col="4" inputValue="=FLOOR(C4/(B4*60),.0001)"
numericValue="5.0">5</gs:cell>
</entry>
API de v4
Para recuperar datos de celdas, llama a un método spreadsheets.values.get o spreadsheets.values.batchGet para el rango o los rangos de interés, respectivamente. Por ejemplo, lo siguiente muestra las celdas de la columna D de "Hoja2", comenzando con la fila 2, en orden de columna y muestra las fórmulas tal como se ingresaron (se omiten las celdas vacías finales):
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet2!D2:D?majorDimension=COLUMNS&valueRenderOption=FORMULA
La respuesta a esta solicitud tiene una estructura similar a la siguiente:
{
"spreadsheetId": spreadsheetId,
"valueRanges": [
{"range": "Sheet2!D2:D",
"majorDimension": "COLUMNS",
"values": [["Widget", 234, "=FLOOR(C4/(B4*60),.0001)", "=D4\*1000"]]
}]
}Es más eficiente usar spreadsheet.values.batchGet si deseas recuperar varios rangos de datos de celdas. Si deseas acceder a las propiedades de las celdas, como el formato, se requiere el método spreadsheet.get.
Cómo editar una celda
La API de Hojas de cálculo v3 te permite editar el contenido de las celdas emitiendo un comando PUT al feed de celdas con la entrada de celda modificada como cuerpo de la solicitud.
En cambio, la API de Hojas de cálculo v4 proporciona los métodos spreadsheets.values.update y spreadsheets.values.batchUpdate para cambiar el contenido de las celdas.
API de v3
Para editar el contenido de una sola celda, primero busca la entrada de la celda en el feed de celdas.
La entrada contiene una URL de edición. Actualiza la entrada para que refleje el contenido que deseas que tenga la celda y, luego, emite una solicitud PUT a la URL de edición con la entrada de celda actualizada como cuerpo de la solicitud. Por ejemplo, lo siguiente actualiza la celda D2 (R2C4) para que contenga una fórmula SUM:
PUT https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full//R2C4/srevc<entry xmlns="http://www.w3.org/2005/Atom" xmlns:gs="http://schemas.google.com/spreadsheets/2006"> <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4</id> <link rel="edit" type="application/atom+xml" href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4"/> <gs:cell row="2" col="4" inputValue="=SUM(A1:B6)"/> </entry>
API de v4
La edición de una sola celda en la API de Hojas de cálculo v4 se puede realizar con el método spreadsheets.values.update. Este método requiere un parámetro de consulta ValueInputOption, que especifica si los datos de entrada se tratan como si se ingresaran en la IU de Hojas de cálculo (USER_ENTERED) o si se dejan sin analizar y se toman como están (RAW). Por ejemplo, la siguiente fórmula actualiza la celda D2 con una fórmula:
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/D2?valueInputOption=USER_ENTERED
{"values": [["=SUM(A1:B6)"]]}Si realizas varias ediciones de celdas, usa el método spreadsheets.values.batchUpdate para enviarlas en una sola solicitud.
Cómo editar varias celdas mediante una solicitud por lotes
Ambas APIs proporcionan los medios para realizar cambios en el contenido de varias celdas con una sola solicitud (por lotes). No es necesario que las celdas a las que hace referencia una solicitud por lotes se encuentren en un rango contiguo.
En el caso de que una o más de las ediciones de celdas del lote fallen, la API de Hojas de cálculo v3 permite que otras se realicen correctamente. Sin embargo, la API de Hojas de cálculo v4 muestra un error si falla alguna de las actualizaciones por lotes y no aplica ninguna de ellas en ese caso.
API de v3
Para editar varias celdas, primero recupera un feed de celdas para la hoja de cálculo. La entrada contiene una URL de lote. Envía una solicitud POST a esta URL, junto con un cuerpo de solicitud que describa las celdas que deseas actualizar y el contenido de la celda nueva. La solicitud y el cuerpo de la solicitud de POST tienen una estructura similar a la siguiente:
POST https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/batch
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:batch="http://schemas.google.com/gdata/batch"
xmlns:gs="http://schemas.google.com/spreadsheets/2006">
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full</id>
<entry>
<batch:id>request1</batch:id>
<batch:operation type="update"/>
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4</id>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4/version"/>
<gs:cell row="2" col="4" inputValue="newData"/>
</entry>
...
<entry>
<batch:id>request2</batch:id>
<batch:operation type="update"/>
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C5</id>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C5/version"/>
<gs:cell row="5" col="2" inputValue="moreInfo"/>
</entry>
</feed>
El campo batch:id debe identificar de forma inequívoca la solicitud dentro del lote.
El campo batch:operation debe ser update para las ediciones de celdas. gs:cell
identifica la celda por número de fila y columna, y proporciona los datos nuevos
para insertar allí. id contiene la URL completa de la celda que se actualizará.
link debe tener un atributo href que contenga la ruta de acceso completa al ID de la celda. Todos estos campos son obligatorios para cada entrada.
API de v4
La versión 4 de la API de Hojas de cálculo proporciona edición por lotes de valores de celdas a través del método spreadsheets.values.batchUpdate.
Para editar varias celdas, emite una solicitud POST con los cambios de datos especificados en el cuerpo de la solicitud. Por ejemplo:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values:batchUpdate
{
"valueInputOption": "USER_ENTERED"
"data": [
{"range": "D4",
"majorDimension": "ROWS",
"values": [["newData"]]
},
{"range": "B5",
"majorDimension": "ROWS",
"values": [["moreInfo"]]
}
]
}Si especificaste una sola celda como el rango, todos los valores proporcionados se escriben en la hoja comenzando con esa celda como la coordenada superior izquierda. En cambio, si especificas un rango de varias celdas, los valores que proporciones deben ajustarse exactamente a ese rango. De lo contrario, la API mostrará un error.