Migrar desde la API de Hojas de cálculo v3

Si tienes apps existentes basadas en la API de Hojas de cálculo de Google v3, puedes migrar a API de Hojas de cálculo de Google v4. La versión v4 se basa en JSON y es más fácil de usar. y agrega una cantidad considerable de funcionalidades que no son posibles en la versión v3.

Esta página proporciona una correspondencia entre los comandos antiguos de la API de Hojas de cálculo v3 y sus equivalentes en la API de Hojas de cálculo v4. La asignación se centra mayormente en el spreadsheets.values que ofrece funciones directas de lectura y escritura de celdas. Otros aspectos, como agregar hojas o actualizar sus propiedades, se gestionan la colección hojas de cálculo. Ten en cuenta que las estructuras JSON de la API v4 no son retrocompatibles con la Estructuras XML utilizadas 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

La API v3 se refiere a las hojas dentro de una hoja de cálculo en particular como “hojas de trabajo”. Estos términos son sinónimos del término "hojas de cálculo". que usa la API v4.

Las APIs a menudo requieren que especifiques un ID de hoja de cálculo. de la hoja de cálculo en la que estás trabajando. También requieren el ID del que se manipule. Estos valores aparecen como parte del extremo de la API como parámetros de consulta o como parte del cuerpo de una solicitud. En esta página, la pestaña los marcadores de posición spreadsheetId y sheetId se refieren a los IDs de la hoja de cálculo y de la hoja, respectivamente. Cuando uses los métodos descritos en esta página, reemplace los ID reales en estas ubicaciones.

La API v3 también asigna un ID a las filas recuperadas mediante su feed de lista; Esto 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 que especifiques en la aplicación determinan qué permisos solicitará.

API 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 del

https://www.googleapis.com/auth/spreadsheets

Se puede usar cualquiera de los formatos del alcance.

API v4

La API de Hojas de cálculo v4 usa uno o más de los siguientes conjuntos de alcances:

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 de un usuario o las propiedades de la hoja. Usa el alcance de las 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 usa para referirse al la disponibilidad de una hoja de cálculo determinada.

API v3

La API de Hojas de cálculo v3 expresa la visibilidad directamente en sus endpoints. Un public la hoja de cálculo se haya "publicado en la Web" y, por lo tanto, puede accederse a API sin autorización, mientras que una hoja de cálculo private sí requiere la autenticación de varios factores. La visibilidad se especifica en el endpoint 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 mediante los ID de la hoja de cálculo. Si la aplicación no tiene permiso para acceder a una hoja de cálculo específica, se muestra un error. En caso 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 definidos dentro de la API. La API de Hojas de cálculo v4 no utiliza proyección. más bien, te permite tener más control sobre los datos que se devuelven.

API v3

Solo hay dos posibles configuraciones de proyección en la API de Hojas de cálculo v3. full proyección 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 devolver un conjunto de datos completo, no define subconjuntos análogos a la configuración de visibilidad de basic de la API de Hojas de cálculo v3. Métodos de la hoja de cálculo de datos restringen la cantidad de datos que devuelven mediante el uso un parámetro de consulta de fields.

Por ejemplo, la siguiente consulta solo devuelve los títulos de todos los hojas en 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 v3

La API de Hojas de cálculo v3 no proporciona un medio para crear hojas de cálculo nuevas. en su lugar, el archivo Files.create de la API de Drive se puede usar para crear nuevos archivos de hoja de cálculo. Esto requiere la aplicación para declarar el alcance de https://www.googleapis.com/auth/drive.

API v4

El método Files.create de la API de Drive puede puede usarse con la API de Hojas de cálculo v4, pero requiere que la aplicación proporcione el permiso de https://www.googleapis.com/auth/drive.

Como alternativa equivalente, la API de Hojas de cálculo v4 ofrece un spreadsheets.create que también puede agregar hojas, establecer la hoja de cálculo y la hoja y agrega rangos con nombre. Por ejemplo, lo siguiente crea un nuevo hoja de cálculo y le asigna el nombre “NewTitle”:

POST https://sheets.googleapis.com/v4/spreadsheets
{
 "properties": {"title": "NewTitle"}
}

Obtén una lista de las hojas de cálculo del usuario autenticado

API v3

