Se você tem apps baseados na API Google Sheets v3, é possível 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 estão presentes na versão v3.
Esta página fornece um mapeamento entre os comandos mais antigos da Sheets API v3 e as operações equivalentes na Sheets API v4. Esse mapeamento se concentra, principalmente, na coleção spreadsheets.values, que fornece recursos diretos de leitura e gravação de células. Outros aspectos, como a adição de páginas ou a atualização de propriedades de páginas, são realizados pela coleção planilhas. As estruturas JSON da API v4 não são compatíveis com a versão anterior das estruturas XML usadas na v3.
Para saber mais sobre os recursos disponíveis na Sheets v4 API, consulte a Referência da API.
Notação e termos
A API v3 chama as páginas de uma planilha específica de "folha de cálculo". Esse é um sinônimo do termo "folha" usado pela API v4.
As APIs geralmente exigem que você especifique um ID de planilha da planilha com que você está trabalhando. Elas também frequentemente exigem o ID da planilha sendo manipulada. Esses valores aparecem como parte do URL do ponto de extremidade da API, como parâmetros de consulta ou como parte do corpo de uma 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, insira os IDs reais nesses locais.
A API v3 também atribui um ID para linhas recuperadas usando o feed de lista. Isso é representado nesta página pelo marcador rowId.
Autorizar solicitações
Quando seu app é executado, ele solicita que os usuários concedam certas permissões. Os escopos que você especifica no aplicativo determinam quais permissões serão solicitadas.
API v3
A Sheets API 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 desses formatos de escopo pode ser usado.
API v4
A Sheets API 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 páginas ou nas propriedades de página de um usuário. Use escopos de planilha 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 planilha.
API v3
A Sheets API v3 expressa 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 depois do ID da planilha:
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
API v4
Na nova Sheets API 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 é realizada.
Projeção
O termo projeção é usado pela Sheets API v3 para se referir ao conjunto de dados que é retornado por determinada chamada de API, seja todo ele ou um subconjunto fixo definido na API. A Sheets API v4 não usa projeção. Em vez disso, ela permite que você tenha mais controle sobre quais dados são retornados.
API v3
Existem apenas duas configurações de projeção possíveis na Sheets API v3. A projeção full
retorna todas as informações disponíveis, enquanto basic retorna um
subconjunto fixo de dados menor (para feeds de páginas, 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 Sheets API v4 possa retornar um conjunto de dados completo, ela não define subconjuntos fixos análogos à configuração de visibilidade basic da Sheets API v3.
Os métodos na coleção planilha
restringem a quantidade de dados que eles retornam com o uso de
um parâmetro de consulta fields.
Por exemplo, a consulta a seguir retorna somente 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 Sheets API v3 não fornece uma maneira de criar novas planilhas.
Em vez disso, o método Drive API Files.create
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 Drive API também pode
ser usado com a Sheets API v4, mas exige que o aplicativo forneça
o escopo https://www.googleapis.com/auth/drive.
Como alternativa equivalente, a Sheets API v4 fornece um método spreadsheets.create, que também pode adicionar páginas, definir as propriedades da planilha e da página e adicionar intervalos nomeados. Por exemplo, o exemplo 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 para o usuário autenticado
API v3
O feed da Sheets API v3 permite que um aplicativo recupere uma lista de todas as planilhas acessíveis pelo usuário autenticado. O endpoint do feed de planilhas é:
GET https://spreadsheets.google.com/feeds/spreadsheets/private/full
API v4
A Sheets API v4 não fornece essa operação específica. Recomendamos que você migre seu app para usar o escopo drive.file em combinação com o Google Picker para seleção de planilhas.
Nos casos em que a listagem de planilhas é necessária, ela pode ser replicada
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'
O uso do método files.list da API Drive para listar todas as planilhas de um usuário exige um escopo restrito.
Extrair metadados da página
A Sheets API v3 fornece um feed para acessar os metadados de página 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 de páginas e informações de tamanho.
O método spreadsheets.get da Sheets API v4 oferece acesso a essas e muitas outras informações.
API v3
O feed de páginas pode ser acessado por esse ponto de extremidade da API (usando um cabeçalho de autorização apropriado):
GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
A resposta para 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 o que está disponível usando a Sheets API v3. Se você só
quer ler as propriedades da página, defina o parâmetro de consulta includeGridData
como false para impedir a inclusão de dados de 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 de página e as informações de tamanho 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
Ambas as APIs permitem que você adicione novas páginas a uma planilha existente.
API v3
A Sheets API v3 pode adicionar novas páginas a uma planilha fazendo a
solicitação POST (autenticada) a seguir. 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
Você pode adicionar novas páginas fazendo uma solicitação AddSheet no método spreadsheets.batchUpdate. Como parte do corpo da solicitação, você pode especificar as propriedades da nova página. Todas as propriedades são opcionais. É um erro fornecer um título usado para uma página 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 Sheets API v3 permite que você atualize os títulos e tamanhos de páginas. A Sheets API v4 também permite isso, mas também pode ser usada para atualizar outras propriedades da página. Observe que reduzir o tamanho de uma página pode fazer com que os dados nas células cortadas sejam excluídos sem aviso.
API v3
Para alterar o título ou o tamanho de uma planilha, comece recuperando o
feed de planilhas e
encontre a entrada de planilha desejada, que contém um URL edit.
Atualize os metadados da página 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 essas propriedades explicitamente.
Se você quiser atualizar todas as propriedades, use fields:"*" como um atalho para
listar todas elas. Por
exemplo, o exemplo a seguir especifica que as propriedades de título e tamanho
da página devem ser atualizadas para a página 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.
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 de planilhas e
envie uma solicitação DELETE no URL edit da entrada de 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 que a
página seja excluída. Exemplo:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteSheet": {
"sheetId": sheetId
}
}
],
}
Para extrair o sheetId de uma página individual, use o método spreadsheets.get da planilha.
Extrair dados de linha
O feed de linhas de lista é um dos dois métodos que a Sheets API 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 (ler linha por linha, anexar linhas, classificar), mas ele parte de pressupostos que o tornam inadequado para algumas tarefas. Especificamente, o feed de lista presume que linhas em branco são terminações de feed e que cabeçalhos obrigatórios estão presentes na primeira linha de uma página.
Em contraste, a Sheets API v4 não usa métodos de acesso específicos de linha. Em vez disso, os dados de células da página são acessados com uma referência aos intervalos específicos necessários usando 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 sequenciais.
API v3
Para determinar o URL de um feed baseado em lista de uma determinada página, extraia o feed de páginas e encontre o URL do feed de lista na entrada de página em questão.
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 apropriado. Exemplo:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
A resposta para essa solicitação contém, entre outras coisas, entradas que correspondem a linhas específicas. Células individuais são referenciadas pelos nomes fornecidos na linha (obrigatória) de cabeçalhos de página. Por exemplo, aqui está uma única entrada de linha:
<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 linha. A Sheets API 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
A Sheets API v3 também permite a filtragem de linhas específicas por meio de 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 Sheets API v4, é possível recuperar linhas por intervalo usando os métodos spreadsheets.values.get ou spreadsheets.values.batchGet. Por exemplo, o exemplo a seguir retorna todas as linhas da "Sheet1":
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1
A resposta para essa solicitação tem uma estrutura semelhante a esta:
{
"range": "Sheet1",
"majorDimension": "ROWS",
"values": [["Name", "Hours", "Items", "IPM"],
["Bingley", "10", "2", "0.0033"],
["Darcy", "14", "6", "0.0071"]]
}
Células vazias nas extremidades não são incluídas na resposta ao recuperar linhas, colunas ou páginas inteiras.
A Sheets API v4 não tem equivalentes para os parâmetros de consulta de ordem de linha
fornecidos pela Sheets API v3. A ordem inversa é trivial. Basta
processar a matriz values retornada na ordem inversa. A ordenação por coluna não é
permitida para leituras, mas é possível classificar os dados na página (usando
uma solicitação SortRange)
e ler esses dados.
No momento, a Sheets API v4 não tem um equivalente direto para as consultas estruturadas da Sheets API v3. No entanto, você pode recuperar os dados relevantes e classificá-los conforme a necessidade no seu aplicativo.
Adicionar uma nova linha de dados
Você pode adicionar uma nova linha de dados a uma planilha usando qualquer uma das duas APIs.
API v3
Para determinar o URL de um feed baseado em lista de uma determinada página, extraia o feed de páginas e encontre o URL da postagem na entrada de página em questão.
Para adicionar uma linha de dados, envie uma solicitação POST para o URL de publicação,
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
ser adicionada, 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 Sheets API v4, é possível anexar linhas usando o método spreadsheets.values.append. O exemplo a seguir grava uma nova linha de dados abaixo da última tabela em "Sheet1" de uma planilha.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}
Além disso, a Sheets API v4 também permite que você anexe células com propriedades e formatação específicas usando as solicitações AppendCells em um método spreadsheets.batchUpdate.
Editar uma linha com novos dados
Ambas as APIs permitem a atualização de dados 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 é exatamente igual ao ID da entrada existente.
Quando 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 Sheets API v4, você pode editar uma linha usando a notação A1 da linha que você quer editar e emitir uma solicitação spreadsheets.values.update para substituir essa linha. O intervalo especificado só precisa referenciar a primeira célula da linha. A API infere as células a serem atualizadas com base nos valores fornecidos com a solicitação. Em vez de especificar um intervalo com várias células, os valores fornecidos precisam estar dentro desse intervalo. Caso contrário, a API vai retornar um erro.
A solicitação e o corpo da solicitação do exemplo a seguir adicionam 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 dados de linha do método spreadsheet.values.batchUpdate. É mais eficiente usar esse método se você está fazendo várias atualizações de linha ou célula.
Além disso, a Sheets API v4 também permite que você atualize as propriedades e a formatação de células usando as solicitações UpdateCells ou RepeatCell em um spreadsheets.batchUpdate.
Excluir uma linha
Ambas as APIs permitem a exclusão de linhas. Uma linha excluída é removida da planilha, e as linhas abaixo dela sobem uma linha.
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 quiser garantir que você não exclua uma linha que tenha sido alterada por outro cliente desde que você a recuperou, inclua um cabeçalho HTTP If-Match que contenha o valor ETag da linha original. Você pode determinar o valor ETag da linha original examinando o atributo gd:etag do elemento de entrada.
Se quiser excluir a linha independentemente de alguém tê-la atualizado desde a recuperação, use If-Match: * e não inclua o ETag. (Nesse caso, não é preciso recuperar a linha antes de excluí-la.)
API v4
A exclusão de linhas com a Sheets API 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 optar por remover apenas parte de uma linha ou coluna. Por exemplo, o seguinte remove a 6ª linha de uma página com o ID fornecido (os índices de linha são baseados em zero, com startIndex incluído e endIndex excluído):
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteDimension": {
"range": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 5,
"endIndex": 6
}
}
}
],
}
O sheetId de uma página pode ser recuperado usando o método spreadsheet.get.
Extrair dados de células
A Sheets API v3 fornece um feed de célula para acesso básico a todos os dados armazenados em uma
planilha. Para acesso de leitura, o feed de células pode fornecer o conteúdo
inteiro da página ou um intervalo das células da página definido por um conjunto de parâmetros de consulta,
mas apenas como um único bloco. Os intervalos não sequenciais precisam ser recuperados
separadamente usando solicitações GET adicionais.
A Sheets API v4 pode recuperar qualquer conjunto de dados de célula de uma página (incluindo vários intervalos não sequenciais). A Sheets API v3 só pode retornar conteúdo de células como valores de entrada (como eles seriam inseridos por um usuário com um teclado) e/ou saídas de fórmula (se forem numéricas); a Sheets API 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 de planilha em questão.
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 apropriado. Exemplo:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
As células são referenciadas usando números de linha e coluna. É possível recuperar um único intervalo
específico usando os parâmetros de consulta max-row, min-row, max-col e min-col. Por exemplo, o exemplo a seguir recupera todas as células da 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 Sheets API v3 retorna o inputValue das células recuperadas, ou seja, o
valor que um usuário digitaria na interface do usuário das
Planilhas Google para manipular a célula. O inputValue pode ser um valor literal
ou uma fórmula. A API também pode retornar 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
Extraia dados de células chamando um método spreadsheets.values.get ou spreadsheets.values.batchGet para o intervalo ou os intervalos em questão, respectivamente. Por exemplo, o seguinte retorna as células da coluna D da "Sheet2", começando pela linha 2, em ordem de coluna principal e retornando fórmulas conforme inseridas (células vazias nas extremidades são omitidas):
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet2!D2:D?majorDimension=COLUMNS&valueRenderOption=FORMULA
A resposta para 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 a formatação, o método spreadsheet.get é necessário.
Editar uma célula
A Sheets API v3 permite que você edite o conteúdo de células emitindo um comando PUT para
o feed de células com a entrada de célula modificada como corpo da solicitação.
A Sheets API v4, por outro lado, fornece os métodos spreadsheets.values.update e spreadsheets.values.batchUpdate para alterar o conteúdo de células.
API v3
Para editar o conteúdo de uma só célula, encontre a entrada dessa célula no
feed de células.
Ela 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
exemplo 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
Na Sheets API v4, é possível editar uma só célula com o método
spreadsheets.values.update. Esse método exige um parâmetro de consulta ValueInputOption, que
especifica se os dados de entrada são tratados como se tivessem sido inseridos na
interface do app Planilhas (USER_ENTERED) ou se foram deixados não analisados e utilizados no estado em que se encontram (RAW). Por
exemplo, o seguinte 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élula, use o método spreadsheets.values.batchUpdate para emiti-las em uma solicitação.
Editar várias células com uma 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 (de lote). As células referenciadas por uma solicitação de lote não precisam estar em um intervalo contínuo.
Caso uma ou mais das edições de célula do lote falhe, a Sheets API v3 permite que as demais sejam realizadas com sucesso. No entanto, a Sheets API v4 retorna um erro se qualquer uma das atualizações em lote falhar e não aplica nenhuma delas.
API v3
Para editar várias células, primeiro extraia um feed de células
para a página. A entrada contém um URL de lote. Envie uma solicitação POST
para esse URL, juntamente com um corpo de solicitação que descreva as células que você
quer atualizar e o novo conteúdo. 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 de forma exclusiva a solicitação dentro do 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
a serem inseridos nela. id contém o URL completo da célula a ser atualizada.
link precisa ter um atributo href que contenha o caminho completo do
ID da célula. Todos esses campos são obrigatórios para cada entrada.
API v4
A Sheets API v4 permite a edição em lote de valores de células com o método spreadsheets.values.batchUpdate.
É possível editar várias células emitindo 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 só célula como intervalo, todos os valores fornecidos são gravados na página a partir dessa célula como coordenada de canto superior esquerdo. Em vez de especificar um intervalo com várias células, os valores fornecidos devem estar dentro desse intervalo de forma exata; caso contrário, a API retornará um erro.