Esegui la migrazione dall'API Sheets v3

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 quantità significativa di funzionalità non disponibili nella versione 3.

Questa pagina fornisce una mappatura tra i comandi dell'API Sheets v3 precedente e le relative operazioni equivalenti nell'API Sheets v4. La mappatura si concentra principalmente sulla raccolta spreadsheets.values, che fornisce funzionalità di lettura e scrittura dirette delle celle. Altri aspetti, come l'aggiunta di fogli o l'aggiornamento delle relative proprietà, sono gestiti dalla raccolta Fogli di lavoro. Tieni presente che le strutture JSON dell'API 4 non sono compatibili con le strutture XML utilizzate nella versione 3.

Per ulteriori informazioni sulle risorse disponibili nell'API Fogli 4, consulta il riferimento all'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 "sheets" utilizzato dall'API v4.

Le API spesso richiedono di specificare un ID foglio di lavoro del foglio di lavoro con cui stai lavorando. Spesso richiedono anche l'ID del foglio da manipolare. Questi valori vengono visualizzati nell'URL dell'endpoint API, come parametri di query o all'interno 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 utilizzando il suo feed elenco. Questo è rappresentato in questa pagina dal segnaposto rowId.

Autorizza richieste

Quando l'app viene eseguita, chiede agli utenti di concedere determinate autorizzazioni. Gli ambiti specificati 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 per

https://www.googleapis.com/auth/spreadsheets

È possibile utilizzare entrambi i formati di ambito.

API v4

La versione 4 dell'API Fogli 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 la tua applicazione non deve apportare modifiche ai fogli o alle proprietà dei fogli di un utente. Utilizza gli ambiti dei fogli di lavoro anziché quelli di Drive se l'applicazione non ha bisogno di 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

La versione 3 dell'API Fogli esprime la visibilità direttamente nei suoi endpoint. Un foglio di lavoro public è stato "pubblicato sul web" e, pertanto, può essere 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 versione 4 dell'API Fogli non è presente una dichiarazione esplicita della visibilità. Le chiamate API vengono effettuate utilizzando gli ID dei fogli di lavoro. Se l'applicazione non ha l'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 Sheets v3 per fare riferimento all'insieme di dati restituito da una determinata chiamata API, in toto o in un sottoinsieme fisso definito all'interno dell'API. L'API Sheets v4 non utilizza la proiezione, ma consente un maggiore controllo sui dati restituiti.

API v3

Nell'API Fogli v3 sono disponibili solo due 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 dell'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 limita 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 Sheets v3 non fornisce un mezzo per creare nuovi fogli di lavoro. Puoi invece utilizzare il metodo Files.create dell'API Drive per creare nuovi file di fogli di lavoro. Per farlo, l'applicazione deve dichiarare 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.

Come alternativa equivalente, la versione 4 dell'API Fogli fornisce il metodo spreadsheets.create, che può anche facoltativamente aggiungere fogli, impostare le proprietà del foglio di lavoro e dei fogli 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 dall'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 della tua app in modo che utilizzi l'ambito drive.file in combinazione con il selettore Google per la selezione dei fogli di lavoro.

Nei casi in cui sia necessario elencare i fogli di lavoro, l'operazione può essere replicata 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 limitato.

Recupera i metadati del foglio

La versione 3 dell'API Fogli fornisce un feed per accedere ai metadati del foglio contenuti in un determinato foglio di lavoro (ai dati di riga e cella si accede tramite un feed separato). I metadati includono informazioni quali i titoli dei fogli e le informazioni sulle dimensioni.

Il metodo spreadsheets.get della versione 4 dell'API Sheets 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 <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à dei fogli e altri metadati, molto più di quanto sia disponibile utilizzando l'API Sheets v3. Se vuoi solo leggere 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 dei fogli e le informazioni sulle dimensioni sono disponibili nello specifico 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 inviando 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. Nell'ambito del corpo della richiesta, puoi specificare le proprietà del 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. Lo consente anche l'API Sheets v4, 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 dei dati nelle celle ritagliate senza avviso.

API v3

Per modificare il titolo o le dimensioni di un foglio di lavoro, inizia recuperando il feed del foglio di lavoro e trovandovi 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 elencarle esplicitamente (se vuoi aggiornare tutte le proprietà, utilizza fields:"*" come abbreviazione per elencarle tutte). Ad esempio, il codice seguente specifica che le proprietà 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 sheetId di un foglio, utilizza il metodo spreadsheets.get del foglio di lavoro.

Eliminare un foglio

Entrambe le API possono rimuovere fogli da un determinato foglio di lavoro.

API v3

Per eliminare un foglio di lavoro, inizia recuperando il feed del foglio 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 sheetId per il foglio da eliminare. Ad esempio:

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
 
{
  "requests": [
    {
      "deleteSheet": {
        "sheetId": sheetId
      }
    }
  ],
}

Per recuperare 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 dalla versione 3 dell'API Fogli 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 comuni dei fogli di lavoro (lettura riga per riga, aggiunta di righe, ordinamento), ma fa alcune supposizioni che lo rendono inadatto per alcune attività. Nello specifico, il feed elenco presuppone che le righe vuote siano chiusure 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 riga. I dati delle celle del foglio vengono invece richiamati 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 non connessi.

API v3

Per determinare l'URL di un feed basato su elenco per un determinato foglio di lavoro, recupera il feed del foglio di lavoro e individua l'URL del feed elenco nella voce del foglio di lavoro di tuo interesse.

