Migrar da API Sheets v3

Se você tiver apps baseados na API Google Sheets v3, poderá migrar para a API Google Sheets v4. A versão v4 é baseada em JSON, tem uma interface mais fácil de usar e adiciona uma quantidade significativa de funcionalidades que não são possíveis na versão v3.

Nesta página, mostramos um mapeamento entre os comandos mais antigos da API Sheets v3 e as operações equivalentes na API Sheets v4. O mapeamento se concentra principalmente na coleção spreadsheets.values, que fornece funcionalidade direta de leitura e gravação de células. Outros aspectos, como adicionar páginas ou atualizar as propriedades da página, são processados pela coleção spreadsheets. As estruturas JSON da API v4 não são compatíveis com as versões XML usadas na v3.

Para mais informações sobre os recursos disponíveis na API Sheets v4, consulte a Referência da API.

Notação e termos

A API v3 refere-se às páginas de uma planilha específica como "planilhas". Esse é um sinônimo do termo "sheets" que a API v4 usa.

As APIs geralmente exigem que você especifique um ID da planilha com que está trabalhando. Elas também costumam exigir o ID da planilha que está sendo manipulada. Esses valores aparecem como parte do URL do endpoint da API, como parâmetros de consulta ou como parte do corpo de uma solicitação. Nesta página, os marcadores spreadsheetId e sheetId se referem aos IDs da planilha e da página, respectivamente. Ao usar os métodos descritos nesta página, substitua pelos IDs reais nesses locais.

A API v3 também atribui um ID a linhas recuperadas usando o feed de lista. Isso é representado nesta página pelo marcador rowId.

Autorizar solicitações

Quando o app é executado, ele pede que os usuários concedam determinadas permissões. Os escopos especificados no aplicativo determinam quais permissões são solicitadas.

API v3

A API Sheets v3 opera com um único escopo de autorização:

https://spreadsheets.google.com/feeds

que é um alias para

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

Qualquer um dos formatos de escopo pode ser usado.

API v4

A API Sheets v4 usa um ou mais do seguinte conjunto de escopos:

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

Use escopos somente leitura se o aplicativo não precisar fazer edições nas propriedades de páginas ou páginas do usuário. Use escopos de planilhas em vez de escopos do Drive se o aplicativo não precisar de acesso geral ao Drive.

Visibilidade

Em versões mais antigas da API, o termo visibilidade é usado para se referir à disponibilidade de uma determinada planilha.

API v3

A API Sheets v3 expressa visibilidade diretamente em seus endpoints. Uma planilha public foi "Publicado na Web" e, portanto, pode ser acessada pela API sem autorização, enquanto uma planilha private exige autenticação. A visibilidade é especificada no endpoint após o ID da planilha:

https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full

API v4

Na nova API Sheets v4, não há uma declaração de visibilidade explícita. As chamadas de API são feitas usando IDs de planilha. Se o aplicativo não tiver permissão para acessar a planilha especificada, um erro será retornado. Caso contrário, a chamada continua.

Projeção

O termo projeção é usado pela API Sheets v3 para se referir ao conjunto de dados retornados por uma determinada chamada de API, seja ela todas ou um subconjunto fixo definido na API. A API Sheets v4 não usa projeção. Em vez disso, ela permite que você tenha mais controle sobre quais dados são retornados.

API v3

Há apenas duas configurações de projeção possíveis na API Sheets v3. A projeção full retorna todas as informações disponíveis, enquanto basic retorna um subconjunto menor e fixo de dados (para os feeds de planilhas, listas e células). Assim como a visibilidade, a projeção precisa ser especificada no endpoint da API (após a configuração de visibilidade):

https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic

O subconjunto menor de dados fornecido pela projeção basic é valioso para tornar o código mais eficiente, mas não pode ser personalizado.

API v4

