Si tienes aplicaciones existentes que se basan en la versión 3 de la API de Hojas de cálculo de Google, puedes migrar a la versión 4 de la API de Hojas de cálculo de Google. La versión v4 está basada en JSON, tiene una interfaz más fácil de usar y agrega una cantidad sustancial de funcionalidades que no son posibles en la versión v3.
En esta página, se proporciona una correspondencia 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. La asignación se centra en gran medida en la colección spreadsheets.values, que proporciona la funcionalidad directa de lectura y escritura de celdas. 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 de la versión 4 no son retrocompatibles con las estructuras de 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 v3 se refiere a las hojas dentro de una hoja de cálculo en particular como "hojas de trabajo". Esto es sinónimo del término "hojas" que usa la API 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. Además, suelen requerir 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 que se describen en esta página, sustituye los IDs reales en estas ubicaciones.
La API v3 también asigna un ID a las filas recuperadas con su feed de lista, lo que se representa en esta página con el marcador de posición rowId.
Autoriza solicitudes
Cuando se ejecuta tu app, les solicita a los usuarios que otorguen ciertos permisos; los alcances que especifiques en la aplicación determinarán qué permisos solicita.
API de v3
La API de Hojas de cálculo v3 funciona con un único alcance de autorización:
https://spreadsheets.google.com/feeds
que es un alias para
https://www.googleapis.com/auth/spreadsheets
Se pueden usar cualquiera de los formatos del alcance.
API v4
La API de Hojas de cálculo v4 utiliza uno o más alcances del siguiente conjunto:
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 permisos de solo lectura si tu aplicación no necesita editar las hojas o las propiedades de la hoja del usuario. Usa permisos de hojas de cálculo en lugar de permisos de Drive si la aplicación no necesita acceso general a Drive.
Visibilidad
En versiones anteriores de la API, el término visibilidad se utiliza 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. Una hoja de cálculo public fue "Publicada 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 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 los IDs de las hojas de cálculo. Si la aplicación no tiene permiso para acceder a una hoja de cálculo específica, se mostrará un error. De lo contrario, la llamada continúa.
Proyección
En la API de Hojas de cálculo v3, se usa el término proyección para hacer referencia al conjunto de datos que muestra una llamada a la API determinada: todos ellos o un subconjunto fijo definido dentro de la API. La API de Hojas de cálculo v4 no usa proyección. En su lugar, te da un mayor control sobre los datos que se muestran.
API de v3
En la API v3 de la API de Hojas de cálculo, solo hay dos configuraciones 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 cálculo, lista y celdas).
Al igual que la visibilidad, la proyección debe especificarse 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 v4
Si bien la API de Hojas de cálculo v4 puede mostrar un conjunto de datos completo, 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 mediante un parámetro de consulta de campos.
Por ejemplo, la siguiente consulta solo muestra los títulos de todas las hojas en una hoja de cálculo particular:
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 un medio para crear hojas de cálculo nuevas; en su lugar, se puede usar el método File API Files.create de Drive para crear nuevos archivos de hoja de cálculo. Esto requiere que la aplicación declare el alcance https://www.googleapis.com/auth/drive.
API v4
El método Archivos 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 alcance 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, definir las propiedades de la hoja de cálculo y de la hoja, y agregar rangos con nombre. En el siguiente ejemplo, se crea una hoja de cálculo nueva y se le da el nombre "NewTitle":
POST https://sheets.googleapis.com/v4/spreadsheets
{
"properties": {"title": "NewTitle"}
}Enumera las 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 la hoja de cálculo es:
GET https://spreadsheets.google.com/feeds/spreadsheets/private/full
API 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 alcance drive.file en combinación con el selector de Google para la selección de hojas de cálculo.
En los casos en los que sea necesario enumerar 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 enumerar todas las hojas de cálculo de un usuario requiere un permiso restringido.
Recuperar los metadatos de las 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 (los datos de las filas y celdas se acceden a través de un feed independiente). Los metadatos incluyen información como los títulos y el tamaño de la hoja.
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 hojas de cálculo 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 v4
El método spreadsheets.get se puede usar para obtener las propiedades y otros metadatos de la hoja, mucho más de lo que está disponible en 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 que se incluyan los 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 sobre el 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
},
...
},
...
},
...
],
...
}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 nuevas hojas de cálculo a una hoja de cálculo realizando 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 v4
Para agregar hojas nuevas, realiza 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 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 lo permite, pero también se puede utilizar para actualizar otras propiedades de la hoja. Ten en cuenta que, si reduces el tamaño de una hoja, es posible que se borren sin advertencia los datos de las celdas recortadas.
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 trabajo y busca la entrada deseada de la hoja de cálculo, que contiene la URL de edit.
Actualiza los metadatos de la hoja de cálculo 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 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 modificarán, y el parámetro fields debe enumerar de manera explícita esas propiedades (si deseas actualizar todas las propiedades, usa fields:"*" como forma abreviada para enumerarlas a todas). Por ejemplo, lo siguiente especifica que las propiedades de título y tamaño de la hoja se deben actualizar en la hoja con el ID proporcionado:
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 dos API 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 la hoja de trabajo y, luego, envía una solicitud DELETE en la URL edit de la entrada de la hoja de cálculo de destino.
DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
API 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 hojas de cálculo (leer fila por fila, agregar filas y ordenar), pero hace ciertas suposiciones que hacen que no sea adecuado para algunas tareas. Específicamente, el feed de lista supone que hay filas en blanco que terminan en el feed y que los encabezados obligatorios están presentes en la primera fila de una hoja.
Por el contrario, la API de Hojas de cálculo v4 no usa métodos de acceso que sean específicos de una fila. En su lugar, puedes acceder a los datos de las celdas de la hoja haciendo referencia a los rangos específicos requeridos con la notación A1. Los rangos pueden ser bloques de celdas, filas enteras, columnas enteras o hojas enteras. La API también puede acceder a conjuntos de celdas inconexos.
API de v3
Para determinar la URL de un feed basado en lista de una hoja de cálculo determinada, recupera el feed de la hoja de trabajo y busca la URL del feed de lista en la entrada de la hoja de cálculo en cuestión.
Para recuperar un feed basado en listas, 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 otros datos, la respuesta a esta solicitud contiene entradas correspondientes a filas específicas. Se hace referencia a celdas individuales mediante los nombres proporcionados en la fila de encabezado (obligatoria) de la hoja. Por ejemplo, esta es una sola entrada de 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 de fila. La API de Hojas de cálculo v3 proporciona parámetros de consulta para cambiar ese orden.
Orden inverso:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full?reverse=true
Ordena 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 por medio de una consulta estructurada (a la que se hace referencia por los encabezados de columna):
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?sq=age>25%20and%20height<175API v4
En la API de Hojas de cálculo v4, las filas se pueden recuperar por rango con los métodos spreadsheets.values.get o spreadsheets.values.batchGet. Por ejemplo, lo siguiente muestra todas las filas de “Sheet1”:
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. No tiene sentido ordenar el orden inverso; simplemente procesa el array values que se muestra en el orden inverso. El orden por columna no es compatible con las lecturas, pero es posible ordenar los datos en la hoja (mediante una solicitud SortRange) y, luego, leerlos.
Actualmente, la API de Hojas de cálculo v4 no tiene 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.
Agregar una nueva fila de datos
Puedes agregar una nueva fila de datos a una hoja con cualquiera de las APIs.
API de v3
Para determinar la URL de un feed basado en lista de una hoja de cálculo determinada, recupera el feed de la hoja de trabajo y busca la URL de la publicación en la entrada de la hoja de cálculo en cuestión.
Para agregar una fila de datos, envía una solicitud POST a la URL de la 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, y los encabezados de columna deben hacer referencia a celdas individuales:
<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 v4
En 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 “Sheet1” 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 agregar celdas con propiedades y formatos específicos mediante las solicitudes AppendCells en un archivo spreadsheets.batchUpdate.
Cómo editar una fila con datos nuevos
Ambas APIs permiten actualizar los datos de las 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 deseas actualizar. Actualiza el contenido de esa entrada según sea necesario. Asegúrate de que el valor de ID de la entrada que usas coincida exactamente con el ID de la entrada existente.
Una vez que se actualice 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 v4
En la API de Sheets v4, puedes editar una fila con la notación A1 de la fila que quieras editar y emitir una solicitud spreadsheets.values.update para reemplazarla. El rango especificado solo necesita hacer referencia a la primera celda de la fila; la API infiere qué celdas se actualizarán según los valores proporcionados en la solicitud. En cambio, si especificas un rango de varias celdas, los valores que proporciones deben adecuarse a él; de lo contrario, la API mostrará un error.
En el siguiente ejemplo de solicitud y cuerpo de la solicitud, se 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. Es más eficaz usar este método si quieres 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 mediante las solicitudes UpdateCells o RepeatCell en un spreadsheets.batchUpdate.
Cómo borrar una fila
Ambas APIs admiten la eliminación de filas. La fila borrada se quita de la hoja de cálculo y las filas inferiores suben una.
API de v3
Para borrar una fila, primero recupera la fila que deseas 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 usó 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 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 la fila sin importar si otra persona la actualizó desde que la recuperaste, utiliza If-Match: * y no incluyas la ETag. (en este caso, no es necesario recuperar la fila antes de borrarla).
API v4
Para borrar filas en la API de Hojas de cálculo v4, se emplea una llamada al método spreadsheet.batchUpdate que usa una solicitud DeleteDimension. Esta solicitud también se puede usar para quitar columnas, y los desarrolladores eligen quitar solo parte de una fila o columna. Por ejemplo, lo siguiente quita la sexta fila de una hoja con el ID especificado (los índices de filas se basan en cero, con startIndex incluidos y endIndex excluyentes):
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.
Recuperar datos móviles
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 tener acceso de lectura, el feed de celdas puede proporcionar todo el contenido de la hoja o un rango de las celdas de la hoja definidos por un conjunto de parámetros de consulta, pero solo como un solo bloque. Los rangos inconexos se deben recuperar por separado mediante solicitudes GET adicionales.
La API de Hojas de cálculo v4 puede recuperar cualquier conjunto de datos de celdas de una hoja (incluidos varios rangos disjuntos). La API de Hojas de cálculo v3 solo puede mostrar contenido de celdas como valores de entrada (como lo ingresaría un usuario con un teclado) o resultados de fórmulas (si son numéricas). 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 de una hoja de cálculo determinada, examina el feed de la hoja de trabajo y busca la URL del feed de celdas en la entrada de la hoja de cálculo 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
Se hace referencia a las celdas con el número de fila y columna. Se puede recuperar un solo rango específico con los parámetros de consulta max-row, min-row, max-col y min-col. Por ejemplo, la siguiente tabla 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=4
La API de Hojas de cálculo v3 muestra el inputValue de las celdas recuperadas (el valor que, de lo contrario, un usuario escribiría en la interfaz de usuario de Hojas de cálculo de Google para manipular la celda). inputValue puede ser un valor literal o una fórmula. A veces, la API muestra un numericValue; por ejemplo, cuando una fórmula da como resultado un número. Por ejemplo, una respuesta puede incluir entradas de celda similares en estructura 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 v4
Si quieres recuperar datos de celdas, llama a los métodos spreadsheets.values.get o spreadsheets.values.batchGet para el rango o los rangos de interés, respectivamente. Por ejemplo, el siguiente ejemplo muestra las celdas en la columna D de "Sheet2", comenzando por la fila 2, en orden de columna mayor y mostrando las fórmulas 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 es similar en estructura 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 eficaz usar spreadsheet.values.batchGet si quieres recuperar varios rangos de datos de celdas. Si quieres acceder a las propiedades de la celda, como el formato, es necesario 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. Para ello, emite un comando PUT al feed de celdas con la entrada de la 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 una celda.
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, 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 v4
En la API de Hojas de cálculo v4, puedes editar una sola 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 hubieran ingresado en la IU de Hojas de cálculo (USER_ENTERED) o se dejan sin analizar y se toman como están (RAW). Por ejemplo, a continuación, se 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 estás editando varias celdas, usa el método spreadsheets.values.batchUpdate para hacerlo en una solicitud.
Editar varias celdas a través de 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 se hace referencia en una solicitud por lotes estén en un rango contiguo.
En caso de que falle una o más de las celdas editadas en el lote, la API de Hojas de cálculo v3 permitirá que las demás se realicen con éxito. Sin embargo, la API de Hojas de cálculo v4 mostrará un error si falla alguna de las actualizaciones en lotes y, en ese caso, no aplicará ninguna de ellas.
API de v3
Si quieres editar varias celdas, primero obtén un feed de celdas para la hoja de cálculo. La entrada contiene una URL por lotes. Envía una solicitud POST a esta URL, junto con el cuerpo de la solicitud que describa las celdas que deseas actualizar y su contenido nuevo. La solicitud de 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 de manera única la solicitud dentro del lote.
El campo batch:operation debe ser update para editar las 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. Todos estos campos son obligatorios para cada entrada.
API v4
La API de Hojas de cálculo v4 permite editar los valores de las celdas por lotes con el método spreadsheets.values.batchUpdate.
Para editar varias celdas, se puede emitir una solicitud POST con los cambios en los 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 escribirán en la hoja a partir de esa celda como la coordenada superior izquierda. En cambio, si especificas un rango de varias celdas, los valores que proporciones deben adecuarse a ese rango; de lo contrario, la API mostrará un error.