Se disponi di app esistenti 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à di lettura e scrittura diretta delle celle. Altri aspetti, come l'aggiunta di fogli o l'aggiornamento delle proprietà del foglio, sono gestiti dalla raccolta fogli di lavoro. Tieni presente che le strutture JSON dell'API v4 non sono compatibili con le versioni precedenti delle strutture XML utilizzate nella versione v3.
Per ulteriori informazioni sulle risorse disponibili nell'API Fogli v4, consulta la documentazione di riferimento per le API.
Notazione e termini
L'API v3 fa riferimento ai fogli all'interno di un determinato foglio di lavoro come "fogli di lavoro". Questo è sinonimo del termine "fogli" utilizzato dall'API v4.
Le API spesso richiedono di specificare un ID del foglio di lavoro su cui stai lavorando. Spesso richiedono anche l'ID del foglio manipolato. 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 del foglio di lavoro e del 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 relativo feed elenco; questo valore è rappresentato in questa pagina dal segnaposto rowId.
Autorizza richieste
Durante l'esecuzione, l'app chiede agli utenti di concedere determinate autorizzazioni; gli ambiti che specifichi nell'applicazione determinano quali autorizzazioni richiede.
API v3
L'API Fogli v3 opera con un singolo ambito di autorizzazione:
https://spreadsheets.google.com/feeds
che è un alias per
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 insiemi 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 ambiti di sola lettura se l'applicazione non ha bisogno di apportare modifiche ai fogli o alle proprietà del foglio di un utente. Usa gli ambiti dei fogli di lavoro anziché quelli di Drive se l'applicazione non ha bisogno dell'accesso generale a Drive.
Visibilità
Nelle versioni precedenti dell'API, il termine visibilità viene utilizzato per fare riferimento alla disponibilità di un determinato foglio di lavoro.
API v3
L'API Fogli v3 esprime visibilità direttamente nei suoi 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à è 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 esiste una dichiarazione esplicita di visibilità. Le chiamate API vengono effettuate utilizzando gli ID dei fogli 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 procede.
Projection
Il termine proiezione viene utilizzato dall'API Fogli v3 per fare riferimento al set di dati restituito da una determinata chiamata API, tutti o un sottoinsieme fisso definito all'interno dell'API. L'API Fogli v4 non utilizza la proiezione, ma consente un maggiore controllo sui dati restituiti.
API v3
Esistono solo due impostazioni di proiezione possibili nell'API Fogli v3. La proiezione full restituisce tutte le informazioni disponibili, mentre basic restituisce un sottoinsieme di dati più piccolo e fisso (per i feed di fogli di lavoro, elenchi e celle).
Come per la visibilità, la proiezione deve essere specificata nell'endpoint API (dopo l'impostazione di visibilità):
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic
Il sottoinsieme più piccolo di dati fornito dalla proiezione basic è utile
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 foglio di lavoro limitano la quantità di dati restituiti tramite l'uso 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 offre 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 fogli 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.
Come alternativa equivalente, l'API Fogli v4 fornisce un metodo spreadsheets.create, che può anche aggiungere facoltativamente fogli, impostare le proprietà del foglio di lavoro e del foglio e aggiungere intervalli denominati. Ad esempio, l'esempio seguente crea un nuovo foglio di lavoro e gli assegna il nome "NewTitle":
POST https://sheets.googleapis.com/v4/spreadsheets
{
"properties": {"title": "NewTitle"}
}Elenca fogli di lavoro per l'utente autenticato
API v3
Il feed v3 dell'API Fogli 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 in modo da utilizzare l'ambito drive.file in combinazione con il selettore Google per la selezione dei fogli di lavoro.
Nei casi in cui è necessario elencare i fogli di lavoro, puoi replicarlo tramite il metodo File dell'API Drive Files.list, 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 in un determinato foglio di lavoro (i dati di righe e celle sono accessibili tramite un feed separato). I metadati includono informazioni quali titoli dei fogli e informazioni sulle dimensioni.
Il metodo spreadsheets.get dell'API Fogli fornisce l'accesso 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 <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 quanto disponibile utilizzando l'API Fogli v3. Se vuoi leggere solo le proprietà del foglio, imposta il parametro di query includeGridData su false per impedire l'inclusione dei 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 del foglio e le informazioni specifiche sulle dimensioni si trovano all'interno dell'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 con il metodo spreadsheets.batchUpdate. Come parte del corpo della richiesta, puoi specificare le proprietà del foglio per il nuovo foglio. Tutte le proprietà sono facoltative. È un errore fornire un titolo utilizzato per un foglio esistente.
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; l'API Fogli v4 consente anche questo, 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 del foglio di lavoro 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 la dimensione, il titolo e altre proprietà del foglio, effettua una richiesta
updateSheetProperties
con il metodo
spreadsheets.batchUpdate. Il corpo della richiesta POST deve contenere le proprietà da
modificare e il parametro fields deve elencarle esplicitamente
(se vuoi aggiornare tutte le proprietà, usa fields:"*" come scorciatoia per elencarle tutte). Ad esempio, quanto segue specifica che le proprietà di titolo e dimensione del foglio devono essere aggiornate per il foglio 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 fogli da un determinato foglio di lavoro.
API v3
Per eliminare un foglio di lavoro, recupera prima il feed del foglio di lavoro, quindi invia una richiesta DELETE all'URL edit della voce del foglio di lavoro target.
DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
API v4
Per eliminare un foglio, crea una richiesta
DeleteSheet
con il metodo
spreadsheets.batchUpdate. Il corpo della richiesta POST deve contenere solo il valore sheetId per il foglio da eliminare. 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.
Recupera i dati delle righe
Il feed di righe dell'elenco è 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 di righe è pensato per supportare le operazioni più comuni dei 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 terminazioni del feed e che siano presenti intestazioni obbligatorie nella prima riga di un foglio.
Al contrario, l'API Fogli v4 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 separate.
API v3
Per determinare l'URL di un feed basato su elenchi per un determinato foglio di lavoro, recupera il feed del foglio di lavoro e trova l'URL del feed elenco nella voce del foglio di lavoro che ti interessa.
Per recuperare un feed basato su elenchi, 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, voci che corrispondono a righe specifiche. Le singole celle fanno riferimento ai nomi forniti nella riga di intestazione del foglio (obbligatoria). Ad esempio, di seguito è riportata una voce singola 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 questo ordine.
Ordine inverso:
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 (a cui si fa riferimento nelle 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 alla fine non sono incluse nella risposta quando si recuperano intere righe, colonne o fogli.
L'API Fogli v4 non ha equivalenti per i parametri di query dell'ordine delle righe forniti dall'API Fogli v3. L'ordine inverso è banale; è sufficiente elaborare l'array values restituito in ordine inverso. L'opzione Ordina per colonna non è supportata per le letture, ma è possibile ordinare i dati nel foglio (utilizzando una richiesta SortRange) e leggerli.
Al momento, l'API Fogli v4 non dispone di un equivalente diretto per le query strutturate dell'API Fogli v3. Tuttavia, puoi recuperare i dati pertinenti e ordinarli a seconda delle esigenze nella tua applicazione.
Aggiungi una nuova riga di dati
Puoi aggiungere una nuova riga di dati a un foglio utilizzando entrambe le API.
API v3
Per determinare l'URL di un feed basato su elenchi per un determinato foglio di lavoro, recupera il feed del foglio 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 che consente di aggiungere i dati della riga, con le singole celle a cui fanno riferimento le 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, l'API Fogli v4 consente 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 che vuoi aggiornare. Aggiorna i contenuti della voce in base alle esigenze. Assicurati che il valore ID nella voce che utilizzi corrisponda esattamente all'ID della voce esistente.
Dopo aver aggiornato la voce, invia una richiesta PUT con la voce come
corpo della richiesta all'URL edit fornito nella voce di riga in questione,
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 questo intervallo. In caso contrario, l'API restituisce un errore.
Il seguente corpo della richiesta e dell'esempio di esempio aggiunge dati alla quarta riga di "Foglio1":
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A4
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}
Puoi anche aggiornare i dati delle righe con il metodo spreadsheet.values.batchUpdate. Questo metodo è più efficiente se esegui aggiornamenti di più righe o celle.
Inoltre, l'API Fogli v4 consente anche di modificare le proprietà delle celle e la loro formattazione utilizzando le richieste UpdateCells o RepeatCell in un spreadsheets.batchUpdate.
Elimina una riga
Entrambe le API supportano l'eliminazione di righe. Una riga eliminata viene rimossa dal foglio di lavoro e le righe sottostanti vengono sottoposte a push up.
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
Se vuoi assicurarti di non eliminare una riga che è stata modificata da un altro client dopo averla recuperata, includi un'intestazione If-Match HTTP contenente il valore ETag della riga originale. Puoi determinare il valore ETag della riga originale esaminando l'attributo gd:etag dell'elemento di voce.
Se vuoi 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 del metodo spreadsheet.batchUpdate, utilizzando una richiesta DeleteDimension. Questa richiesta può essere utilizzata anche per rimuovere colonne e gli sviluppatori possono scegliere di rimuovere solo parte di una riga o di una colonna. Ad esempio, quanto riportato di seguito rimuove la sesta riga di un foglio con l'ID specificato (gli indici delle righe sono in base a zero, con startIndex inclusi ed endIndex esclusi):
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteDimension": {
"range": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 5,
"endIndex": 6
}
}
}
],
}
Il valore sheetId di un foglio può essere recuperato con il metodo spreadsheet.get.
Recupera i dati della cella
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 insieme di parametri di query, ma solo come un singolo blocco: gli intervalli separati devono essere recuperati separatamente utilizzando richieste GET aggiuntive.
L'API Fogli v4 può recuperare qualsiasi set di dati di celle da un foglio, inclusi più intervalli disgiunti. L'API Fogli v3 può restituire i contenuti delle celle solo come valori di input (come verrebbero inseriti dall'utente tramite la tastiera) e/o gli output di formula (se numerici); 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 del foglio 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
Le celle vengono utilizzate per fare riferimento ai numeri di riga e colonna. Puoi recuperare un singolo intervallo
specifico utilizzando i parametri di query max-row, min-row, max-col e min-col. Ad esempio, quanto riportato di seguito 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 il valore inputValue di celle recuperate,
il valore che altrimenti verrebbe digitato 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 numericValue, ad esempio quando una formula restituisce un numero. Ad esempio, una risposta può includere voci di cella
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, quanto segue restituisce le celle nella colonna D di "Foglio2", a partire dalla riga 2, in ordine di colonna principale e restituendo le formule così come sono state inserite (le celle vuote vengono omesse):
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet2!D2:D?majorDimension=COLUMNS&valueRenderOption=FORMULA
La risposta a questa richiesta ha una struttura 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, è richiesto il metodo spreadsheet.get.
Modificare una cella
L'API Fogli v3 consente di modificare il contenuto delle celle inviando un comando PUT al feed di celle con la voce di cella modificata come corpo della richiesta.
L'API Fogli v4, al contrario, fornisce i metodi spreadsheets.values.update e spreadsheets.values.batchUpdate per la modifica del contenuto delle celle.
API v3
Per modificare il contenuto di una singola cella, trova prima la voce della cella nel feed di celle.
La voce contiene un URL di modifica. Aggiorna la voce in modo che rifletta il contenuto
che vuoi avere nella cella, poi invia una richiesta PUT all'URL di modifica
con la voce della cella aggiornata come corpo della richiesta. Ad esempio, quanto riportato di seguito aggiorna la cella D2 (R2C4) in modo che contenga 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 singole celle nell'API Fogli v4 può essere eseguita 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 stati inseriti nell'interfaccia utente di Fogli (USER_ENTERED) o se non fossero stati analizzati e presi così come sono (RAW). Ad esempio, quanto segue 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 inviarle in un'unica richiesta.
Modifica più celle tramite richiesta batch
Entrambe le API forniscono i mezzi per apportare modifiche al contenuto di più celle con una singola richiesta (batch). Non è necessario che le celle a cui fa riferimento una richiesta batch si trovino in un intervallo contingente.
Nel caso in cui una o più modifiche di celle nel batch non vadano a buon fine, l'API Fogli v3 consente ad altre di andare a buon fine. Tuttavia, l'API Fogli v4 restituisce un errore se uno degli aggiornamenti collettivi non riesce e non ne applica nessuno.
API v3
Per modificare più celle, recupera prima un feed di celle per il foglio di lavoro. La voce contiene un URL del batch. Invia una richiesta POST a questo URL, insieme a un corpo della richiesta che descriva le celle che vuoi aggiornare e i nuovi contenuti della cella. La richiesta e il corpo della richiesta POST
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.
Il campo batch:operation deve essere update per le modifiche alle celle. gs:cell identifica la cella per numero di riga e colonna e fornisce i nuovi dati da inserire al suo interno. id contiene l'URL completo della cella da aggiornare.
link deve avere un attributo href che contiene il percorso completo
per l'ID della cella. Tutti questi campi sono obbligatori per ogni voce.
API v4
L'API Fogli v4 consente la modifica in gruppo dei valori delle celle tramite il metodo spreadsheets.values.batchUpdate.
La modifica di più celle può essere eseguita 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 a partire da quella cella come coordinata in alto a sinistra. Se invece specifichi un intervallo a più celle, i valori forniti devono rientrare esattamente nell'intervallo. In caso contrario, l'API restituisce un errore.