Embora a API Sheets v4 possa retornar um conjunto de dados completo, ela não define subconjuntos fixos análogos à configuração de visibilidade basic da API Sheets v3. Os métodos na coleção de planilhas restringem a quantidade de dados retornados usando um parâmetro de consulta fields.

Por exemplo, a seguinte consulta retorna apenas os títulos de todas as páginas de uma planilha específica:

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title

Criar uma planilha

API v3

A API Sheets v3 não fornece uma maneira de criar novas planilhas. Em vez disso, o método Files.create da Drive API pode ser usado para criar novos arquivos de planilha. Isso exige que o aplicativo declare o escopo https://www.googleapis.com/auth/drive.

API v4

O método Files.create da API Drive também pode ser usado com a API Sheets v4, mas exige que o aplicativo forneça o escopo https://www.googleapis.com/auth/drive.

Como alternativa equivalente, a API Sheets v4 oferece um método spreadsheets.create, que também pode adicionar páginas, definir as propriedades delas e adicionar intervalos nomeados. Por exemplo, o código a seguir cria uma nova planilha e atribui a ela o nome "NewTitle":

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

Listar planilhas do usuário autenticado

API v3

Com o feed da API Sheets v3, um aplicativo pode recuperar uma lista de todas as planilhas acessíveis pelo usuário autenticado. O ponto de extremidade do feed de planilha é:

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

API v4

A API Sheets v4 não oferece essa operação específica. Recomendamos migrar seu app para usar o escopo drive.file com o seletor do Google para selecionar planilhas.

Nos casos em que a listagem das planilhas é necessária, ela pode ser replicada com o método Files.list da API Drive usando uma consulta mimeType:

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

O uso do método files.list da API Drive para listar todas as planilhas de um usuário requer um escopo restrito.

Recuperar metadados da planilha

A Sheets API v3 fornece um feed para acessar os metadados de planilha contidos em uma determinada planilha (os dados de linha e célula são acessados por meio de um feed separado). Os metadados incluem informações como títulos de planilhas e informações de tamanho.

Com o método spreadsheets.get da API Sheets v4 oferece acesso a essas informações e muito mais.

API v3

O feed de planilhas pode ser acessado neste endpoint da API (usando um cabeçalho de autorização apropriado):

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

A resposta a essa solicitação tem uma estrutura semelhante a esta, com os dados de cada página contidos em um <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

O método spreadsheets.get pode ser usado para adquirir propriedades de página e outros metadados, muito mais do que está disponível na API Sheets v3. Se você só quiser ler as propriedades da planilha, defina o parâmetro de consulta includeGridData como false para impedir a inclusão dos dados das células da planilha:

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?includeGridData=false

A resposta Spreadsheet contém uma matriz de objetos Sheet. Os títulos da página e as informações de tamanho especificamente podem ser encontrados no elemento SheetProperties desses objetos. Exemplo:

{
  "spreadsheetId": spreadsheetId,
  "sheets": [
      {"properties": {
          "sheetId": sheetId,
          "title": "Sheet1",
          "index": 0,
          "gridProperties": {
              "rowCount": 100,
              "columnCount": 20,
              "frozenRowCount": 1,
              "frozenColumnCount": 0,
              "hideGridlines": false
          },
          ...
       },
       ...
      },
      ...
  ],
  ...
}

Adicionar uma página a uma planilha

As duas APIs permitem que você adicione novas páginas a uma planilha existente.

API v3

A API Sheets v3 pode adicionar novas planilhas a uma planilha fazendo a seguinte solicitação POST (autenticada). Você pode especificar o tamanho da nova página:

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

É possível adicionar novas planilhas fazendo uma solicitação AddSheet no método spreadsheets.batchUpdate. Como parte do corpo da solicitação, você pode especificar as propriedades da nova planilha. Todas as propriedades são opcionais. É um erro fornecer um título usado para uma planilha existente.

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
  "requests": [{
      "addSheet": {
          "properties": {
            "title": "Expenses",
            "sheetType": "GRID",
            "gridProperties": {
              "rowCount": 50,
              "columnCount": 10
            }
          }
      }
  }],
}