El feed de la API de Hojas de cálculo v3 permite que una aplicación recupere una lista de todos los hojas de cálculo a las que puede acceder el usuario autenticado. El feed de la hoja de cálculo extremo es:

GET https://spreadsheets.google.com/feeds/spreadsheets/private/full

API v4

La API de Hojas de cálculo v4 no proporciona esta operación específica. Recomendaciones migrar tu aplicación para usar el alcance drive.file junto con el Selector de Google para la selección de la hoja de cálculo.

En los casos en que sea obligatorio enumerar las hojas de cálculo, se puede replicar. por medio del método Files.list de la API de Drive Una consulta mimeType:

GET https://www.googleapis.com/drive/v3/files
             ?q=mimeType='application/vnd.google-apps.spreadsheet'

Usar el 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 metadatos de hojas

La API de Hojas de cálculo v3 proporciona un feed para acceder a los metadatos de la hoja contenidos en una hoja de cálculo determinada (se accede a los datos de las filas y celdas mediante un feed independiente). Los metadatos incluyen información como los títulos de las hojas y la información del tamaño.

La API de Hojas de cálculo v4 spreadsheets.get proporciona acceso a esta información y mucho más.

API v3

Se puede acceder al feed de hojas de cálculo desde este extremo de 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: los datos de cada hoja contenidos en un <entry> separado:

<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 comando spreadsheets.get se puede usar para adquirir las propiedades de la hoja y otros metadatos, más de la que está disponible en la API de Sheets v3. Si solo para leer las propiedades de la hoja, establece la consulta includeGridData parámetro para 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 Spreadsheet contiene un array de Sheet objetos; se pueden encontrar específicamente los títulos de las hojas y la información del tamaño en el 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 API te permiten agregar nuevas hojas a una hoja de cálculo existente.

API v3

La API de Hojas de cálculo v3 puede agregar nuevas hojas de cálculo a una hoja de cálculo haciendo la siguiente solicitud de POST (autenticada). Puedes especificar el tamaño nueva hoja:

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, haz una AddSheet en el archivo spreadsheets.batchUpdate . En el cuerpo de la solicitud, puedes especificar las propiedades de la hoja para la nueva hoja; 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
            }
          }
      }
  }],
}

Cambiar el título y 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. API de Hojas de cálculo v4 permite esta acción también, pero también se puede utilizar para actualizar otras propiedades de la hoja. Si reduces el tamaño de una hoja, es posible que los datos de las celdas recortadas se se eliminó sin previo aviso.

API v3

Para cambiar el título o tamaño de una hoja de cálculo, empieza por recuperar el feed de hoja de trabajo y encontrar la entrada de la hoja de cálculo deseada, que contiene una URL 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, crea una updateSheetProperties solicitud en la spreadsheets.batchUpdate . El cuerpo de la solicitud POST debe contener las propiedades que se y el parámetro fields debería enumerar esas propiedades de forma explícita (si deseas actualizar todas las propiedades, usa fields:"*" como abreviatura de enumerándolos todos). Para ejemplo, el siguiente especifica que el título y el tamaño de la hoja las propiedades se deben actualizar para la hoja con el ID dado:

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 la hoja de cálculo spreadsheets.get.

Cómo borrar una hoja

Ambas API pueden quitar hojas de una hoja de cálculo determinada.

API v3

Para borrar una hoja de cálculo, primero recupera el feed de 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, haz una DeleteSheet solicitud en la spreadsheets.batchUpdate . El cuerpo de la solicitud POST solo debe contener el sheetId de la hoja de cálculo que se elimine. Por ejemplo:

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
  "requests": [
    {
      "deleteSheet": {
        "sheetId": sheetId
      }
    }
  ],
}

Para recuperar el sheetId de una hoja individual, usa la hoja de cálculo spreadsheets.get .

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 el feed de filas está diseñado para admitir operaciones comunes de hojas de cálculo (leer fila por fila, anexar filas, ordenar), pero hace ciertas suposiciones que lo vuelven inadecuado. para algunas tareas. Específicamente, el feed de lista supone que las filas en blanco corresponden al feed finalizaciones y que los encabezados obligatorios estén presentes en la primera fila de una de la hoja de cálculo.