Per recuperare un feed basato su elenco, invia una richiesta GET all'URL del feed dell'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 corrispondente a righe specifiche. I singoli riferimenti alle celle sono costituiti dai nomi forniti nella riga di intestazione del foglio (obbligatoria). Ad esempio, di seguito è riportata una voce con una 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. La versione 3 dell'API Fogli fornisce 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

La versione 3 dell'API Fogli consente inoltre di filtrare righe specifiche tramite una query strutturata (a cui fanno riferimento le intestazioni di colonna):

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
             ?sq=age>25%20and%20height<175

API v4

Con la versione 4 dell'API Fogli, 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 a:

{
  "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 recuperati interi 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.

Al momento l'API Sheets v4 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.

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 elenco per un determinato foglio di lavoro, recupera il feed del foglio di lavoro e individua l'URL del post nella voce del foglio di lavoro di tuo interesse.

Per aggiungere una riga di dati, invia una richiesta POST all'URL 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 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>

Le nuove righe vengono aggiunte alla fine del foglio specificato.

API v4

Con la versione 4 dell'API Sheets, 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 ti consente di accodare 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 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 nella voce della 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 sovrascriverla. L'intervallo specificato deve fare riferimento solo alla prima cella della riga; l'API deducono le celle da aggiornare in base ai valori forniti con la richiesta. Se invece specifichi un intervallo di più celle, i valori forniti devono rientrare in quell'intervallo. In caso contrario, l'API restituirà un errore.

L'esempio seguente di richiesta e corpo della richiesta 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 dal metodo spreadsheet.values.batchUpdate. È più efficiente utilizzare questo metodo se apporti più aggiornamenti delle righe o delle celle.

Inoltre, la versione 4 dell'API Fogli ti consente 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 una riga più in alto.

API v3

Per eliminare una riga, recuperala prima 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 modificata da un altro client da quando l'hai recuperata, includi un'intestazione HTTP If-Match contenente 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 un'altra persona 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 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 le colonne e gli sviluppatori possono scegliere di rimuovere solo parte di una riga o di una colonna. Ad esempio, il codice seguente rimuove la sesta riga di un foglio con l'ID specificato (gli indici di riga sono basati su zero, con startIndex incluso ed endIndex escluso):

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
 
{
  "requests": [
    {
      "deleteDimension": {
        "range": {
          "sheetId": sheetId,
          "dimension": "ROWS",
          "startIndex": 5,
          "endIndex": 6
        }
      }
    }
  ],
}

sheetId di un foglio può essere recuperato utilizzando il metodo spreadsheet.get.

Recupera i dati della cella

La versione 3 dell'API Fogli 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 singolo blocco: gli intervalli in disgiunto devono essere recuperati separatamente utilizzando richieste GET aggiuntive.

La versione 4 dell'API Fogli può recuperare qualsiasi insieme di dati di celle da un foglio (inclusi più intervalli indipendenti). La versione 3 dell'API Fogli può restituire i contenuti delle celle solo come valori di input (come verrebbero inseriti da un utente su una tastiera) e/o come output della formula (se numerica); la versione 4 dell'API Fogli concede l'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 della cella nella voce del foglio di lavoro di tuo interesse.

Per recuperare un feed basato su celle, invia una richiesta GET all'URL del feed delle celle, utilizzando un'intestazione di autorizzazione appropriata. Ad esempio:

GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full

I riferimenti alle celle vengono utilizzati utilizzando il numero di riga e di colonna. Puoi recuperare un singolo intervallo specifico 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=4

La versione 3 dell'API Fogli restituisce il inputValue delle celle recuperate, ovvero il valore che un utente altrimenti digiterebbe 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 può includere voci di cella simili per struttura a quanto segue:

<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. Ad esempio, il seguente codice restituisce le celle della colonna D di "Foglio2", a partire dalla riga 2, in ordine di colonna e restituisce le formule 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 di celle. Se vuoi accedere alle proprietà delle celle, come la formattazione, è necessario il metodo spreadsheet.get.

Modificare una cella

La versione 3 dell'API Fogli ti consente di modificare i contenuti delle celle emettendo un comando PUT al feed della cella con la voce della cella modificata come corpo della richiesta.

L'API Sheets v4, invece, 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, devi prima trovare la relativa voce nel feed di 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, il seguente 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 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 devono essere trattati come se fossero inseriti nell'IDE di Fogli (USER_ENTERED) o se devono essere lasciati non analizzati e presi così come sono (RAW). Per 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 più modifiche alle celle, utilizza il metodo spreadsheets.values.batchUpdate per eseguirle in un'unica richiesta.

Modificare più celle tramite una richiesta batch

Entrambe le API forniscono i mezzi per apportare modifiche ai contenuti di più celle con una singola richiesta (collettiva). Le celle a cui fa riferimento una richiesta batch non devono necessariamente trovarsi in un intervallo contiguo.

Se una o più modifiche alle celle nel batch non vanno a buon fine, l'API Sheets v3 consente alle altre di andare a buon fine. Tuttavia, l'API Sheets v4 restituisce un errore se uno degli aggiornamenti raggruppati non va a buon fine e, in questo caso, non ne applica nessuno.

API v3

Per modificare più celle, recupera innanzitutto 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 descriva le celle che vuoi aggiornare e i nuovi contenuti delle celle. 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 delle 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 contenente il percorso completo dell'ID della cella. Tutti questi campi sono obbligatori per ogni voce.

API v4

La versione 4 dell'API Fogli consente di modificare in blocco i valori delle celle tramite il metodo spreadsheets.values.batchUpdate.

Puoi modificare più celle 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 adattarsi esattamente a quell'intervallo. In caso contrario, l'API restituisce un errore.