Alterar o título e o tamanho de uma página

Com a API Sheets v3, você pode atualizar os títulos e o tamanho das planilhas. A API Sheets v4 também permite isso, mas também pode ser usada para atualizar outras propriedades da página. Reduzir o tamanho de uma página pode fazer com que os dados nas células cortadas sejam excluídos sem aviso prévio.

API v3

Para alterar o título ou o tamanho de uma planilha, comece recuperando o feed de planilhas e encontrando a entrada de planilha desejada, que contém um URL edit. Atualize os metadados da planilha e envie-os como o corpo de uma solicitação PUT para o URL de edição. Exemplo:

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 atualizar o tamanho, o título e outras propriedades da página, faça uma solicitação updateSheetProperties no método spreadsheets.batchUpdate. O corpo da solicitação POST precisa conter as propriedades a serem alteradas, e o parâmetro fields precisa listar explicitamente essas propriedades. Se você quiser atualizar todas as propriedades, use fields:"*" como uma abreviação para listá-las. Por exemplo, o código a seguir especifica que as propriedades de título e tamanho da planilha precisam ser atualizados para a planilha com o ID fornecido:

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 o sheetId de uma página, use o método spreadsheets.get da planilha.

Excluir uma página

Qualquer uma das APIs pode remover páginas de determinada planilha.

API v3

Para excluir uma planilha, comece recuperando o feed da planilha e envie uma solicitação DELETE no URL edit da entrada da planilha de destino.

DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version

API v4

Para excluir uma página, faça uma solicitação DeleteSheet no método spreadsheets.batchUpdate. O corpo da solicitação POST precisa conter apenas o sheetId para a planilha a ser excluída. Exemplo:

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

Para recuperar o sheetId de uma página individual, use o método spreadsheets.get da planilha.

Recuperar dados da linha

O feed de linhas de lista é um dos dois métodos que a API Sheets v3 oferece para acessar dados nas células de uma planilha. O outro é o feed de células. O feed de linhas foi projetado para oferecer suporte a operações de planilha comuns (ler linha por linha, anexar linhas, classificar), mas faz certas suposições que o tornam inadequado para algumas tarefas. Especificamente, o feed de lista presume que as linhas em branco são encerramentos do feed e que os cabeçalhos obrigatórios estão presentes na primeira linha de uma página.

Por outro lado, a API Sheets v4 não usa métodos de acesso específicos de linha. Em vez disso, os dados das células da planilha são acessados com referência aos intervalos específicos necessários com a notação A1. Os intervalos podem ser blocos de células, linhas inteiras, colunas inteiras ou páginas inteiras. A API também pode acessar conjuntos de células não integrados.

API v3

Para determinar o URL de um feed baseado em lista de uma determinada planilha, recupere o feed da planilha e encontre o URL do feed na entrada de planilha em questão.

Para recuperar um feed baseado em lista, envie uma solicitação GET para o URL do feed de lista usando um cabeçalho de autorização apropriado. Exemplo:

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full

A resposta a essa solicitação contém, entre outras coisas, entradas correspondentes a linhas específicas. Células individuais são referenciadas pelos nomes fornecidos na linha (obrigatória) de cabeçalho da página. Por exemplo, aqui está uma entrada de linha única:

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

Por padrão, as linhas retornadas no feed de lista são retornadas em ordem de linhas. A API Sheets v3 fornece parâmetros de consulta para alterar essa ordem.

Ordem inversa:

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full?reverse=true

Ordenar por uma coluna específica:

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
             ?orderby=column:lastname

Com a API Sheets v3, também é possível filtrar linhas específicas por meio de uma consulta estruturada (referenciada pelos cabeçalhos das colunas):

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

API v4