Por el contrario, la API de Hojas de cálculo v4 no usa métodos de acceso con las siguientes características: específicas de cada fila. Para acceder a los datos de las celdas de las hojas, se debe hacer referencia a los rangos requeridos con la notación A1. El Los rangos pueden ser bloques de celdas, filas enteras, columnas enteras u hojas enteras. La API también puede acceder a conjuntos de celdas inconexos.

API v3

Para determinar la URL de un feed basado en listas para 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 que te interesa.

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

La respuesta a esta solicitud contiene, entre otras cosas, entradas correspondientes a filas específicas. Se hace referencia a celdas individuales mediante los nombres proporcionados en la fila de encabezado (obligatorio) de la hoja. Por ejemplo, aquí 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 mostradas 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 a través de un consulta (referencia por los encabezados de las columnas):

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
             ?sq=age>25%20and%20height<175

API v4

Con la API de Hojas de cálculo v4, las filas se pueden recuperar por rango con el 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 recupera información completa. filas, columnas u hojas.

La API de Hojas de cálculo v4 no tiene equivalentes para la consulta de orden de filas parámetros proporcionados por la API de Hojas de cálculo v3. El orden inverso es trivial; simplemente Procesa el array values que se muestra en orden inverso. Ordenar por columna no es compatibles con las lecturas, pero es posible ordenar los datos de la hoja (usando un SortRange) la solicitud y, luego, leerla.

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 lo ordenarás según sea necesario en tu aplicación.

Agregar una nueva fila de datos

Puedes usar cualquiera de las APIs para agregar una nueva fila de datos a una hoja.

API v3

Para determinar la URL de un feed basado en listas para 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 que te interese.

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 en add, 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 agregan al final de la hoja especificada.

API v4

Con la API de Hojas de cálculo v4, puedes agregar filas con la 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 permite agregar celdas con las propiedades y el formato con el AppendCells solicitudes en una spreadsheets.batchUpdate.

Editar una fila con datos nuevos

Ambas APIs permiten actualizar los datos de las filas con valores nuevos.

API v3

Para editar una fila de datos, examina el feed de lista. para ubicar 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 en la entrada que uses sea exactamente coincide con el ID de la entrada existente.

Una vez que se haya actualizado la entrada, envía una solicitud PUT con la entrada como el del 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

Con la API de Hojas de cálculo v4, puede editar una fila con la Notación A1 de la fila que deseas editar y emitir un spreadsheets.values.update para reemplazar esa fila. El rango especificado solo debe hacer referencia al primera celda de la fila; la API infiere las celdas que se actualizarán según la valores proporcionados con la solicitud. En cambio, si especificas un rango de varias celdas, los valores que proporcione deben encajar dentro de ese rango; De lo contrario, la API devuelve un .

En el siguiente ejemplo, la solicitud y el cuerpo de la solicitud agregan datos al 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 los datos de las filas desde spreadsheet.values.batchUpdate método; es más eficiente usar este método si haces varios actualizaciones de filas o celdas.

Además, la API de Hojas de cálculo v4 te permite editar las propiedades de la celda y el formato de las celdas con el UpdateCells o RepeatCell solicitudes en una spreadsheets.batchUpdate.

Cómo borrar una fila

Ambas APIs admiten la eliminación de filas. Una fila eliminada se quita del de la hoja de cálculo y las filas inferiores suben una posición.

API v3

Para borrar una fila, primero debes recuperarla feed de lista, Luego, envía una solicitud DELETE a la URL edit proporcionada en la entrada de la fila. Esta 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 desea asegurarse de no eliminar una fila que haya cambiado por otro cliente, ya que la recuperaste, incluye un encabezado If-Match HTTP que contiene el valor ETag de la fila original. Puedes determinar el estado valor de ETag de la fila examinando el atributo gd:etag del elemento de entrada.

Si deseas borrar una fila sin tener en cuenta si alguien más la actualizó dado que la recuperaste, usa If-Match: * y no incluyas la ETag. (en este caso, no es necesario recuperar la fila antes de borrarla).

API v4

