Se hai app esistenti basate sull'API Google Sheets v3, puoi eseguire la migrazione all'API Google Sheets v4. La versione 4 è basata su JSON, ha un'interfaccia più facile da usare e aggiunge una notevole quantità di funzionalità non possibili nella versione 3.
Questa pagina fornisce una mappatura tra i comandi precedenti dell'API Sheets v3 e le operazioni equivalenti nell'API Sheets v4. Il mapping 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à dei fogli, vengono gestiti dalla raccolta fogli di lavoro. Tieni presente che le strutture JSON dell'API v4 non sono compatibili con le strutture XML utilizzate nella v3.
Per ulteriori informazioni sulle risorse disponibili nell'API Sheets v4, consulta la documentazione di riferimento dell'API.
Notazione e termini
L'API v3 si riferisce ai fogli all'interno di un determinato foglio di lavoro come "fogli di lavoro". È sinonimo del termine "fogli" utilizzato dall'API v4.
Le API spesso richiedono di specificare un ID foglio di lavoro del foglio di lavoro con cui stai lavorando. Inoltre, spesso richiedono l'ID del foglio da manipolare. Questi valori vengono visualizzati come parte dell'URL dell'endpoint API, come parametri di query o come parte di un corpo della richiesta. In questa pagina, i segnaposto spreadsheetId e sheetId si riferiscono rispettivamente all'ID foglio di lavoro e all'ID 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 utilizzando il relativo feed elenco; questo è rappresentato in questa pagina dal segnaposto rowId.
Autorizza richieste
Quando la tua app viene eseguita, chiede agli utenti di concedere determinate autorizzazioni; gli ambiti che specifichi nella tua applicazione determinano le autorizzazioni richieste.
API v3
L'API Sheets v3 opera con un unico ambito di autorizzazione:
https://spreadsheets.google.com/feeds
che è un alias di
https://www.googleapis.com/auth/spreadsheets
Può essere utilizzato uno dei due formati di ambito.
API v4
L'API Google Sheets 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 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 dei fogli di lavoro anziché gli ambiti 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 indicare la disponibilità di un determinato foglio di lavoro.
API v3
L'API Sheets v3 esprime la visibilità direttamente nei suoi endpoint. Un foglio di lavoro public
è stato "Pubblicato sul web" e pertanto è accessibile all'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 Sheets v4, non esiste 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 prosegue.
Projection
Il termine proiezione viene utilizzato dall'API Sheets v3 per fare riferimento all'insieme di dati restituiti da una determinata chiamata API, ovvero tutti i dati o un sottoinsieme fisso definito all'interno dell'API. L'API Sheets v4 non utilizza la proiezione, ma ti consente di controllare meglio i dati restituiti.
API v3
Nell'API Sheets v3 sono disponibili solo due possibili impostazioni di proiezione. 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 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 è utile
per rendere il codice più efficiente, ma non può essere personalizzato.
API v4
Sebbene l'API Sheets v4 possa restituire un set di dati completo, non definisce sottoinsiemi fissi analoghi all'impostazione di visibilità basic dell'API Sheets v3.
I metodi nella raccolta spreadsheet 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 particolare foglio di lavoro:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title
Crea un foglio di lavoro
API v3
L'API Sheets v3 non fornisce un mezzo per creare nuovi fogli di lavoro;
in alternativa, è possibile utilizzare il metodo Files.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 Files.create dell'API Drive può essere utilizzato anche con l'API Sheets v4, ma richiede che l'applicazione fornisca l'ambito https://www.googleapis.com/auth/drive.
In alternativa, l'API Sheets 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, il seguente comando crea un nuovo foglio di lavoro e gli assegna 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 Sheets v3 consente a un'applicazione di recuperare un elenco di tutti i fogli di lavoro accessibili all'utente autenticato. L'endpoint del feed del foglio di lavoro è:
GET https://spreadsheets.google.com/feeds/spreadsheets/private/full
API v4
L'API Sheets v4 non fornisce questa operazione specifica. Ti consigliamo di eseguire la migrazione dell'app per utilizzare l'ambito drive.file in combinazione con Google Picker per la selezione dei fogli di lavoro.
Nei casi in cui è necessario elencare i fogli di lavoro, è possibile replicare
tramite il metodo Files.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 con limitazioni.
Recuperare 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 vengono accessibili tramite un feed separato). I metadati includono informazioni quali i titoli dei fogli e le dimensioni.
Il metodo spreadsheets.get dell'API Sheets v4 fornisce l'accesso a queste informazioni e a molte altre.
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, molti
di più di quelli disponibili utilizzando l'API Sheets 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 e le informazioni sulle dimensioni dei fogli 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 ti consentono di aggiungere nuovi fogli a un foglio di lavoro esistente.
API v3
L'API Sheets 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 inviando una richiesta AddSheet nel 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 Sheets v3 consente di aggiornare i titoli e le dimensioni dei fogli; l'API Sheets v4 consente anche questa operazione, ma può essere utilizzata anche per aggiornare altre proprietà dei fogli. Tieni presente che la riduzione delle dimensioni di un foglio potrebbe causare l'eliminazione senza preavviso dei dati nelle celle ritagliate.
API v3
Per modificare il titolo o le dimensioni di un foglio di lavoro, inizia recuperando il
feed del foglio di lavoro e
trovando la voce del foglio di lavoro che ti interessa, 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 le dimensioni, il 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 abbreviazione per elencarle tutte). Ad esempio, il seguente codice specifica che le proprietà del titolo e delle dimensioni 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 l'sheetId di un foglio, utilizza il metodo spreadsheets.get del foglio di lavoro.
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 del foglio di lavoro, poi
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 sheetId per il
foglio da eliminare. Ad esempio:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteSheet": {
"sheetId": sheetId
}
}
],
}Per recuperare il sheetId di un singolo foglio, utilizza il metodo spreadsheets.get.
Recuperare i dati delle righe
Il feed righe elenco è uno dei due metodi forniti dall'API Sheets v3 per accedere ai dati all'interno delle celle di un foglio di lavoro (l'altro è il feed celle). Il feed di righe è pensato per supportare le operazioni comuni dei fogli di lavoro (lettura riga per riga, aggiunta di righe, ordinamento), ma fa alcune ipotesi che lo rendono inadatto per alcune attività. Nello specifico, il feed di elenco presuppone che le righe vuote siano terminazioni del feed e che le intestazioni obbligatorie siano presenti nella prima riga di un foglio.
Al contrario, l'API Sheets v4 non utilizza metodi di accesso specifici per le righe. I dati delle celle del foglio vengono 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 disgiunti di celle.
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 basato su elenchi nella voce del foglio di lavoro di interesse.
Per recuperare un feed basato su elenchi, invia una richiesta GET all'URL del feed di elenchi,
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 corrispondenti a righe specifiche. Le singole celle vengono indicate dai nomi forniti nella riga di intestazione (obbligatoria) del foglio. Ad esempio, ecco una voce a riga singola:
<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 di elenco vengono restituite nell'ordine delle righe. L'API Sheets v3 fornisce parametri di query per modificare l'ordine.
Inverti ordine:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full?reverse=true
Ordinare in base a una colonna specifica:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?orderby=column:lastnameL'API Sheets v3 consente anche di filtrare righe specifiche tramite una query strutturata (a cui fanno riferimento le intestazioni delle colonne):
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?sq=age>25%20and%20height<175API v4
Con l'API Sheets v4, le righe possono essere recuperate per intervallo utilizzando i metodi spreadsheets.values.get o spreadsheets.values.batchGet. Ad esempio, il seguente comando restituisce tutte le righe di "Sheet1":
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 sono incluse nella risposta quando vengono recuperate intere righe, colonne o fogli.
L'API Sheets v4 non ha equivalenti per i parametri di query
dell'ordine delle righe forniti dall'API Sheets v3. L'ordine inverso è banale: basta
elaborare 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 Sheets v4 al momento non ha un equivalente diretto per le query strutturate dell'API Sheets v3. Tuttavia, puoi recuperare i dati pertinenti e ordinarli in base alle tue esigenze nell'applicazione.
Aggiungere 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 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 di interesse.
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 della riga da
aggiungere, con le singole celle a cui viene fatto riferimento dalle 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>
Le nuove righe vengono aggiunte alla fine del foglio specificato.
API v4
Con l'API Sheets v4, puoi aggiungere righe utilizzando il metodo spreadsheets.values.append. L'esempio seguente scrive una nuova riga di dati sotto l'ultima tabella nel "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 Sheets v4 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 di elenco per individuare la voce relativa alla riga che vuoi aggiornare. Aggiorna i contenuti di questa voce in base alle esigenze. Assicurati che il valore ID nella voce che utilizzi 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 in quella 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 Sheets v4, puoi modificare una riga utilizzando la notazione A1 della riga che vuoi modificare ed emettendo una richiesta spreadsheets.values.update per sovrascrivere la riga. 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 di più celle, i valori che fornisci devono rientrare in questo 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 anche aggiornare i dati delle righe utilizzando il metodo spreadsheet.values.batchUpdate; è più efficiente utilizzare questo metodo se apporti più aggiornamenti a righe o celle.
Inoltre, l'API Sheets v4 consente anche di modificare le proprietà e la formattazione delle celle utilizzando le richieste UpdateCells o RepeatCell in un spreadsheets.batchUpdate.
Eliminare una riga
Entrambe le API supportano l'eliminazione delle righe. Una riga eliminata viene rimossa dal foglio di lavoro e le righe sottostanti vengono spostate di una posizione verso l'alto.
API v3
Per eliminare una riga, recuperala innanzitutto dal
feed di elenco,
poi 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 modificata da un altro client dopo il recupero, includi un'intestazione HTTP If-Match che contenga il valore ETag della riga originale. Puoi determinare il valore ETag della riga originale esaminando l'attributo gd:etag dell'elemento entry.
Se vuoi eliminare la riga indipendentemente dal fatto che qualcun altro l'abbia aggiornata dopo il recupero, utilizza If-Match: * e non includere l'ETag. In questo caso, non è necessario recuperare la riga prima di eliminarla.
API v4
L'eliminazione delle righe con l'API Sheets v4 viene gestita da una chiamata al metodo spreadsheet.batchUpdate, utilizzando una richiesta DeleteDimension. Questa richiesta può essere utilizzata anche per rimuovere colonne e gli sviluppatori possono scegliere di rimuovere solo una parte di una riga o di una colonna. Ad esempio, il seguente codice rimuove la sesta riga di un foglio con l'ID specificato (gli indici di riga sono basati su zero, con startIndex inclusivo ed endIndex esclusivo):
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteDimension": {
"range": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 5,
"endIndex": 6
}
}
}
],
}Il sheetId di un foglio può essere recuperato utilizzando il metodo spreadsheet.get.
Recuperare i dati della cella
L'API Sheets v3 fornisce un feed di celle per l'accesso di base a tutti i dati memorizzati in un
foglio di lavoro. Per l'accesso in lettura, il feed delle 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 singolo blocco. Gli intervalli disgiunti devono essere recuperati
separatamente utilizzando richieste GET aggiuntive.
L'API Sheets v4 può recuperare qualsiasi insieme di dati delle celle da un foglio (inclusi più intervalli disgiunti). L'API Sheets v3 può restituire solo i contenuti delle celle come valori di input (come se fossero inseriti da un utente da tastiera) e/o gli output di formula (se numerici); l'API Sheets v4 concede l'accesso completo a valori, formule, formattazione, collegamenti ipertestuali, convalida dei dati e altre proprietà.
API v3
Per determinare l'URL di un feed basato sulle celle per un determinato foglio di lavoro, esamina il feed del foglio di lavoro e trova l'URL del feed delle celle nella voce del foglio di lavoro di interesse.
Per recuperare un feed basato sulle 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 indicate utilizzando il numero di riga e di 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, il seguente comando recupera tutte le celle della 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=4L'API Sheets v3 restituisce il 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. A volte l'API restituisce anche un numericValue; ad esempio,
quando una formula restituisce un numero. Ad esempio, una risposta potrebbe 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, il seguente restituisce le celle della colonna D di "Sheet2", a partire dalla riga 2, in ordine di colonna e restituendo le formule così come sono state inserite (le celle vuote finali 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 a:
{
"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 delle celle. Se vuoi accedere alle proprietà delle celle, come la formattazione, è necessario il metodo spreadsheet.get.
Modificare una cella
L'API Sheets v3 ti consente di modificare il contenuto delle celle inviando un comando PUT al feed delle celle con la voce della cella modificata come corpo della richiesta.
L'API Sheets v4, al contrario, fornisce i metodi spreadsheets.values.update e spreadsheets.values.batchUpdate per modificare i contenuti delle celle.
API v3
Per modificare i contenuti di una singola cella, individua innanzitutto la voce della cella nel
feed delle celle.
La voce contiene un URL di modifica. Aggiorna la voce in modo che rifletta i contenuti
che vuoi che la cella contenga, quindi invia una richiesta PUT all'URL di modifica
con la voce della cella aggiornata come corpo della richiesta. Ad esempio, i seguenti aggiornamenti della 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 una singola cella nell'API Sheets 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 lasciati non 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 apporti modifiche a più celle, utilizza il metodo spreadsheets.values.batchUpdate per emetterle in un'unica richiesta.
Modificare più celle tramite 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 fa riferimento una richiesta batch non devono necessariamente trovarsi in un intervallo contiguo.
Nel caso in cui una o più modifiche delle celle nel batch non vadano a buon fine, l'API Sheets v3 consente alle altre di riuscire. Tuttavia, l'API Sheets v4 restituisce un errore se uno degli aggiornamenti batch non va a buon fine e in questo caso 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 batch. Invia una richiesta POST
a questo URL, insieme a un corpo della richiesta che descrive le celle che
vuoi aggiornare e il nuovo contenuto delle celle. 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.
Il campo batch:operation deve essere update per le modifiche alle celle. gs:cell
identifica la cella in base al numero di riga e colonna e fornisce i nuovi dati
da inserire. id contiene l'URL completo della cella da aggiornare.
link deve avere un attributo href che contenga il percorso completo dell'ID della cella. Tutti questi campi sono obbligatori per ogni voce.
API v4
L'API Sheets v4 consente la modifica batch 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 di più celle, i valori forniti devono corrispondere esattamente a questo intervallo; in caso contrario, l'API restituisce un errore.