Com a API Sheets v4, é possível recuperar linhas por intervalo usando os métodos spreadsheets.values.get ou spreadsheets.values.batchGet. Por exemplo, o código a seguir retorna todas as linhas da "Sheet1":

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1

A resposta a essa solicitação tem uma estrutura semelhante a:

{
  "range": "Sheet1",
  "majorDimension": "ROWS",
  "values": [["Name", "Hours", "Items", "IPM"],
             ["Bingley", "10", "2", "0.0033"],
             ["Darcy", "14", "6", "0.0071"]]
}

As células vazias posteriores não são incluídas na resposta ao recuperar linhas, colunas ou páginas inteiras.

A API Sheets v4 não tem equivalentes para os parâmetros de consulta de ordem de linha fornecidos pela API Sheets v3. A ordem inversa é trivial. Basta processar a matriz values retornada na ordem inversa. A ordenação por coluna não é compatível com leituras, mas é possível classificar os dados na planilha usando uma solicitação SortRange e lê-los.

Atualmente, a API Sheets v4 não tem um equivalente direto para as consultas estruturadas da API Sheets v3. No entanto, é possível recuperar os dados relevantes e classificá-los conforme necessário no aplicativo.

Adicionar uma nova linha de dados

Você pode adicionar uma nova linha de dados a uma planilha usando qualquer uma das APIs.

API v3

Para determinar o URL de um feed baseado em lista de uma determinada planilha, recupere o feed de planilhas e encontre o URL da postagem na entrada relevante da planilha.

Para adicionar uma linha de dados, envie uma solicitação POST ao URL da postagem usando um cabeçalho de autorização apropriado. Exemplo:

POST https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full

O corpo da solicitação POST precisa conter uma entrada para os dados da linha a serem adicionados, com células individuais referenciadas por cabeçalhos de coluna:

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

Novas linhas são anexadas ao final da página especificada.

API v4

Com a API Sheets v4, você pode anexar linhas usando o método spreadsheets.values.append. O exemplo a seguir grava uma nova linha de dados abaixo da última tabela na "Sheet1" de uma planilha.

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1

{
   "values": [["Elizabeth", "2", "0.5", "60"]]
}

Além disso, a API Sheets v4 também permite que você anexe células com propriedades e formatação específicas usando as solicitações AppendCells em spreadsheets.batchUpdate.

Editar uma linha com novos dados

As duas APIs permitem que os dados da linha sejam atualizados com novos valores.

API v3

Para editar uma linha de dados, examine o feed de lista para localizar a entrada da linha que você quer atualizar. Atualize o conteúdo dessa entrada conforme necessário. Verifique se o valor do ID na entrada usada corresponde exatamente ao ID da entrada existente.

Depois que a entrada for atualizada, envie uma solicitação PUT com a entrada como o corpo da solicitação para o URL edit fornecido nessa entrada de linha, usando um cabeçalho de autorização apropriado. Exemplo:

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

Com a API Sheets v4, é possível editar uma linha usando a notação A1 da linha que você quer editar e emitindo uma solicitação spreadsheets.values.update para substituir essa linha. O intervalo especificado precisa fazer referência apenas à primeira célula da linha. A API infere as células a serem atualizadas com base nos valores fornecidos com a solicitação. Se, em vez disso, você especificar um intervalo com várias células, os valores fornecidos precisarão estar dentro desse intervalo. Caso contrário, a API retornará um erro.

O exemplo de solicitação e corpo da solicitação a seguir adiciona dados à quarta linha da "Sheet1":

PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A4
{
   "values": [["Elizabeth", "2", "0.5", "60"]]
}

Também é possível atualizar os dados das linhas com o método spreadsheet.values.batchUpdate. Esse método é mais eficiente se você estiver fazendo várias atualizações de linhas ou células.

Além disso, a API Sheets v4 também permite editar as propriedades e a formatação das células usando as solicitações UpdateCells ou RepeatCell em spreadsheets.batchUpdate.

