Se hai già delle app basate sull'API Fogli Google v3, puoi eseguire la migrazione all'API Fogli Google v4. La versione v4 è basata su JSON, ha un'interfaccia più facile da usare e aggiunge una notevole quantità di funzionalità che non sono possibili nella versione v3.
Questa pagina fornisce una mappatura tra i comandi precedenti dell'API Fogli v3 e le relative operazioni equivalenti nell'API Fogli v4. La mappatura si concentra in gran parte sulla raccolta spreadsheets.values, che fornisce funzionalità dirette di lettura e scrittura delle celle. Altri aspetti, come l'aggiunta di fogli o l'aggiornamento delle proprietà dei fogli, sono gestiti dalla raccolta fogli di lavoro. Tieni presente che le strutture JSON dell'API v4 non sono compatibili con le versioni precedenti con le strutture XML utilizzate nella versione 3.
Per ulteriori informazioni sulle risorse disponibili nell'API Fogli v4, consulta la pagina di riferimento API.
Notazione e termini
L'API v3 fa riferimento ai fogli di un determinato foglio di lavoro con l'espressione "fogli di lavoro". Questo è sinonimo del termine "fogli" utilizzato dall'API v4.
Le API spesso richiedono di specificare un ID foglio di lavoro del foglio di lavoro su cui stai lavorando. Spesso richiedono anche l'ID del foglio da manipolare. Questi valori vengono visualizzati come parte dell'URL dell'endpoint API, come parametri di query o come parte del corpo di una richiesta. In questa pagina, i segnaposto spreadsheetId e sheetId fanno riferimento rispettivamente agli ID foglio di lavoro e foglio. Quando utilizzi i metodi descritti in questa pagina, sostituisci gli ID effettivi in queste posizioni.
L'API v3 assegna anche un ID alle righe recuperate tramite il feed elenco. Questo è rappresentato in questa pagina dal segnaposto rowId.
Autorizza richieste
Durante l'esecuzione, l'app chiede agli utenti di concedere determinate autorizzazioni; gli ambiti specificati nell'applicazione determinano le autorizzazioni richieste.
API v3
L'API Fogli v3 opera con un singolo ambito di autorizzazione:
https://spreadsheets.google.com/feeds
che è un alias di
https://www.googleapis.com/auth/spreadsheets
È possibile utilizzare entrambi i formati di ambito.
API v4
L'API Fogli v4 utilizza uno o più dei seguenti set di ambiti:
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
Utilizza gli ambiti di sola lettura se l'applicazione non deve apportare modifiche ai fogli o alle proprietà dei fogli di un utente. Utilizza gli ambiti per i fogli di lavoro anziché gli ambiti per Drive se l'applicazione non ha bisogno dell'accesso generale a Drive.
Visibilità
Nelle versioni precedenti dell'API, il termine visibilità viene utilizzato per indicare la disponibilità di un determinato foglio di lavoro.
API v3
L'API Fogli v3 esprime la visibilità direttamente nei propri endpoint. Un foglio di lavoro public è stato "Pubblicato sul web" e pertanto è accessibile dall'API senza autorizzazione, mentre un foglio di lavoro private richiede l'autenticazione. La visibilità viene specificata nell'endpoint dopo
l'ID del foglio di lavoro:
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
API v4
Nella nuova API Fogli v4, non è prevista una dichiarazione esplicita di visibilità. Le chiamate API vengono effettuate utilizzando gli ID foglio di lavoro. Se l'applicazione non dispone dell'autorizzazione per accedere al foglio di lavoro specificato, viene restituito un errore. In caso contrario, la chiamata continua.
Projection
Il termine proiezione viene utilizzato dall'API Fogli v3 per fare riferimento all'insieme di dati restituiti da una determinata chiamata API, tutti o un sottoinsieme fisso definito all'interno dell'API. L'API Fogli v4 non utilizza la proiezione, ma offre un maggiore controllo sui dati restituiti.
API v3
Esistono solo due possibili impostazioni di proiezione nell'API Fogli v3. full
la proiezione restituisce tutte le informazioni disponibili, mentre basic restituisce un sottoinsieme
di dati fisso e più piccolo (per i feed di fogli di lavoro, elenchi e celle).
Come la visibilità, la proiezione deve essere specificata nell'endpoint API
(dopo l'impostazione della visibilità):
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic
Il sottoinsieme più piccolo di dati fornito dalla proiezione basic è importante per rendere il codice più efficiente, ma non può essere personalizzato.
API v4
Sebbene l'API Fogli v4 possa restituire un set di dati completo, non definisce sottoinsiemi fissi analoghi all'impostazione di visibilità basic dell'API Fogli v3.
I metodi nella raccolta del foglio di lavoro limitano la quantità di dati restituiti tramite l'utilizzo di un parametro di query fields.
Ad esempio, la seguente query restituisce solo i titoli di tutti i fogli di un determinato foglio di lavoro:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title
Crea un foglio di lavoro
API v3
L'API Fogli v3 non fornisce un mezzo per creare nuovi fogli di lavoro;
al contrario, può essere utilizzato il metodo File.create dell'API Drive
per creare nuovi file di foglio di lavoro. Ciò richiede che l'applicazione dichiari l'ambito https://www.googleapis.com/auth/drive.
API v4
Il metodo File.create dell'API Drive può
essere utilizzato anche con l'API Fogli v4, ma richiede che l'applicazione fornisca
l'ambito https://www.googleapis.com/auth/drive.
In alternativa equivalente, l'API Fogli v4 offre il metodo spreadsheets.create, che può anche aggiungere facoltativamente fogli, impostare le proprietà del foglio e del foglio di lavoro e aggiungere intervalli denominati. Ad esempio, di seguito viene creato un nuovo foglio di lavoro a cui viene assegnato il nome "NewTitle":
POST https://sheets.googleapis.com/v4/spreadsheets
{
"properties": {"title": "NewTitle"}
}Elenca i fogli di lavoro per l'utente autenticato
API v3
Il feed dell'API Fogli v3 consente a un'applicazione di recuperare un elenco di tutti i fogli di lavoro accessibili dall'utente autenticato. L'endpoint del feed del foglio di lavoro è:
GET https://spreadsheets.google.com/feeds/spreadsheets/private/full
API v4
L'API Fogli v4 non fornisce questa operazione specifica. Ti consigliamo di eseguire la migrazione dell'app per utilizzare l'ambito drive.file in combinazione con il selettore di Google per la selezione dei fogli di lavoro.
Nei casi in cui è necessario elencare i fogli di lavoro, è possibile replicarli tramite il metodo File.list dell'API Drive, utilizzando una query mimeType:
GET https://www.googleapis.com/drive/v3/files
?q=mimeType='application/vnd.google-apps.spreadsheet'
L'utilizzo del metodo files.list dell'API Drive per elencare tutti i fogli di lavoro di un utente richiede un ambito limitato.
Recupera i metadati del foglio
L'API Fogli v3 fornisce un feed per accedere ai metadati del foglio contenuti all'interno di un determinato foglio di lavoro (accesso ai dati di righe e celle tramite un feed separato). I metadati includono informazioni quali titoli dei fogli e informazioni sulle dimensioni.
Il metodo spreadsheets.get dell'API Fogli v4 consente di accedere a queste informazioni e a molto altro.
API v3
Il feed del foglio di lavoro è accessibile da questo endpoint API (utilizzando un'intestazione di autorizzazione appropriata):
GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
La risposta a questa richiesta ha una struttura simile a questa, con i dati di ogni foglio contenuti in un elemento <entry> separato:
<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
Il metodo spreadsheets.get può essere utilizzato per acquisire le proprietà del foglio e altri metadati, molto più di quella disponibile utilizzando l'API Fogli v3. Se vuoi leggere solo le proprietà del foglio, imposta il parametro di query includeGridData su false per evitare di includere i dati delle celle del foglio di lavoro:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?includeGridData=false
La risposta Spreadsheet contiene un array di oggetti Sheet; i titoli dei fogli e le informazioni sulle dimensioni in particolare si trovano nell'elemento SheetProperties di questi oggetti. Ad esempio:
{
"spreadsheetId": spreadsheetId,
"sheets": [
{"properties": {
"sheetId": sheetId,
"title": "Sheet1",
"index": 0,
"gridProperties": {
"rowCount": 100,
"columnCount": 20,
"frozenRowCount": 1,
"frozenColumnCount": 0,
"hideGridlines": false
},
...
},
...
},
...
],
...
}Aggiungere un foglio a un foglio di lavoro
Entrambe le API consentono di aggiungere nuovi fogli a un foglio di lavoro esistente.
API v3
L'API Fogli v3 può aggiungere nuovi fogli di lavoro a un foglio di lavoro effettuando la
seguente richiesta POST (autenticata). Puoi specificare le dimensioni
del nuovo foglio:
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
Puoi aggiungere nuovi fogli effettuando una richiesta AddSheet nel metodo spreadsheets.batchUpdate. Come parte del corpo della richiesta, puoi specificare le proprietà del nuovo foglio. Tutte le proprietà sono facoltative. Fornire un titolo che viene utilizzato per un foglio esistente è un errore.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [{
"addSheet": {
"properties": {
"title": "Expenses",
"sheetType": "GRID",
"gridProperties": {
"rowCount": 50,
"columnCount": 10
}
}
}
}],
}Modificare il titolo e le dimensioni di un foglio
L'API Fogli v3 consente di aggiornare titoli e dimensioni dei fogli; la versione 4 dell'API Fogli consente questa operazione, ma può essere utilizzata anche per aggiornare altre proprietà dei fogli. Tieni presente che, riducendo le dimensioni di un foglio, i dati nelle celle ritagliate potrebbero essere eliminati senza avviso.
API v3
Per modificare il titolo o la dimensione di un foglio di lavoro, inizia recuperando il feed del foglio di lavoro e trovando la voce desiderata, che contiene un URL edit.
Aggiorna i metadati del foglio di lavoro e inviali come corpo di una richiesta PUT
all'URL di modifica. Ad esempio:
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
Per aggiornare dimensioni, titolo e altre proprietà del foglio, effettua una richiesta updateSheetProperties nel metodo spreadsheets.batchUpdate. Il corpo della richiesta POST deve contenere le proprietà da modificare e il parametro fields deve elencare esplicitamente queste proprietà (se vuoi aggiornare tutte le proprietà, utilizza fields:"*" come forma abbreviata per elencarle tutte). Ad esempio, quanto segue specifica che le proprietà del titolo e delle dimensioni del foglio devono essere aggiornate con l'ID specificato:
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)"
}
}
],
}
Per recuperare il valore sheetId di un foglio, utilizza il metodo spreadsheets.get.
Eliminare un foglio
Entrambe le API possono rimuovere i fogli da un determinato foglio di lavoro.
API v3
Per eliminare un foglio di lavoro, inizia recuperando il feed dei fogli di lavoro, quindi invia una richiesta DELETE all'URL edit della voce del foglio di lavoro di destinazione.
DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
API v4
Per eliminare un foglio, effettua una richiesta
DeleteSheet
nel metodo
spreadsheets.batchUpdate. Il corpo della richiesta POST deve contenere solo il valore sheetId per l'eliminazione del foglio. Ad esempio:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteSheet": {
"sheetId": sheetId
}
}
],
}
Per recuperare il valore sheetId di un singolo foglio, utilizza il metodo spreadsheets.get del foglio di lavoro.
Recuperare i dati delle righe
Il feed elenco righe è uno dei due metodi forniti dall'API Fogli v3 per accedere ai dati all'interno delle celle di un foglio di lavoro (l'altro è il feed di celle). Il feed righe è pensato per supportare operazioni comuni sui fogli di lavoro (lettura riga per riga, aggiunta di righe, ordinamento), ma fa alcune ipotesi che lo rendono inadatto per alcune attività. In particolare, il feed elenco presuppone che le righe vuote siano terminali del feed e che le intestazioni obbligatorie siano presenti nella prima riga di un foglio.
Al contrario, l'API Fogli versione 4 non utilizza metodi di accesso specifici per le righe. I dati delle celle del foglio sono invece accessibili facendo riferimento agli intervalli specifici richiesti utilizzando la notazione A1. Gli intervalli possono essere blocchi di celle, intere righe, intere colonne o interi fogli. L'API può anche accedere a insiemi di celle disgiunti.
API v3
Per determinare l'URL di un feed basato su elenco per un determinato foglio di lavoro, recupera il feed dei fogli di lavoro e trova l'URL del feed elenco nella voce del foglio di lavoro che ti interessa.
Per recuperare un feed basato su elenco, invia una richiesta GET all'URL del feed elenco utilizzando un'intestazione di autorizzazione appropriata. Ad esempio:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
La risposta a questa richiesta contiene, tra le altre cose, le voci corrispondenti a righe specifiche. I nomi forniti nella riga di intestazione (obbligatoria) del foglio fanno riferimento alle singole celle. Ad esempio, ecco una singola voce di riga:
<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>
Per impostazione predefinita, le righe restituite nel feed elenco vengono restituite in ordine di riga. L'API Fogli v3 fornisce i parametri di query per modificare l'ordine.
Inverti ordine:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full?reverse=true
Ordina in base a una colonna specifica:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?orderby=column:lastname
L'API Fogli v3 consente anche di filtrare righe specifiche tramite una query strutturata (cui si fa riferimento alle intestazioni di colonna):
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?sq=age>25%20and%20height<175API v4
Con l'API Fogli v4, le righe possono essere recuperate per intervallo utilizzando i metodi spreadsheets.values.get o spreadsheets.values.batchGet. Ad esempio, quanto segue restituisce tutte le righe in "Foglio1":
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1
La risposta a questa richiesta ha una struttura simile alla seguente:
{
"range": "Sheet1",
"majorDimension": "ROWS",
"values": [["Name", "Hours", "Items", "IPM"],
["Bingley", "10", "2", "0.0033"],
["Darcy", "14", "6", "0.0071"]]
}
Le celle vuote finali non vengono incluse nella risposta quando si recuperano righe, colonne o fogli interi.
L'API Fogli v4 non ha equivalenti per i parametri di query sull'ordine delle righe
forniti dall'API Fogli v3. L'inversione dell'ordine è banale; elabora semplicemente
l'array values restituito in ordine inverso. L'ordinamento per colonna non è
supportato per le letture, ma è possibile ordinare i dati nel foglio (utilizzando
una richiesta SortRange)
e poi leggerli.
L'API Fogli v4 al momento non ha un equivalente diretto per le query strutturate dell'API Fogli v3. Tuttavia, puoi recuperare i dati pertinenti e ordinarli secondo necessità nella tua applicazione.
Aggiungi una nuova riga di dati
Puoi aggiungere una nuova riga di dati a un foglio utilizzando una delle due API.
API v3
Per determinare l'URL di un feed basato su elenco per un determinato foglio di lavoro, recupera il feed dei fogli di lavoro e trova l'URL del post nella voce del foglio di lavoro che ti interessa.
Per aggiungere una riga di dati, invia una richiesta POST all'URL del post utilizzando un'intestazione di autorizzazione appropriata. Ad esempio:
POST https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
Il corpo della richiesta POST deve contenere una voce per i dati di riga da
aggiungere, con singole celle indicate come intestazioni di colonna:
<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>
Nuove righe vengono aggiunte alla fine del foglio specificato.
API v4
Con l'API Fogli v4, puoi aggiungere righe utilizzando il metodo spreadsheets.values.append. L'esempio seguente scrive una nuova riga di dati sotto l'ultima tabella in "Foglio1" di un foglio di lavoro.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}
Inoltre, la versione 4 dell'API Fogli consente anche di aggiungere celle con proprietà e formattazione specifiche utilizzando le richieste AppendCells in un spreadsheets.batchUpdate.
Modificare una riga con nuovi dati
Entrambe le API consentono di aggiornare i dati delle righe con nuovi valori.
API v3
Per modificare una riga di dati, esamina il feed elenco per individuare la voce relativa alla riga da aggiornare. Aggiorna i contenuti della voce in base alle tue esigenze. Assicurati che il valore ID nella voce utilizzata corrisponda esattamente all'ID della voce esistente.
Una volta aggiornata la voce, invia una richiesta PUT con la voce come
corpo della richiesta all'URL edit fornito nella voce di riga,
utilizzando un'intestazione di autorizzazione appropriata. Ad esempio:
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
Con l'API Fogli v4, puoi modificare una riga utilizzando la notazione A1 della riga da modificare e inviando una richiesta spreadsheets.values.update per sovrascriverla. L'intervallo specificato deve fare riferimento solo alla prima cella della riga; l'API deduce le celle da aggiornare in base ai valori forniti con la richiesta. Se invece specifichi un intervallo a più celle, i valori forniti devono rientrare in quell'intervallo; in caso contrario l'API restituisce un errore.
La seguente richiesta di esempio e il corpo della richiesta aggiungono dati alla quarta riga di "Sheet1":
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A4
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}
Puoi aggiornare i dati di riga anche dal metodo spreadsheet.values.batchUpdate ; utilizzare questo metodo è più efficiente se apporti più aggiornamenti di righe o celle.
Inoltre, l'API Fogli v4 consente anche di modificare le proprietà e la formattazione delle celle utilizzando le richieste UpdateCells o RepeatCell in un file spreadsheets.batchUpdate.
Elimina una riga
Entrambe le API supportano l'eliminazione delle righe. Una riga eliminata viene rimossa dal foglio di lavoro, mentre per le righe sottostanti viene eseguito il push di una riga.
API v3
Per eliminare una riga, recupera prima la riga da eliminare dal
feed elenco,
quindi invia una richiesta DELETE all'URL edit fornito nella voce della riga.
Si tratta dello stesso URL utilizzato per aggiornare la riga.
DELETE https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
Per assicurarti di non eliminare una riga modificata da un altro client da quando l'hai recuperata, includi un'intestazione If-Match HTTP che contenga il valore ETag della riga originale. Puoi determinare il valore ETag della riga originale esaminando l'attributo gd:etag dell'elemento voce.
Per eliminare la riga indipendentemente dal fatto che qualcun altro l'abbia aggiornata da quando l'hai recuperata, utilizza If-Match: * e non includere l'ETag. In questo caso, non è necessario recuperare la riga prima di eliminarla.
API v4
L'eliminazione di righe con l'API Fogli v4 viene gestita da una chiamata al metodo spreadsheet.batchUpdate utilizzando una richiesta DeleteDimension. Questa richiesta può essere utilizzata anche per rimuovere colonne, mentre gli sviluppatori possono scegliere di rimuovere solo parte di una riga o di una colonna. Ad esempio, di seguito rimuove la sesta riga di un foglio con l'ID specificato (gli indici di riga sono a base zero, con startIndex inclusi ed endIndex esclusivi):
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteDimension": {
"range": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 5,
"endIndex": 6
}
}
}
],
}
L'elemento sheetId di un foglio può essere recuperato utilizzando il metodo spreadsheet.get.
Recuperare i dati delle celle
L'API Fogli v3 fornisce un feed di celle per l'accesso di base a tutti i dati archiviati in un
foglio di lavoro. Per l'accesso in lettura, il feed di celle può fornire l'intero contenuto del foglio o un intervallo di celle del foglio definito da un set di parametri di query, ma solo come un singolo blocco: gli intervalli disgiunti devono essere recuperati separatamente utilizzando richieste GET aggiuntive.
L'API Fogli v4 può recuperare qualsiasi set di dati di celle da un foglio (compresi più intervalli disgiunti). L'API Fogli v3 può restituire i contenuti delle celle solo come valori di input (come verrebbero inseriti da un utente alla tastiera) e/o come output di formule (se numeriche); l'API Fogli v4 concede accesso completo a valori, formule, formattazione, link ipertestuali, convalida dei dati e altre proprietà.
API v3
Per determinare l'URL di un feed basato su celle per un determinato foglio di lavoro, esamina il feed dei fogli di lavoro e trova l'URL del feed di celle nella voce del foglio di lavoro che ti interessa.
Per recuperare un feed basato su celle, invia una richiesta GET all'URL del feed di celle, utilizzando un'intestazione di autorizzazione appropriata. Ad esempio:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
Alle celle viene fatto riferimento usando i numeri di riga e colonna. Il recupero di un singolo intervallo specifico
può essere eseguito utilizzando i parametri di query
max-row, min-row, max-col e min-col. Ad esempio, quanto segue recupera tutte le celle nella colonna 4 (D), a partire dalla riga 2:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
?min-row=2&min-col=4&max-col=4
L'API Fogli v3 restituisce l'inputValue delle celle recuperate, ovvero il valore che un utente digiterebbe altrimenti nell'interfaccia utente di Fogli Google per manipolare la cella. inputValue può essere un valore letterale
o una formula. L'API a volte restituisce anche un numericValue, ad esempio,
quando una formula restituisce un numero. Ad esempio, una risposta può includere voci di celle con una struttura simile alla seguente:
<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
Recupera i dati delle celle chiamando un metodo spreadsheets.values.get o spreadsheets.values.batchGet per l'intervallo o gli intervalli di interesse, rispettivamente. Ad esempio, di seguito vengono restituite le celle nella colonna D di "Foglio2", a partire dalla riga 2, in ordine colonna principale, e vengono restituite le formule così come sono state immesse (le celle vuote finali vengono omesse):
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet2!D2:D?majorDimension=COLUMNS&valueRenderOption=FORMULA
La struttura della risposta a questa richiesta è simile alla seguente:
{
"spreadsheetId": spreadsheetId,
"valueRanges": [
{"range": "Sheet2!D2:D",
"majorDimension": "COLUMNS",
"values": [["Widget", 234, "=FLOOR(C4/(B4*60),.0001)", "=D4\*1000"]]
}]
}
È più efficiente utilizzare spreadsheet.values.batchGet se intendi recuperare più intervalli di dati di celle. Se vuoi accedere alle proprietà delle celle come la formattazione, è obbligatorio il metodo spreadsheet.get.
Modifica una cella
L'API Fogli v3 ti consente di modificare il contenuto delle celle tramite l'invio di un comando PUT al feed di celle con la voce della cella modificata come corpo della richiesta.
L'API Fogli v4, invece, offre i metodi spreadsheets.values.update e spreadsheets.values.batchUpdate per modificare il contenuto delle celle.
API v3
Per modificare il contenuto di una singola cella, individua innanzitutto la voce della cella nel feed di celle.
La voce contiene un URL di modifica. Aggiorna la voce in modo che rifletta i contenuti che vuoi includere nella cella, quindi invia una richiesta PUT all'URL di modifica con la voce di cella aggiornata come corpo della richiesta. Ad esempio, di seguito aggiorna la cella D2 (R2C4) per contenere una formula 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
La modifica di una singola cella nell'API Fogli v4 può essere effettuata con il metodo
spreadsheets.values.update. Questo metodo richiede un parametro di query ValueInputOption, che
specifica se i dati di input vengono trattati come se fossero inseriti nell'interfaccia utente
di Fogli (USER_ENTERED) o se non vengono analizzati e presi così come sono (RAW). Ad esempio,
il seguente aggiorna la cella D2 con una formula:
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/D2?valueInputOption=USER_ENTERED
{"values": [["=SUM(A1:B6)"]]}
Se stai apportando modifiche a più celle, utilizza il metodo spreadsheets.values.batchUpdate per emetterle in un'unica richiesta.
Modificare più celle tramite una richiesta batch
Entrambe le API forniscono i mezzi per apportare modifiche al contenuto di più celle con una singola richiesta (batch). Le celle a cui si fa riferimento in una richiesta batch non devono essere necessariamente comprese in un intervallo contingente.
Nel caso in cui una o più modifiche delle celle nel batch non vadano a buon fine, l'API Fogli v3 consente agli altri di completare l'operazione. Tuttavia, l'API Fogli v4 restituisce un errore se gli aggiornamenti in batch non vanno a buon fine e non ne applica nessuno in questo caso.
API v3
Per modificare più celle, devi prima recuperare un feed di celle per il foglio di lavoro. La voce contiene un URL batch. Invia una richiesta POST
a questo URL, insieme al corpo della richiesta, che descrive le celle che
vuoi aggiornare e i nuovi contenuti. La richiesta POST e il corpo della richiesta
hanno una struttura simile alla seguente:
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>
Il campo batch:id deve identificare in modo univoco la richiesta all'interno del batch.
Per le modifiche delle celle, il campo batch:operation deve essere update. gs:cell
identifica la cella per numero di riga e colonna e fornisce i nuovi dati
da inserire al loro interno. id contiene l'URL completo della cella da aggiornare.
link deve avere un attributo href che contiene il percorso completo
all'ID della cella. Tutti questi campi sono obbligatori per ogni voce.
API v4
L'API Fogli v4 consente di modificare in gruppo i valori delle celle tramite il metodo spreadsheets.values.batchUpdate.
La modifica di più celle può essere effettuata inviando una richiesta POST con le
modifiche ai dati specificate nel corpo della richiesta. Ad esempio:
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 hai specificato una singola cella come intervallo, tutti i valori forniti vengono scritti nel foglio che inizia con quella cella come coordinata in alto a sinistra. Se invece specifichi un intervallo a più celle, i valori forniti devono rientrare esattamente in quell'intervallo; in caso contrario l'API restituisce un errore.