Se você tem aplicativos baseados na API Google Sheets v3, pode 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 substancial de funcionalidades que não são possíveis na versão v3.
Nesta página, você encontra um mapeamento entre os antigos comandos da API Sheets v3 e as operações equivalentes deles na API Sheets v4. O mapeamento se concentra em grande parte na coleção spreadsheets.values, que fornece a funcionalidade direta de leitura e gravação de células. Outros aspectos, como a adição de páginas ou a atualização de propriedades da página, são tratados pela coleção spreadsheets. Observe que 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 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 é sinônimo do termo “sheets” usado pela API v4.
Geralmente, as APIs exigem que você especifique um ID da planilha em que você 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 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 seu feed de lista. Isso é representado nesta página pelo marcador rowId.
Autorizar solicitações
Quando o app é executado, ele solicita que os usuários concedam determinadas permissões. Os escopos especificados 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
https://www.googleapis.com/auth/spreadsheets
Qualquer um dos 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 propriedades de páginas de um usuário. Use escopos de planilhas em vez de escopos do Drive se o aplicativo não precisar de acesso geral ao Drive.
Visibilidade
Nas versões mais antigas da API, o termo visibilidade é usado para se referir à disponibilidade de uma determinada planilha.
API v3
A Sheets API v3 expressa visibilidade diretamente em seus pontos de extremidade. Uma planilha public foi "Publicado na Web" e, portanto, pode ser acessada pela API sem autorização, enquanto uma planilha private requer 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 planilhas. 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 que é retornado por uma determinada chamada de API: todos ou um subconjunto fixo definido na API. A API Sheets v4 não usa projeção; em vez disso, ela permite 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 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 planilha restringem a quantidade de dados retornados por meio do uso de um parâmetro de consulta fields.
Por exemplo, a consulta a seguir retorna apenas os títulos de todas as páginas em uma planilha específica:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title
Criar uma planilha
API v3
Com a API Sheets v3, não é possível criar novas planilhas. Em vez disso, o método Files.create da API Drive 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 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 comando a seguir cria uma nova planilha com 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 API Sheets v3 permite que um aplicativo recupere uma lista de todas as planilhas que o usuário autenticado pode acessar. O endpoint do feed de planilha é:
GET https://spreadsheets.google.com/feeds/spreadsheets/private/full
API v4
A Sheets API v4 não fornece essa operação específica. Recomendamos migrar seu app para usar o escopo drive.file em combinação com o Google Picker para selecionar 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'
Usar o método files.list da API Drive para listar todas as planilhas de um usuário requer um escopo restrito.
Recuperar metadados de planilhas
A Sheets API v3 fornece um feed para acessar os metadados da planilha contidos em uma determinada planilha (os dados da linha e da 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.
O método spreadsheets.get da API Sheets v4 fornece acesso a essas informações e muito mais.
API v3
O feed de planilhas pode ser acessado a partir desse 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 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 da página e outros metadados, muito mais do que a disponível com a API Sheets v3. Se você quiser ler apenas as propriedades da página, defina o parâmetro de consulta includeGridData como false para impedir a inclusão dos 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 das páginas 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
Ambas as 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 planilha:
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 planilhas fazendo uma solicitação AddSheet no método spreadsheets.batchUpdate. Como parte do corpo da solicitação, especifique as propriedades da nova página. 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 da planilha. 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, primeiro recupere o feed de planilhas e encontre a entrada 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 essas propriedades explicitamente. Se você quiser atualizar todas as propriedades, use fields:"*" como uma abreviação para listar todas. O exemplo a seguir especifica que as propriedades de título e tamanho da página precisam 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 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 uma determinada planilha.
API v3
Para excluir uma planilha, comece recuperando o feed de planilhas e depois 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 que a planilha seja 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 fornecidos pela API Planilhas v3 para acessar dados nas células de uma planilha (o outro é o feed de células). O feed de linhas visa oferecer suporte a operações de planilha comuns (leitura de linha por linha, anexação de linhas, classificação), 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 de feed e que cabeçalhos obrigatórios estão presentes na primeira linha de uma planilha.
Em contraste, 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 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 desconexos.
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 do feed de lista na entrada da planilha desejada.
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. As células individuais são referenciadas pelos nomes fornecidos na linha (obrigatório) do cabeçalho da página. Por exemplo, veja 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 na ordem das linhas. 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
Com a API Sheets v3, você também pode 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<175API 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 comando a seguir retorna todas as linhas em "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 na recuperação de 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 reversa é trivial. Basta processar a matriz values retornada na ordem inversa. A ordenação por coluna não é aceita para leituras, mas é possível classificar os dados na solicitação de planilha (usando uma solicitação SortRange) e depois fazer a leitura deles.
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
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 desejada.
Para adicionar uma linha de dados, envie uma solicitação POST para o 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 pelos cabeçalhos das colunas:
<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 página especificada.
API v4
Com a API Sheets v4, você pode anexar linhas usando o método spreadsheets.values.append. No exemplo a seguir, uma nova linha de dados é gravada 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"]]
}
Com a API Sheets v4, você também pode anexar células com propriedades e formatação específicas usando as solicitações AppendCells em uma spreadsheets.batchUpdate.
Editar uma linha com novos dados
Ambas as APIs permitem que os dados das linhas 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, você pode editar uma linha usando a notação A1 da linha que quer editar e emitindo uma solicitação spreadsheets.values.update para substituir essa linha. O intervalo especificado precisa se referir apenas à primeira célula na 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 caber nesse intervalo. Caso contrário, a API 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 os dados da linha com o método spreadsheet.values.batchUpdate. É mais eficiente usar esse método se você estiver fazendo várias atualizações de linha ou célula.
Com a API Sheets v4, você também pode editar as propriedades e formatar células usando as solicitações UpdateCells ou RepeatCell em uma 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 são empurradas uma 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.
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 da ETag da linha original. É possível determinar o valor da ETag da linha original examinando o atributo gd:etag do elemento de entrada.
Se 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 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 optar por remover apenas parte de uma linha ou coluna. O exemplo 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 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 com o método spreadsheet.get.
Recuperar dados da célula
A Sheets API 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 página ou um intervalo de células da página definido por um conjunto de parâmetros de consulta, mas somente como um único bloco. Os intervalos separados precisam ser recuperados separadamente usando outras solicitações GET.
Com a Sheets API v4, você pode recuperar qualquer conjunto de dados de células de uma planilha, incluindo vários intervalos desconexos. A API Sheets v3 só pode retornar conteúdos de células como valores de entrada (que seriam inseridos por um usuário com um teclado) e/ou as saídas de fórmulas (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 desejada.
Para recuperar um feed baseado em células, envie uma solicitação GET para o URL de 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 o número da linha e da coluna. É possível buscar um único intervalo específico 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 de 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 estrutura semelhante a:
<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 um ou mais intervalos de interesse, respectivamente. Por exemplo, o comando a seguir retorna as células da coluna D da "Planilha2", começando com a linha 2, na ordem da coluna principal, retornando fórmulas conforme elas são inseridas (as células vazias no final 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. Para acessar as propriedades da célula como a formatação, o método spreadsheet.get é necessário.
Editar uma célula
Com a API Sheets v3, você pode 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.
A API Sheets 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 ú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, em seguida, emita uma solicitação PUT para o URL de edição com a entrada atualizada da célula 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 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 Planilhas (USER_ENTERED) ou não analisados e considerados como estão (RAW). Por
exemplo, a célula D2 é atualizada 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 emiti-las em uma única 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 (lote). As células referenciadas por uma solicitação em lote não precisam estar em um intervalo contínuo.
Quando uma ou mais edições de células no lote falham, a API Sheets v3 permite que as outras tenham êxito. 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, além de um corpo 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 deve identificar exclusivamente 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 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
Com a API Sheets v4, você pode editar em lote os 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 o intervalo, todos os valores fornecidos são gravados na página começando com essa célula como coordenada no canto superior esquerdo. Se, em vez disso, você especificar um intervalo com várias células, os valores fornecidos precisarão se encaixar exatamente nesse intervalo. Caso contrário, a API vai retornar um erro.