Excluir uma linha

As duas APIs oferecem suporte à exclusão de linhas. Uma linha excluída é removida da planilha, e as linhas abaixo dela sobem uma.

API v3

Para excluir uma linha, primeiro recupere a linha a ser excluída do feed de lista e envie uma solicitação DELETE para o URL edit fornecido na entrada da linha. Esse é o mesmo URL usado para atualizar a linha.

DELETE https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version

Se você quiser garantir que você não exclua uma linha que foi alterada por outro cliente desde que a recuperou, inclua um cabeçalho HTTP if-Match que contenha o valor ETag da linha original. Você pode determinar o valor de ETag da linha original examinando o atributo gd:etag do elemento da entrada.

Se você quiser excluir a linha independentemente de alguém a ter atualizado desde a recuperação, use "If-Match: *" e não inclua a ETag. Nesse caso, não é preciso recuperar a linha antes de excluí-la.

API v4

A exclusão de linhas com a API Sheets v4 é realizada por uma chamada de método spreadsheet.batchUpdate usando uma solicitação DeleteDimension. Essa solicitação também pode ser usada para remover colunas, e os desenvolvedores escolhem remover apenas parte de uma linha ou coluna. Por exemplo, o código a seguir remove a 6a linha de uma página com o ID fornecido (os índices de linha são baseados em zero, com startIndex incluído e endIndex exclusivo):

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
  "requests": [
    {
      "deleteDimension": {
        "range": {
          "sheetId": sheetId,
          "dimension": "ROWS",
          "startIndex": 5,
          "endIndex": 6
        }
      }
    }
  ],
}

O sheetId de uma planilha pode ser recuperado com o método spreadsheet.get.

Recuperar dados de celular

A API Sheets v3 fornece um feed de células para acesso básico a todos os dados armazenados em uma planilha. Para acesso de leitura, o feed de células pode fornecer todo o conteúdo da planilha ou um intervalo de células da planilha definido por um conjunto de parâmetros de consulta, mas apenas como um único bloco: intervalos separados precisam ser recuperados separadamente usando solicitações GET adicionais.

A API Sheets v4 pode recuperar qualquer conjunto de dados de célula de uma planilha, incluindo vários intervalos não sequenciais. A API Sheets v3 só pode retornar o conteúdo das células como valores de entrada (como seria inserido por um usuário em um teclado) e/ou como saídas de fórmula (se forem numéricos). A API Sheets v4 concede acesso total a valores, fórmulas, formatação, hiperlinks, validação de dados e outras propriedades.

API v3

Para determinar o URL de um feed baseado em células de uma determinada planilha, examine o feed de planilhas e encontre o URL do feed de células na entrada relevante da planilha.

Para recuperar um feed baseado em células, envie uma solicitação GET para o URL do feed de células, usando um cabeçalho de autorização apropriado. Exemplo:

GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full

As células são referenciadas usando número de linha e coluna. A busca de um único intervalo específico pode ser feita usando os parâmetros de consulta max-row, min-row, max-col e min-col. Por exemplo, o comando a seguir recupera todas as células na coluna 4 (D), começando com a linha 2:

GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
             ?min-row=2&min-col=4&max-col=4

A API Sheets v3 retorna o inputValue das células recuperadas, o valor que um usuário digitaria na interface do usuário do Planilhas Google para manipular a célula. O inputValue pode ser um valor literal ou uma fórmula. Às vezes, a API também retorna um numericValue. Por exemplo, quando uma fórmula resulta em um número. Por exemplo, uma resposta pode incluir entradas de células com uma estrutura semelhante a esta:

<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

Recupere dados de células chamando um método spreadsheets.values.get ou spreadsheets.values.batchGet para os intervalos de interesse, respectivamente. Por exemplo, o seguinte retorna as células na coluna D da "Sheet2", começando pela linha 2, na ordem da coluna maior e retornando as fórmulas conforme inseridas (as células vazias finais são omitidas):

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet2!D2:D?majorDimension=COLUMNS&valueRenderOption=FORMULA

