Si tienes aplicaciones basadas en la API de Hojas de cálculo de Google v3, puedes realizar la migración a la API de Hojas de cálculo de Google v4. La versión 4 está basada en JSON, tiene una interfaz más fácil de usar y agrega una cantidad significativa de funciones que no es posible en la versión 3.
En esta página, se proporciona una comparación entre los comandos antiguos de la API de Hojas de cálculo v3 y sus operaciones equivalentes en la API de Hojas de cálculo v4. En gran medida, la asignación se centra en la colección spreadsheets.values, que proporciona la funcionalidad de lectura y escritura de celdas directa. La colección spreadsheets se encarga de otros aspectos, como agregar hojas o actualizar sus propiedades. Ten en cuenta que las estructuras JSON de la API v4 no son compatibles con estructuras previas de XML usadas en la v3.
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
En la API v3, a las hojas dentro de una hoja de cálculo determinada se las denomina “hojas de trabajo”. Es sinónimo del término “hojas” en la API v4.
A menudo, las APIs requieren que especifiques un ID de hoja de cálculo correspondiente a la hoja de cálculo en la que estés trabajando. También requieren el ID de la hoja que se esté manipulando. 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, sustituye los IDs reales en estas ubicaciones.
La API de v3 también asigna un ID a las filas recuperadas con su feed de lista; en esta página, se representa con el marcador de posición rowId.
Autoriza solicitudes
Cuando tu app se ejecuta, solicita al usuario ciertos permisos. Los ámbitos que especificas en tu aplicación determinan los permisos que solicitará.
API de v3
La API de Hojas de cálculo v3 funciona con un solo ámbito de autorización:
https://spreadsheets.google.com/feeds
que es un alias de
https://www.googleapis.com/auth/spreadsheets
Se pueden usar ambos formatos del ámbito.
API de v4
La API de Hojas de cálculo v4 utiliza 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
Utiliza ámbitos de solo lectura si no es necesario que tu aplicación realice ediciones en las hojas o propiedades de las hojas de un usuario. Utiliza ámbitos de hoja de cálculo en lugar de ámbitos de Drive si la aplicación no requiere 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 API de Hojas de cálculo v3 muestra la visibilidad directamente en los extremos. Si una hoja de cálculo es public, se usó la opción "Publicar en la Web", por lo que la API puede acceder a ella sin autorización. En cambio, una hoja de cálculo private sí requiere autenticación. En el extremo, la visibilidad se especifica 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, la visibilidad no está explícitamente declarada. Las llamadas a la API se realizan con los IDs de la hoja de cálculo. Si la aplicación no tiene permiso para acceder a una hoja de cálculo determinada, se mostrará un error. De lo contrario, se continúa con la llamada.
Proyección
La API de Hojas de cálculo v3 emplea el término proyección para referirse al conjunto de datos que muestra una llamada a la API determinada (todos los datos o un subconjunto fijo definido por la API). La API de Hojas de cálculo v4 no utiliza proyección. En su lugar, te permite tener un mayor control sobre los datos que se muestran.
API de v3
En la API de Hojas de cálculo v3, solo hay dos parámetros de configuración de proyección posibles. 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 trabajo, listas y celdas).
Como 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 menor de datos que proporciona la proyección basic es valioso para que el código sea más eficaz, pero no se puede personalizar.
API de v4
Si bien la API de Hojas de cálculo v4 puede mostrar un conjunto completo de datos, no define subconjuntos fijos análogos a la configuración de visibilidad basic de la API de Hojas de cálculo v3.
Los métodos de la colección hoja de cálculo restringen la cantidad de datos que muestran a través del uso de un parámetro de consulta fields.
Por ejemplo, la siguiente consulta solo muestra los títulos de todas las hojas en una hoja de cálculo determinada:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title
Crear una hoja de cálculo
API de v3
La API de Hojas de cálculo v3 no proporciona ningún método para crear una nueva hoja de cálculo. En su lugar, se puede usar el método Files.create de la API de Drive para crear nuevos archivos de hoja de cálculo. Para ello, la aplicación debe declarar el ámbito 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 API de Hojas de cálculo v4, 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, establecer las propiedades de la hoja de cálculo y de la hoja, y agregar rangos con nombre de forma opcional. Por ejemplo, en el siguiente elemento, se crea una hoja de cálculo nueva y se le asigna el nombre “NewTitle”:
POST https://sheets.googleapis.com/v4/spreadsheets
{
"properties": {"title": "NewTitle"}
}Proporcionar una lista de las hojas de cálculo al usuario autenticado
API de v3
El feed de la API de Hojas de cálculo v3 permite que una aplicación obtenga una lista de todas las hojas de cálculo a las que puede acceder el usuario autenticado. El extremo del feed de la hoja de cálculo es el siguiente:
GET https://spreadsheets.google.com/feeds/spreadsheets/private/full
API de v4
La API de Hojas de cálculo v4 no ofrece esta operación en particular. 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 con el método Files.list de la API de Drive mediante 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 hojas
La API de Hojas de cálculo v3 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 celdas desde otro feed). Los metadatos incluyen información como los títulos y el tamaño de la hoja.
En la API de Hojas de cálculo v4, el método spreadsheets.get proporciona acceso a esta información y mucho más.
API de v3
Se puede tener acceso al feed de las hojas de trabajo desde el siguiente extremo de la API (con un encabezado de autorización adecuado):
GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
La respuesta a esta solicitud tiene una estructura similar a la siguiente, con los datos de cada hoja 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
Se puede usar el método spreadsheets.get para adquirir propiedades de la hoja y otros metadatos, mucho más que lo que está disponible en la API de Hojas de cálculo v3. Si solo necesitas leer las propiedades de la hoja, establece el parámetro de consulta includeGridData en false para evitar que se incluyan datos de las celdas 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 del 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 permiten agregar hojas nuevas a una hoja de cálculo existente.
API de v3
En la API de Hojas de cálculo v3, se puede usar la siguiente solicitud POST (autenticada) para agregar nuevas hojas de trabajo a una hoja de cálculo. 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
Puedes agregar nuevas hojas si realizas una solicitud AddSheet en el método spreadsheets.batchUpdate. En el cuerpo de la solicitud, puedes especificar las propiedades de la hoja nueva. Todas las propiedades son opcionales. No se puede proporcionar un título que ya se use en otra hoja.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [{
"addSheet": {
"properties": {
"title": "Expenses",
"sheetType": "GRID",
"gridProperties": {
"rowCount": 50,
"columnCount": 10
}
}
}
}],
}Cambia el título y el tamaño de una hoja
La API de Hojas de cálculo v3 te permite modificar el título y tamaño de una hoja. La API de Hojas de cálculo v4 también permite hacer lo mismo, pero también se puede usar para modificar otras propiedades de la hoja. Ten en cuenta que si reduces el tamaño de una hoja, es posible que se eliminen, sin aviso, los datos de las celdas recortadas.
API de v3
Para cambiar el título o el tamaño de una hoja de trabajo, primero obtén el
feed de hojas de trabajo y
busca la entrada de la hoja de trabajo en cuestión, que contiene una URL de edit.
Actualiza los metadatos de la hoja de trabajo y envíalos como 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, realiza una solicitud updateSheetProperties en el método spreadsheets.batchUpdate. El cuerpo de la solicitud POST debe contener las propiedades que se modificarán, y el parámetro fields debe enumerar esas propiedades de forma explícita (si quieres actualizar todas las propiedades, usa fields:"*" como abreviatura para enumerarlas todas). Por ejemplo, a continuación se especifica que deben actualizarse las propiedades de título y tamaño de 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
Ambas APIs pueden quitar hojas de una hoja de cálculo determinada.
API de v3
Para borrar una hoja de trabajo, primero obtén el
feed de hojas de trabajo y, luego,
envía una solicitud DELETE en la URL edit de la entrada de la hoja de trabajo objetivo.
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 de la hoja que se borrará. 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 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 hoja de cálculo (leer fila por fila, anexar filas, ordenar), pero realiza ciertas suposiciones que no le permiten ser adecuado para algunas tareas. En concreto, el feed de lista supone que las filas en blanco son finalizadores del feed y que los encabezados obligatorios se encuentran en la primera fila de una hoja.
En cambio, la API de Hojas de cálculo v4 no usa métodos de acceso que dependan de filas. En su lugar, para acceder a los datos correspondientes a la celda de una hoja, se hace referencia a los rangos específicos mediante la notación A1. Los rangos pueden ser bloques de celdas, filas enteras, columnas enteras o hojas enteras. La API también puede tener acceso a conjuntos de celdas no contiguos.
API de v3
Para determinar la URL de un feed basado en lista correspondiente a una hoja de trabajo determinada, recupera el feed de la hoja de trabajo y busca la URL del feed de lista en la entrada de la hoja de trabajo en cuestión.
Para recuperar un feed basado en 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
Entre otras cosas, la respuesta a esta solicitud contiene entradas que corresponden a filas específicas. Se hace referencia a celdas individuales mediante los nombres provistos en la fila de encabezado (obligatorio) de la hoja. 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 en el feed de lista se muestran por orden de fila. La API de Hojas de cálculo v3 proporciona parámetros de consulta que permiten cambiar el orden.
Orden inverso:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full?reverse=true
Orden según una columna específica:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?orderby=column:lastname
La API de Hojas de cálculo v3 también permite filtrar filas específicas a través de una consulta estructurada (por los encabezados de las columnas):
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?sq=age>25%20and%20height<175API de v4
En la API de Hojas de cálculo v4, se pueden usar los métodos spreadsheets.values.get o spreadsheets.values.batchGet para recuperar las filas por rango. 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 cuenta con parámetros equivalentes a los parámetros de consulta para ordenar filas que ofrece la API de Hojas de cálculo v3. No tiene sentido ordenar las filas de forma inversa; solo debes procesar el array values que se muestra en el orden inverso. El orden por columnas no se admite en las operaciones de lectura, pero es posible ordenar los datos en la solicitud de la hoja (con una solicitud SortRange) y, luego, leerlos.
Actualmente, la API de Hojas de cálculo v4 no ofrece un equivalente directo a 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 nueva fila de datos
Con ambas APIs, puedes agregar una nueva fila de datos a la hoja.
API de v3
Para determinar la URL de un feed basado en lista correspondiente a una hoja de trabajo determinada, recupera el feed de la hoja de trabajo y busca la URL de la publicación en la entrada de la hoja de trabajo en cuestión.
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 la fila que se agregarán, con celdas individuales a las que hacen referencia los encabezados de las columnas:
<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 insertan al final de la hoja especificada.
API de v4
Con la API de Hojas de cálculo v4, puedes agregar filas con el método spreadsheets.values.append. En el siguiente ejemplo, se escribe una nueva fila 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 insertar celdas con propiedades y formatos específicos a través de las solicitudes AppendCells en un spreadsheets.batchUpdate.
Edita una fila con datos nuevos
Ambas APIs permiten actualizar datos de filas 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 quieras actualizar. Actualiza el contenido de la entrada según sea necesario. Asegúrate de que el valor de ID de la entrada que uses sea exactamente igual al 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 API de Hojas de cálculo v4, puedes editar una fila usando la notación A1 de la fila que quieres editar y emitir una solicitud spreadsheets.values.update para sobrescribir esa fila. El rango especificado solo necesita hacer referencia a la primera celda de la fila; la API infiere cuáles son las celdas que se actualizarán según los valores provistos en la solicitud. De otra forma, si especificas un rango de varias celdas, los valores que proporciones deben adecuarse a dicho rango o la API mostrará un error.
En el siguiente ejemplo, la solicitud y el cuerpo de la solicitud agregan datos a la cuarta fila de “Sheet1”:
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A4
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}
También puedes actualizar datos de filas con el método spreadsheet.values.batchUpdate. Usar este método es más eficiente si necesitas actualizar varias filas o celdas.
Además, la API de Hojas de cálculo v4 también te permite editar las propiedades y el formato de las celdas con las solicitudes UpdateCells o RepeatCell en un spreadsheets.batchUpdate.
Cómo borrar una fila
Ambas APIs admiten la eliminación de filas. La fila eliminada se quita de la hoja de cálculo y las filas siguientes suben una posición.
API de v3
Para borrar una fila, primero recupérala del feed de lista y, luego, envía una solicitud DELETE a la URL edit proporcionada en la entrada de la fila.
Es la misma URL que se utiliza 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 haya cambiado desde que la obtuviste, incluye un encabezado If-Match HTTP que contenga el valor ETag de la fila original. Para determinar el valor ETag de la fila original, examina el atributo gd:etag del elemento de entrada.
Si deseas borrar una fila aunque alguien la haya actualizado desde que la recuperaste, utiliza If-Match: * y no incluyas el valor de ETag. (en este caso, no es necesario recuperar la fila antes de borrarla).
API de v4
Para borrar filas en la API de Hojas de cálculo v4, se emplea una llamada al método spreadsheet.batchUpdate con una solicitud DeleteDimension. Esta solicitud también se puede usar para quitar columnas, y los programadores pueden elegir quitar solo parte de una fila o columna. Por ejemplo, en el siguiente ejemplo, se quita la sexta fila de una hoja con el ID determinado (los índices de las filas se basan en cero, y startIndex sí se incluye, pero endIndex no):
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteDimension": {
"range": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 5,
"endIndex": 6
}
}
}
],
}
Se puede recuperar el sheetId de una hoja 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 obtener un acceso básico a todos los datos almacenados en una hoja de cálculo. Para obtener acceso de lectura, el feed de celdas puede proporcionar el contenido de toda la hoja o un rango de celdas definido por un conjunto de parámetros de consulta, pero solo como un bloque entero (los rangos no contiguos se pueden recuperar por separado mediante solicitudes GET adicionales).
La API de Hojas de cálculo v4 puede recuperar de una hoja cualquier conjunto de datos de celdas (incluso varios rangos no contiguos). La API de Hojas de cálculo v3 solo puede mostrar contenido de celdas como valores de entrada (como los ingresaría un usuario por teclado) o los resultados de fórmulas (si son numéricos). La API de Hojas de cálculo v4 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 correspondiente a una hoja de trabajo determinada, examina el feed de la hoja de trabajo y busca la URL del feed de celdas en la entrada de la hoja de trabajo en cuestión.
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 usa el número de fila y columna. Para recuperar un rango específico, puedes usar los parámetros de consulta max-row, min-row, max-col y min-col. Por ejemplo, a continuación se recuperan 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=4
La API de Hojas de cálculo v3 muestra el inputValue de las celdas recuperadas, el valor que, de otra manera, el usuario ingresarí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 muestra un numericValue; por ejemplo, cuando el resultado de una fórmula es un número. Por ejemplo, es posible que una respuesta incluya entradas de celdas cuyas estructuras sean similares a la siguiente:
<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
Si deseas obtener datos de celdas, llama a los métodos spreadsheets.values.get o spreadsheets.values.batchGet para el rango o los rangos (respectivamente) que necesites. Por ejemplo, a continuación se muestran las celdas de la columna D de “Sheet2” a partir de la fila 2, en orden de columna mayor, y las fórmulas se muestran según se hayan ingresado (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 es similar en estructura a lo 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 quieres recuperar varios rangos de datos de celdas. Si quieres acceder a propiedades de las celdas, como el formato, es necesario usar el método spreadsheet.get.
Cómo editar una celda
La API de Hojas de cálculo v3 te permite editar el contenido de una celda mediante el envío de un comando PUT al feed de celdas, con la entrada de la celda modificada como el cuerpo de la solicitud.
En cambio, la API de Hojas de cálculo v4 ofrece 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 debes buscar la entrada de la celda en el
feed de celdas.
La entrada contiene una URL de edición. Modifica la entrada para que refleje el contenido que deseas que tenga la celda. A continuación, envía una solicitud PUT a la URL de edición con la entrada de la celda actualizada como el cuerpo de la solicitud. Por ejemplo, a continuación se 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
En la Sheets API v4, puedes editar una única celda 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:
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/D2?valueInputOption=USER_ENTERED
{"values": [["=SUM(A1:B6)"]]}
Si estás editando varias celdas, usa el método spreadsheets.values.batchUpdate para hacerlo en una sola solicitud.
Editar varias celdas a través de una solicitud por lotes
Ambas APIs ofrecen 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 se haga referencia en una solicitud por lotes estén en un rango contiguo.
Si la edición de una o más celdas falla en el lote, la API de Hojas de cálculo v3 permite que el resto se realice correctamente. Sin embargo, la API de Hojas de cálculo v4 mostrará un error si falla alguna de las modificaciones del lote. Si es así, no llevará a cabo ninguna de ellas.
API de v3
Para editar varias celdas, primero recupera un feed de celdas de la hoja de trabajo. La entrada contiene una URL por lotes. 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 POST y el cuerpo de la solicitud 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 exclusivamente la solicitud en el lote.
El campo batch:operation debe ser update para la edición de celdas. gs:cell
identifica la celda por número de fila y columna, y proporciona los datos nuevos
que se insertarán 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. Cada entrada debe contar con todos los campos.
API de v4
La API de Hojas de cálculo v4 utiliza el método spreadsheets.values.batchUpdate para editar en lote los valores de las celdas.
Para editar varias celdas, se puede emitir 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. De otra forma, si especificas un rango de varias celdas, los valores que proporciones deben adecuarse a dicho rango; de lo contrario, la API mostrará un error.