Se você tiver apps baseados na API Google Sheets v3, poderá migrar para a API Google Sheets v4. A versão v4 é baseada em JSON e tem uma interface interface de usuário e adiciona uma quantidade substancial de funcionalidade que não é possível na versão v3.
Esta página fornece um mapeamento entre os antigos comandos da Sheets API v3 e seus operações equivalentes na API Sheets v4. O mapeamento se concentra em grande parte spreadsheets.values coleta, que oferece a funcionalidade direta de leitura e gravação de células. Outros aspectos, como adição de páginas ou atualização de propriedades da página, são tratados pelo a coleção planilhas. Observe que as estruturas JSON da API v4 não são compatíveis com a versão 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". É sinônimo do termo "planilhas" usadas pela API v4.
As APIs geralmente exigem que você especifique um ID de planilha da planilha com a qual você está trabalhando. Muitas vezes, elas também exigem o ID planilha sendo manipulada. Esses valores aparecem como parte do endpoint da API URL, como parâmetros de consulta ou como parte do corpo de uma solicitação. Nesta página, marcadores de posição spreadsheetId e sheetId referem-se 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 a feed de lista Isso é representado nesta página pelo marcador rowId.
Autorizar solicitações
Quando o app é executado, ele pede que os usuários concedam determinadas permissões. os escopos que especificado no aplicativo a determinar as permissões 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 nos 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
Em 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. Um public
planilha é "Publicado na Web" e, portanto, pode ser acessado
sem autorização, enquanto uma planilha private exige
autenticação. A visibilidade é especificada no endpoint
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, será retornado um erro. Caso contrário a chamada vai prosseguir.
Projeção
O termo projeção é usado pela API Sheets v3 para se referir ao conjunto de dados. retornados por uma determinada chamada de API, tudo ou um subconjunto fixo definidos na API. A Sheets API v4 não usa projeção; em vez disso, oferece mais controle sobre quais dados são retornados.
API v3
Existem apenas duas configurações de projeção possíveis na Sheets API v3. full
projeção retorna todas as informações disponíveis, enquanto basic retorna uma
subconjunto fixo de dados menor e fixo (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 análogos à configuração de visibilidade basic na API Sheets v3.
Métodos na planilha
coleta restringem a quantidade de dados que retornam com o uso de
um parâmetro de consulta fields.
Por exemplo, a consulta a seguir retorna apenas os títulos de todas páginas em 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;
a API Drive Files.create
pode ser usado para criar novos arquivos de planilha. Isso exige que
aplicativo para declarar o escopo https://www.googleapis.com/auth/drive.
API v4
O método Files.create da API Drive pode
também pode ser usado com a API Sheets v4, mas exige que o aplicativo forneça
escopo https://www.googleapis.com/auth/drive.
Como alternativa equivalente, a API Sheets v4 fornece uma spreadsheets.create , que também pode adicionar páginas, definir a planilha e e adicionar intervalos nomeados. O exemplo a seguir cria uma nova planilha e dará 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 todos os planilhas acessíveis pelo usuário autenticado. O feed da planilha endpoint é:
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 aplicativo para usar o escopo drive.file em combinação com o Seletor do Google para seleção de planilha.
Nos casos em que a listagem das 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 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 planilhas e informações de tamanho.
A API Sheets v4 spreadsheets.get 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 uma 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 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 comando spreadsheets.get
pode ser usado para adquirir propriedades de páginas e outros metadados, muito
mais do que a API Sheets v3. Se você só
Se quiser ler as propriedades da planilha, defina a consulta includeGridData
como false para evitar a inclusão dos dados de célula da planilha:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?includeGridData=false
O Spreadsheet
resposta contém uma matriz de Sheet
objetos os títulos das planilhas e as informações de tamanho especificamente podem ser encontradas
no SheetProperties
elemento 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 planilhas a uma planilha tornando o
seguinte (autenticada) POST. É possível especificar o tamanho
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 criando uma AddSheet solicitação em spreadsheets.batchUpdate . Como parte do corpo da solicitação, é possível especificar as propriedades da planilha para a nova planilha; todas as propriedades são opcionais. É um erro informar título que é 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
}
}
}
}],
}Alterar o título e o tamanho de uma página
Com a Sheets API v3, você pode atualizar os títulos e o tamanho das páginas, a API Sheets v4 permite isso, mas também pode ser usado 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ída sem aviso prévio.
API v3
Para alterar o título ou o tamanho de uma planilha, comece recuperando o
feed de planilhas e
encontrar a entrada da planilha desejada, que contém um URL edit.
Atualizar os metadados da planilha e enviá-los como o corpo de uma solicitação PUT
ao 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
updateSheetProperties
na solicitação
spreadsheets.batchUpdate
. O corpo da solicitação POST precisa conter as propriedades a serem
mudou, e o parâmetro fields precisa listar explicitamente essas propriedades
Se você quiser atualizar todas as propriedades, use fields:"*" como uma abreviação de
listando todos). Para
exemplo, o seguinte especifica que o título e o tamanho da página
devem ser atualizadas na 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 a planilha método spreadsheets.get.
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, então
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
DeleteSheet
na solicitação
spreadsheets.batchUpdate
. O corpo da solicitação POST precisa conter apenas o sheetId para o
planilha a ser excluída. Exemplo:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteSheet": {
"sheetId": sheetId
}
}
],
}
Para recuperar o sheetId de uma página individual, use o planilha spreadsheets.get .
Recuperar dados da linha
O feed de linhas de lista é um dos dois métodos que a API Sheets v3 fornece para acessar os dados nas células de uma planilha (o outro é o feed de células). A O feed de linhas foi criado para dar suporte a operações de planilha comuns (ler linha por linha, anexação de linhas, classificação), mas faz certas suposições que a tornam inadequada para algumas tarefas. Especificamente, o feed de lista presume que as linhas em branco são e que os cabeçalhos obrigatórios estão presentes na primeira linha de um folha
Por outro lado, a Sheets API v4 não usa métodos de acesso que são são específicos de cada linha. Em vez disso, os dados de células da planilha são acessados com referência à necessários usando a notação A1. A 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 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 que correspondem a linhas específicas. Células individuais são referenciadas por os nomes fornecidos na linha (obrigatório) do cabeçalho da página. Por exemplo, aqui é 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 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 (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 Sheets API v4, as linhas podem ser recuperadas por intervalo usando o spreadsheets.values.get ou spreadsheets.values.batchGet métodos. 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 dados inteiros linhas, colunas ou páginas.
A Sheets API v4 não tem equivalentes para a consulta de ordem de linha.
parâmetros fornecidos pela API Sheets v3. A ordem reversa é trivial; simplesmente
processar a matriz values retornada na ordem inversa. A ordenação por coluna não é
suportado para leituras, mas é possível classificar os dados na planilha (usando o
um SortRange)
e depois lê-lo.
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 em seu 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 feed de planilhas e encontre o URL da postagem na entrada da planilha de interesse.
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 que serão
adicionar, 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 página especificada.
API v4
Com a Sheets API v4, você pode anexar linhas usando o 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 requisitos e formatação usando as propriedades AppendCells solicitações em um 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 deseja atualizar. Atualize o conteúdo do conforme necessário. Verifique se o valor do ID na entrada que você usa exatamente corresponde 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 Sheets API v4, você pode editar uma linha usando o Notação A1 da linha que você quer editar e emitir uma spreadsheets.values.update para substituir a linha. O intervalo especificado só precisa se referir ao primeira célula da linha; a API infere as células a serem atualizadas com base no valores fornecidos com a solicitação. Se, em vez disso, você especificar um intervalo com várias células, os valores fornecidos devem estar dentro desse intervalo; Caso contrário, a API retornará uma erro.
A solicitação e o corpo da solicitação de 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"]]
}
Você também pode atualizar os dados das linhas do spreadsheet.values.batchUpdate método é mais eficiente usar esse método se você estiver fazendo várias atualizações de linha ou célula.
Além disso, a Sheets API v4 também permite que você edite as propriedades de células e a formatação de células usando o UpdateCells ou RepeatCell solicitações 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 são empurradas uma para cima.
API v3
Para excluir uma linha, primeiro recupere a linha a ser excluída do
feed de lista,
Em seguida, envie uma solicitação DELETE ao URL edit fornecido na entrada da linha.
Esse é o mesmo URL usado para atualizar a linha.
DELETE https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
Se você quiser ter certeza de que não excluirá uma linha que tenha sido alterada por outro cliente desde que você a recuperou, inclua um cabeçalho HTTP if-Match que contém o valor da ETag da linha original. Você pode determinar o original ETag da linha de comando examinando o atributo gd:etag do elemento de entrada.
Se você quiser excluir a linha, mesmo que outra pessoa não 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 Sheets API v4 é processada por uma spreadsheet.batchUpdate chamada de método, usando um parâmetro DeleteDimension solicitação. Essa solicitação também pode ser usada para remover colunas, e os desenvolvedores e optar por remover apenas parte de uma linha ou coluna. Por exemplo, o seguinte 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 usando 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 um
planilha. Para acesso de leitura, o feed de células pode fornecer a planilha inteira
conteúdo ou um intervalo de células da página definido por um conjunto de parâmetros de consulta;
mas apenas como um único bloco. Intervalos separados devem ser recuperados
separadamente usando outras solicitações GET.
A Sheets API v4 pode recuperar qualquer conjunto de dados de célula de uma planilha (incluindo vários intervalos separados). A API Sheets v3 só pode retornar conteúdos de células como valores de entrada (que seriam inseridos por um usuário em um teclado) e/ou as saídas de fórmula (se numérico); a API Sheets v4 dá acesso total aos 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 de interesse.
Para recuperar um feed baseado em células, envie uma solicitação GET para o URL do feed de células,
usando um cabeçalho de autorização apropriado. Exemplo:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
As células são referenciadas usando o número da linha e da coluna. A busca de uma instância específica
de destino pode ser feito usando max-row, min-row, max-col e min-col
parâmetros de consulta. 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 no arquivo do Planilhas Google
interface 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 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 os dados da célula chamando um spreadsheets.values.get ou spreadsheets.values.batchGet para os intervalos de interesse, respectivamente. Por exemplo, o seguinte retorna as células na coluna D da "Sheet2", começando pela linha 2, na ordem da coluna principal e retornando as fórmulas conforme foram inseridas as células são omitidas):
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet2!D2:D?majorDimension=COLUMNS&valueRenderOption=FORMULA
A resposta a essa solicitação tem uma estrutura semelhante a:
{
"spreadsheetId": spreadsheetId,
"valueRanges": [
{"range": "Sheet2!D2:D",
"majorDimension": "COLUMNS",
"values": [["Widget", 234, "=FLOOR(C4/(B4*60),.0001)", "=D4\*1000"]]
}]
}
É mais eficiente usar spreadsheet.values.batchGet caso você pretenda recuperar vários intervalos de dados de células. Se você quiser acessar propriedades da célula como formatação, spreadsheet.get é obrigató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 o corpo da solicitação.
A Sheets API v4, por outro lado, oferece spreadsheets.values.update e spreadsheets.values.batchUpdate métodos para alterar o conteúdo da célula.
API v3
Para editar o conteúdo de uma só célula, encontre a entrada da célula 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 de célula atualizada como o corpo da solicitação. Por exemplo, o
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 Sheets API v4 pode ser feita com a
spreadsheets.values.update
. Esse método exige um parâmetro de consulta ValueInputOption, que
especifica se os dados de entrada devem ser tratados como se tivessem sido inseridos no
Interface das Planilhas (USER_ENTERED) ou não analisada e tomada como está (RAW). Para
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 spreadsheets.values.batchUpdate para as emitir em uma única solicitação.
Editar várias células por solicitação em lote
Ambas as APIs fornecem meios de alterar o conteúdo de várias células com uma única solicitação (em lote). As células referenciadas por uma solicitação em lote sã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 retorna um erro se alguma das atualizações em lote falhar e não aplica nenhuma delas.
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. Enviar POST
para esse URL, junto com um corpo de solicitação que descreva as células às quais você
deseja atualizar e ao novo conteúdo da célula. 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
para inserir ali. 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 Sheets API v4 fornece edição em lote de valores de células por meio da spreadsheets.values.batchUpdate .
A edição de várias células pode ser feita emitindo uma solicitação POST com o
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 intervalo, todos os valores fornecidos serão escrito na planilha começando com essa célula como coordenada de canto superior esquerdo. Se, em vez disso, você especificar um intervalo com várias células, os valores fornecidos deverão caber exatamente esse intervalo, Caso contrário, a API retornará um erro.