A resposta a essa solicitação tem uma estrutura semelhante a:

{
  "spreadsheetId": spreadsheetId,
  "valueRanges": [
      {"range": "Sheet2!D2:D",
       "majorDimension": "COLUMNS",
       "values": [["Widget", 234, "=FLOOR(C4/(B4*60),.0001)", "=D4\*1000"]]
      }]
}

É mais eficiente usar spreadsheet.values.batchGet caso você pretenda recuperar vários intervalos de dados de células. Se você quiser acessar propriedades da célula como a formatação, o método spreadsheet.get será necessário.

Editar uma célula

Com a Sheets API v3, você pode editar o conteúdo da célula emitindo um comando PUT para o feed de células com a entrada de célula modificada como o corpo da solicitação.

Por outro lado, a API Sheets v4 fornece os métodos spreadsheets.values.update e spreadsheets.values.batchUpdate para alterar o conteúdo das células.

API v3

Para editar o conteúdo de uma única célula, primeiro encontre a entrada dela no feed de células. A entrada contém um URL de edição. Atualize a entrada para refletir o conteúdo que você quer que a célula tenha e emita uma solicitação PUT para o URL de edição com a entrada de célula atualizada como o corpo da solicitação. Por exemplo, o seguinte atualiza a célula D2 (R2C4) para conter uma 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

Na API Sheets v4, é possível editar uma única célula com o método spreadsheets.values.update. Esse método requer um parâmetro de consulta ValueInputOption, que especifica se os dados de entrada serão tratados como se inseridos na interface do Planilhas (USER_ENTERED) ou se foram deixados não analisados e utilizados como estão (RAW). Por exemplo, o seguinte código atualiza a célula D2 com uma fórmula:

PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/D2?valueInputOption=USER_ENTERED
{"values": [["=SUM(A1:B6)"]]}

Se estiver fazendo várias edições de célula, use o método spreadsheets.values.batchUpdate para emiti-las em uma solicitação.

Editar várias células por meio de solicitação em lote

Ambas as APIs fornecem meios de fazer alterações no conteúdo de várias células com uma única solicitação (em lote). As células referenciadas por uma solicitação em lote não precisam estar em um intervalo contínuo.

Em caso de falha em uma ou mais edições de células no lote, a API Sheets v3 permite que outras sejam bem-sucedidas. No entanto, a API Sheets v4 retornará um erro se alguma das atualizações em lote falhar e não aplicará nenhuma delas.

API v3

Para editar várias células, primeiro recupere um feed de células para a planilha. A entrada contém um URL de lote. Envie uma solicitação POST para esse URL com o corpo da solicitação que descreva as células que você quer atualizar e o novo conteúdo delas. A solicitação POST e o corpo da solicitação têm uma estrutura semelhante a esta:

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>

O campo batch:id precisa identificar exclusivamente a solicitação no lote. O campo batch:operation precisa ser update para edições de células. gs:cell identifica a célula por número de linha e coluna e fornece os novos dados para inserir lá. id contém o URL completo da célula a ser atualizada. link precisa ter um atributo href que contenha o caminho completo para o ID da célula. Todos esses campos são obrigatórios para cada entrada.

API v4

A API Sheets v4 oferece edição em lote de valores de células por meio do método spreadsheets.values.batchUpdate.

É possível editar várias células emitindo uma solicitação POST com as alterações de dados especificadas no corpo da solicitação. Exemplo:

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"]]
       }
  ]
}

Se você especificou uma única célula como intervalo, todos os valores fornecidos são gravados na página que começa com essa célula como a coordenada de canto superior esquerdo. Se, em vez disso, você especificar um intervalo com várias células, os valores fornecidos precisarão se adequar exatamente a esse intervalo. Caso contrário, a API retornará um erro.