Con la API de Hojas de cálculo v4, la eliminación de filas se realiza mediante un spreadsheet.batchUpdate. de método de entrada con una clase DeleteDimension para cada solicitud. Esta solicitud también se puede usar para quitar columnas, y los desarrolladores y eliges quitar solo parte de una fila o columna. Por ejemplo, el quita la sexta fila de una hoja con el ID especificado (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 spreadsheet.get.

Cómo recuperar datos de celdas

La API de Hojas de cálculo v3 ofrece un feed de celdas para obtener un acceso básico a todos los datos almacenados en una en una hoja de cálculo. Para tener acceso de lectura, el feed de celdas puede proporcionar toda la hoja contenido o un rango de celdas de la hoja, definidas por un conjunto de parámetros de consulta, pero solo como un bloque: los rangos inconexos deben recuperarse. por separado con solicitudes GET adicionales.

La API de Hojas de cálculo v4 puede recuperar cualquier conjunto de datos de celdas de una hoja (incluso varios rangos inconexos). La API de Hojas de cálculo v3 solo puede devolver contenido de celdas como valores de entrada (tal como lo ingresaría un usuario con un teclado) o las salidas de fórmula (si es numérico); la API de Hojas de cálculo v4 otorga acceso completo a los valores, fórmulas, formato, hipervínculos, validación de datos y otras propiedades.

API v3

Para determinar la URL de un feed basado en celdas para una hoja de cálculo determinada, examina feed de hoja de trabajo 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 usa el número de fila y columna. Recuperar un solo elemento el rango se puede realizar con max-row, min-row, max-col y min-col parámetros de consulta. Por ejemplo, lo siguiente recupera todas las celdas de una columna 4 (D), comenzando con 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: valor que un usuario de otro modo escribiría en el 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 también muestra un numericValue. por ejemplo, cuando una fórmula da como resultado un número. Por ejemplo, una respuesta puede incluir celdas entradas 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

Recupera datos de celdas llamando a spreadsheets.values.get o spreadsheets.values.batchGet para los rangos de interés, respectivamente. Por ejemplo, el muestra las celdas de la columna D de “Hoja2”, comenzando por la fila 2, en el orden de columna mayor y mostrar las fórmulas tal como se ingresaron (está vacío al final se omiten las celdas):

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 deseas acceder a las propiedades de las celdas, como el formato, spreadsheet.get obligatorio.

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 para el feed de celdas con la entrada de celda modificada como cuerpo de la solicitud.

La API de Hojas de cálculo v4, en cambio, brinda spreadsheets.values.update y spreadsheets.values.batchUpdate métodos para cambiar el contenido de las celdas.

API v3

Para editar el contenido de una sola celda, busca la entrada de la celda en la 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, envía una solicitud PUT a la URL de edición con la entrada de celda actualizada como cuerpo de la solicitud. Por ejemplo, el 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 v4

En la API de Hojas de cálculo v4, puedes editar una sola celda con la 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 IU de Hojas de cálculo (USER_ENTERED) o sin analizar y tomar como está (RAW). Para ejemplo, lo siguiente 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 editas varias celdas, usa el spreadsheets.values.batchUpdate para emitirlos 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 solicitud única (por lotes). Las celdas a las que hace referencia una solicitud por lotes se no es necesario que estén en un rango contiguo.

En caso de que falle una o más modificaciones de las celdas en el lote, la API de Hojas de cálculo v3 permite que los demás se hagan correctamente. Sin embargo, la API de Hojas de cálculo v4 devuelve un error si falla alguna de las actualizaciones por lotes y, en ese caso, no aplica ninguna de ellas.

API v3

Para editar varias celdas, primero debes recuperar un feed de celdas para la hoja de cálculo. La entrada contiene una URL por lotes. Enviar un POST a esta URL, junto con un cuerpo de la solicitud que describe las celdas que deseas actualizar y el nuevo contenido de la celda. 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 de manera única la solicitud dentro del lote. El campo batch:operation debe ser update para las ediciones de las celdas. gs:cell identifica la celda por número de fila y columna, y proporciona los datos nuevos para insertarlos 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 el ID de la celda. Todos estos campos son obligatorios para cada entrada.

API v4

La API de Hojas de cálculo v4 permite editar por lotes los valores de las celdas mediante la spreadsheets.values.batchUpdate .

Para editar varias celdas, puedes enviar una solicitud POST con el 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 especificas una sola celda como rango, todos los valores proporcionados son escrito en la hoja y comienza con esa celda como la coordenada superior izquierda. En cambio, si especificas un rango de varias celdas, los valores que proporciones deben ajustarse ese rango exactamente; De lo contrario, la API mostrará un error.