Se você tiver apps baseados na API Google Sheets v3, migre para a API Google Sheets v4. A versão 4 é baseada em JSON, tem uma interface mais fácil de usar e adiciona uma quantidade substancial de funcionalidades que não são possíveis na versão 3.
Esta página fornece 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 oferece funcionalidade direta de leitura e gravação de células. Outros aspectos, como adicionar planilhas ou atualizar propriedades delas, são processados pela coleção spreadsheets. As estruturas JSON da API v4 não são compatíveis com as estruturas XML usadas na v3.
Para mais informações sobre os recursos disponíveis na API Google Sheets v4, consulte a Referência da API.
Notação e termos
A API v3 se refere a planilhas em uma planilha específica como "planilhas". É sinônimo do termo "planilhas" usado pela API v4.
As APIs geralmente exigem que você especifique um ID da planilha 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 de um corpo de solicitação. Nesta página, os marcadores de posição spreadsheetId e sheetId se referem aos IDs da planilha e da página, respectivamente. Ao usar os métodos descritos nesta página, substitua os IDs reais nesses locais.
A API v3 também atribui um ID às linhas recuperadas usando o feed de lista; isso é representado nesta página pelo marcador de posição rowId.
Autorizar solicitações
Quando o app é executado, ele pede aos usuários que concedam determinadas permissões. Os escopos que você especifica 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 de
https://www.googleapis.com/auth/spreadsheets
Qualquer um dos formatos de escopo pode ser usado.
API v4
A API Google Sheets v4 usa um ou mais dos seguintes conjuntos 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 planilhas ou nas propriedades delas de um usuário. Use escopos do 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 Google Sheets v3 expressa a visibilidade diretamente nos endpoints. Uma planilha public foi "Publicada 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 Google Sheets v4, não há declaração explícita de visibilidade. 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 Google Sheets v3 para se referir ao conjunto de dados retornado por uma determinada chamada de API, seja ele completo ou um subconjunto fixo definido na API. A API Google Sheets v4 não usa projeção. Em vez disso, ela permite mais controle sobre os dados retornados.
API v3
Há apenas duas configurações de projeção possíveis na API Google 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 (depois da configuração de visibilidade):
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic
O subconjunto menor de dados fornecido pela projeção basic é útil para tornar o código mais eficiente, mas não pode ser personalizado.
API v4
Embora a API Google Sheets v4 possa retornar um conjunto de dados completo, ela não define subconjuntos fixos análogos à configuração de visibilidade basic da API Google Sheets v3.
Os métodos na coleção spreadsheet restringem a quantidade de dados retornados usando um parâmetro de consulta fields.
Por exemplo, a consulta a seguir retorna apenas os títulos de todas as planilhas em 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 oferece uma maneira de criar planilhas. Em vez disso, o método Files.create da API Drive pode ser usado para criar 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 Google Sheets v4 oferece um método spreadsheets.create, que também pode adicionar planilhas, definir as propriedades da planilha e da página e adicionar intervalos nomeados. Por exemplo, o comando a seguir cria uma nova planilha e dá a ela o nome "NewTitle":
POST https://sheets.googleapis.com/v4/spreadsheets
{
"properties": {"title": "NewTitle"}
}Listar planilhas do usuário autenticado
API v3
O feed da API Sheets v3 permite que um aplicativo recupere uma lista de todas as planilhas acessíveis pelo usuário autenticado. O endpoint 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 em combinação com o Google Picker para seleção de planilhas.
Nos casos em que é necessário listar planilhas, isso pode ser replicado
pelo 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'Usar o método files.list da API Drive para listar todas as planilhas de um usuário exige um escopo restrito.
Recuperar metadados da planilha
A API Google Sheets v3 fornece um feed para acessar os metadados da planilha contidos em uma determinada planilha. Os dados de linha e célula são acessados por um feed separado. Os metadados incluem informações como títulos e tamanho das planilhas.
O método spreadsheets.get da API Google Sheets v4 fornece acesso a essas informações e muito mais.
API v3
O feed da planilha é acessível por esse endpoint da API (usando um cabeçalho de autorização adequado):
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 planilha 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 da planilha e outros metadados, muito mais do que o que está disponível usando a API Sheets v3. Se você quiser apenas ler as propriedades da planilha, defina o parâmetro de consulta includeGridData como false para evitar 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 e as informações de tamanho das planilhas 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
Com as duas APIs, é possível adicionar novas páginas a uma planilha.
API v3
A API Sheets v3 pode adicionar novas planilhas a uma planilha fazendo a seguinte solicitação POST (autenticada). É possível 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
Para adicionar novas planilhas, faça 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
}
}
}
}],
}Mudar o título e o tamanho de uma página
A API Sheets v3 permite atualizar títulos e tamanhos de planilhas. A API Sheets v4 também permite isso, mas pode ser usada para atualizar outras propriedades de planilhas. Reduzir o tamanho de uma planilha pode causar a exclusão dos dados nas células cortadas sem aviso prévio.
API v3
Para mudar o título ou o tamanho de uma planilha, comece recuperando o feed de planilhas e encontrando a entrada da 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 planilha, 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 abreviação para
listar todas elas). Por exemplo, o seguinte especifica que as propriedades de título e tamanho da planilha devem ser atualizadas 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 um sheetId de uma página, use o método spreadsheets.get.
Excluir uma página
Qualquer uma das APIs pode remover planilhas de uma planilha específica.
API v3
Para excluir uma planilha, comece recuperando o feed de planilhas 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 só pode conter o sheetId da 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 planilha individual, use o método spreadsheets.get da planilha.
Recuperar dados de linha
O feed de lista de linhas é um dos dois métodos que a API Google Sheets v3 oferece para acessar dados nas células de uma planilha. O outro é o feed de células. O feed de linhas foi criado para oferecer suporte a operações comuns de planilhas (leitura linha por linha, adição de linhas, classificação), mas faz algumas proposições que o tornam inadequado para algumas tarefas. Especificamente, o feed de lista pressupõe que as linhas em branco são terminações de feed e que os cabeçalhos obrigatórios estão presentes na primeira linha de uma planilha.
Por outro lado, a API Sheets v4 não usa métodos de acesso específicos de linhas. Em vez disso, os dados das células da planilha são acessados referenciando os intervalos específicos necessários usando a notação A1. Os intervalos podem ser blocos de células, linhas inteiras, colunas inteiras ou planilhas inteiras. A API também pode acessar conjuntos disjuntos de células.
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 de lista na entrada da planilha de interesse.
Para recuperar um feed baseado em lista, envie uma solicitação GET ao URL do feed de lista usando um cabeçalho de autorização adequado. 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. As células individuais são referenciadas pelos nomes fornecidos na linha de cabeçalho da planilha (obrigatória). 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 na ordem das linhas. A API Google Sheets v3 oferece parâmetros de consulta para mudar 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:lastnameA API Google Sheets v3 também permite filtrar linhas específicas usando uma consulta estruturada (referenciada por cabeçalhos de coluna):
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?sq=age>25%20and%20height<175API v4
Com a API Google Sheets v4, é possível recuperar linhas por intervalo usando os métodos spreadsheets.values.get ou spreadsheets.values.batchGet. Por exemplo, o comando a seguir retorna todas as linhas na "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 finais não são incluídas na resposta ao recuperar linhas, colunas ou planilhas 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 depois lê-los.
No momento, 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
É possível 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 da planilha e encontre o URL da postagem na entrada da planilha de interesse.
Para adicionar uma linha de dados, envie uma solicitação POST ao URL da postagem usando um cabeçalho de autorização adequado. 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>
As novas linhas são anexadas ao final da planilha especificada.
API v4
Com a API Sheets v4, é possível adicionar 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 permite anexar células com propriedades e formatação específicas usando as solicitações AppendCells em um spreadsheets.batchUpdate.
Editar uma linha com novos dados
As duas APIs permitem que os dados de 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 atual.
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 adequado. 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 Google 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 se referir apenas à primeira célula da linha. A API deduz as células a serem atualizadas com base nos valores fornecidos com a solicitação. Se você especificar um intervalo de várias células, os valores fornecidos precisarão se ajustar a esse intervalo. Caso contrário, a API vai retornar um erro.
O exemplo de solicitação e corpo de solicitação a seguir adiciona dados à quarta linha de "Sheet1":
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A4
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}Também é possível atualizar dados de linha usando o método spreadsheet.values.batchUpdate, que é mais eficiente se você estiver fazendo várias atualizações de linha ou célula.
Além disso, a API Google Sheets v4 também permite editar as propriedades e a formatação das células usando as solicitações UpdateCells ou RepeatCell em um spreadsheets.batchUpdate.
Excluir uma linha
As duas APIs aceitam a exclusão de linhas. Uma linha excluída é removida da planilha, e as linhas abaixo dela são movidas para cima.
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.
É 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 não vai excluir uma linha que foi alterada por outro cliente desde que você a recuperou, inclua um cabeçalho HTTP If-Match que contenha o valor ETag da linha original. Para determinar o valor da ETag da linha original, examine o atributo gd:etag do elemento de entrada.
Se você quiser excluir a linha, mesmo que outra pessoa a tenha atualizado desde que você a recuperou, use "If-Match: *" e não inclua a ETag. Nesse caso, não é necessário recuperar a linha antes de excluí-la.
API v4
A exclusão de linhas com a API Google Sheets v4 é processada 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 podem escolher remover apenas parte de uma linha ou coluna. Por exemplo, o comando a seguir remove a sexta linha de uma planilha com o ID especificado. Os índices de linha são baseados em zero, com startIndex inclusivo 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 usando o método spreadsheet.get.
Recuperar dados da célula
A API Google 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 definido por um conjunto de parâmetros de consulta, mas apenas como um único bloco. Intervalos desconexos precisam ser recuperados separadamente usando solicitações GET adicionais.
A API Google Sheets v4 pode recuperar qualquer conjunto de dados de células de uma planilha, incluindo vários intervalos desconexos. A API Google Sheets v3 só pode retornar o conteúdo da célula como valores de entrada (como seriam inseridos por um usuário em um teclado) e/ou as saídas de uma fórmula (se numérica). A API Google 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 da planilha e encontre o URL do feed de células na entrada da planilha de interesse.
Para recuperar um feed baseado em células, envie uma solicitação GET ao URL do feed de células usando um cabeçalho de autorização adequado. Exemplo:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
As células são referenciadas usando o número da linha e da coluna. Para buscar um único intervalo específico, use 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 pela linha 2:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
?min-row=2&min-col=4&max-col=4A API Google Sheets v3 retorna o inputValue das células recuperadas, ou seja, o valor que um usuário digitaria na interface do Google Sheets 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élula com 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 os dados da célula chamando um método spreadsheets.values.get ou spreadsheets.values.batchGet para o intervalo ou intervalos de interesse, respectivamente. Por exemplo, o comando a seguir retorna as células na coluna D de "Sheet2", começando pela linha 2, em ordem de coluna principal e retornando as fórmulas conforme foram 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 se você pretende recuperar vários intervalos de dados de células. Se você quiser acessar propriedades de células, como formatação, o método spreadsheet.get é obrigatório.
Editar uma célula
A API Google Sheets v3 permite editar o conteúdo das células emitindo um comando PUT para o feed de células com a entrada de célula modificada como o corpo da solicitação.
Em contraste, a API Sheets v4 oferece os métodos spreadsheets.values.update e spreadsheets.values.batchUpdate para mudar 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
comando a seguir 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
A edição de uma única célula na API Sheets v4 pode ser feita com o método
spreadsheets.values.update. Esse método requer um parâmetro de consulta ValueInputOption, que
especifica se os dados de entrada são tratados como se tivessem sido inseridos na
interface do usuário do Planilhas (USER_ENTERED) ou deixados sem análise e usados como estão (RAW). Por
exemplo, o comando a seguir 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 você estiver fazendo várias edições de células, use o método spreadsheets.values.batchUpdate para emitir todas em uma solicitação.
Editar várias células com uma solicitação em lote
As duas APIs oferecem meios de fazer mudanças no conteúdo de várias células com uma única solicitação (em lote). As células referidas por uma solicitação em lote não precisam estar em um intervalo contíguo.
Se uma ou mais edições de células no lote falharem, a API Google Sheets v3 permitirá que outras sejam concluídas. No entanto, a API Google Sheets v4 retorna um erro se alguma das atualizações em lote falhar e não aplica nenhuma delas nesse caso.
API v3
Para editar várias células, primeiro recupere um feed de células
da planilha. A entrada contém um URL de lote. Envie uma solicitação POST
para esse URL, junto com um corpo de solicitação que descreve as células que você
quer atualizar e o novo conteúdo delas. A solicitação e o corpo da solicitação POST 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 de maneira exclusiva a solicitação no lote.
O campo batch:operation precisa ser update para edições de células. gs:cell
identifica a célula pelo número da linha e da coluna e fornece os novos dados
para inserir nela. 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 Google Sheets v4 oferece edição em lote de valores de células usando o método spreadsheets.values.batchUpdate.
Para editar várias células, emita uma solicitação POST com as mudanças 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 o intervalo, todos os valores fornecidos serão gravados na planilha começando por essa célula como a coordenada superior esquerda. Se você especificar um intervalo de várias células, os valores fornecidos precisarão corresponder exatamente a esse intervalo. Caso contrário, a API vai retornar um erro.