Esegui la migrazione dall'API Sheets v3

Se hai già delle app basate sull'API Fogli Google v3, puoi eseguire la migrazione API Fogli Google v4. La versione v4 è basata su JSON, ha un modello e aggiunge una notevole quantità di funzionalità che non è possibile nella versione v3.

Questa pagina fornisce una mappatura tra i comandi precedenti dell'API Fogli v3 e i relativi operazioni equivalenti nell'API Fogli v4. La mappatura si concentra in gran parte spreadsheets.values che fornisce funzionalità diretta di lettura e scrittura nelle celle. Altri aspetti, come l'aggiunta di fogli o l'aggiornamento delle proprietà dei fogli, sono gestiti nella raccolta fogli di lavoro. Tieni presente che le strutture JSON dell'API v4 non sono compatibili con le versioni precedenti Strutture XML utilizzate nella versione 3.

Per ulteriori informazioni sulle risorse disponibili nell'API Fogli v4, vedi Riferimento API.

Notazione e termini

L'API v3 fa riferimento ai fogli di un determinato foglio di lavoro con l'espressione "fogli di lavoro". Questo è sinonimo del termine "fogli" usate dall'API v4.

Le API spesso richiedono di specificare un ID foglio di lavoro del foglio di lavoro su cui stai lavorando. Spesso richiedono anche l'ID del foglio di lavoro manipolato. Questi valori vengono visualizzati come parte dell'endpoint API , come parametri di query o come parte del corpo di una richiesta. In questa pagina, segnaposto spreadsheetId e sheetId fare riferimento rispettivamente agli ID foglio di lavoro e foglio di lavoro. 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; indicato in questa pagina dal segnaposto rowId.

Autorizza richieste

Durante l'esecuzione, l'app chiede agli utenti di concedere determinate autorizzazioni. gli ambiti che hai specificato nella tua applicazione e stabilire le autorizzazioni richieste.

API v3

L'API Fogli v3 opera con un singolo ambito di autorizzazione:

https://spreadsheets.google.com/feeds

che è un alias di

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

È possibile utilizzare entrambi i formati di ambito.

API v4

L'API Fogli v4 utilizza uno o più dei seguenti set di ambiti:

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

Utilizza gli ambiti di sola lettura se l'applicazione non deve apportare modifiche a i fogli o le proprietà dei fogli di un utente. Utilizza gli ambiti dei fogli di lavoro anziché 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 fare riferimento alla la disponibilità di un determinato foglio di lavoro.

API v3

L'API Fogli v3 esprime la visibilità direttamente nei propri endpoint. public foglio di lavoro è stato "Pubblicato sul Web" e quindi sono accessibili l'API senza autorizzazione, mentre un foglio di lavoro private richiede autenticazione. La visibilità viene specificata nell'endpoint dopo ID foglio di lavoro:

https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full

API v4

Nella nuova API Fogli v4, non è prevista una dichiarazione esplicita di visibilità. Le chiamate API vengono effettuate utilizzando gli ID foglio di lavoro. Se l'applicazione non dispone di l'autorizzazione ad accedere al foglio di lavoro specificato, viene restituito un errore. Altrimenti la chiamata continua.

Projection

Il termine proiezione viene utilizzato dall'API Fogli v3 per fare riferimento al set di dati restituito da una determinata chiamata API, oppure tutte o un sottoinsieme fisso definiti nell'API. L'API Fogli v4 non utilizza la proiezione, ma ti consente di avere un maggiore controllo sui dati restituiti.

API v3

Esistono solo due possibili impostazioni di proiezione nell'API Fogli v3. full proiezione restituisce tutte le informazioni disponibili, mentre basic restituisce un sottoinsieme fisso di dati più piccolo (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 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 Fogli v4 possa restituire un set di dati completo, non definisce sottoinsiemi analoghi all'impostazione di visibilità basic dell'API Fogli v3. Metodi nel foglio di lavoro di raccolta dei dati limitano la quantità di dati restituiti attraverso l'uso un parametro di query fields.

Ad esempio, la seguente query restituisce solo i titoli di tutte le di un foglio di lavoro specifico:

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title

Crea un foglio di lavoro

API v3

L'API Fogli v3 non fornisce un mezzo per creare nuovi fogli di lavoro. viene invece eseguito il file File.create dell'API Drive può essere utilizzato per creare nuovi file di fogli di lavoro. Ciò richiede per dichiarare l'ambito https://www.googleapis.com/auth/drive.

API v4

Il metodo File.create dell'API Drive può può essere utilizzato anche con l'API Fogli v4, ma richiede che l'applicazione fornisca l'ambito https://www.googleapis.com/auth/drive.

In alternativa, l'API Fogli v4 offre una spreadsheets.create che può anche aggiungere fogli, impostare il foglio di lavoro e e aggiungere intervalli denominati. Ad esempio, quanto segue crea una nuova foglio di lavoro assegnandogli il nome "NewTitle":

POST https://sheets.googleapis.com/v4/spreadsheets
{
 "properties": {"title": "NewTitle"}
}

Elenca i fogli di lavoro per l'utente autenticato

API v3

Il feed dell'API Fogli v3 consente a un'applicazione di recuperare un elenco di tutte le ai fogli di lavoro accessibili dall'utente autenticato. Il feed del foglio di lavoro dell'endpoint è:

GET https://spreadsheets.google.com/feeds/spreadsheets/private/full

API v4

L'API Fogli v4 non fornisce questa operazione specifica. I nostri suggerimenti eseguire la migrazione della tua app per utilizzare l'ambito drive.file in combinazione con Selettore Google per la selezione del foglio di lavoro.

Nei casi in cui è necessario elencare i fogli di lavoro, questi possono essere replicati mediante il metodo File.list dell'API Drive, utilizzando una query mimeType:

GET https://www.googleapis.com/drive/v3/files
             ?q=mimeType='application/vnd.google-apps.spreadsheet'

Utilizzare il 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 (accesso ai dati di righe e celle un feed separato). I metadati includono informazioni quali titoli dei fogli e le informazioni sulle dimensioni.

API Fogli v4 spreadsheets.get 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 l'intestazione dell'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 sono contenuti in un file <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

L'app spreadsheets.get può essere usato per acquisire le proprietà del foglio e altri metadati, rispetto a quelle disponibili con l'API Fogli v3. Se vuoi leggere le proprietà del foglio, imposta la 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 Spreadsheet la risposta contiene un array di Sheet oggetti i titoli dei fogli e le informazioni sulle dimensioni sono disponibili nel 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 rendendo successiva richiesta POST (autenticata). Puoi specificare le dimensioni 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 creando un AddSheet nel file spreadsheets.batchUpdate . Come parte del corpo della richiesta, puoi specificare le proprietà del foglio per nel nuovo foglio; tutte le proprietà sono facoltative. È un errore fornire un 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 questa operazione, ma può essere utilizzato anche per aggiornare altre proprietà del foglio. Tieni presente che, se riduci le dimensioni di un foglio, i dati nelle celle ritagliate potrebbero essere eliminati senza preavviso.

API v3

Per modificare il titolo o la dimensione di un foglio di lavoro, inizia recuperando feed dei fogli di lavoro e trovare la voce desiderata nel foglio di lavoro, 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, crea una updateSheetProperties nel spreadsheets.batchUpdate . Il corpo della richiesta POST deve contenere le proprietà da modificato e il parametro fields deve elencare in modo esplicito queste proprietà (se vuoi aggiornare tutte le proprietà, usa fields:"*" come forma abbreviata di elencarli tutti). Per esempio, quanto segue specifica che il titolo e le 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'elemento sheetId di un foglio, utilizza il foglio di lavoro spreadsheets.get.

Eliminare un foglio

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

API v3

Per eliminare un foglio di lavoro, inizia recuperando feed foglio di lavoro, 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, crea un DeleteSheet nel spreadsheets.batchUpdate . Il corpo della richiesta POST deve contenere solo il valore sheetId per foglio da eliminare. Ad esempio:

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

Per recuperare l'elemento sheetId di un singolo foglio, utilizza il metodo foglio di lavoro spreadsheets.get .

Recuperare i dati delle righe

Il feed list rows è 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). La il feed di righe ha lo scopo di supportare operazioni comuni sui fogli di lavoro (leggere riga per riga, aggiungere righe e ordinare), ma fa alcune ipotesi che lo rendono inadatto per alcune attività. In particolare, il feed elenco presuppone che le righe vuote siano del feed di chiusura e che nella prima riga di un messaggio siano presenti intestazioni obbligatorie in un foglio di calcolo.

Al contrario, l'API Fogli v4 non utilizza metodi di accesso che sono specifico per la riga. L'accesso ai dati delle celle del foglio è invece possibile con un riferimento necessari utilizzando la notazione A1. La possono essere blocchi di celle, intere righe, intere colonne o interi fogli. L'API può anche accedere a insiemi di celle disgiunti.

API v3

Per determinare l'URL di un feed basato su elenco per un determinato foglio di lavoro, recupera il feed dei fogli di lavoro e trova l'URL del feed elenco nella voce del foglio di lavoro che ti interessa.

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

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

La risposta a questa richiesta contiene, tra le altre cose, le voci corrispondenti a righe specifiche. Le singole celle fanno riferimento a i nomi forniti nella riga di intestazione (obbligatoria) del foglio. Ad esempio, qui è una singola voce:

<entry gd:etag='"S0wCTlpIIip7ImA0X0QI"'>
  <id>rowId</id>
  <updated>2006-11-17T18:23:45.173Z</updated>
  <category scheme="http://schemas.google.com/spreadsheets/2006"
      term="http://schemas.google.com/spreadsheets/2006#list"/>
  <title type="text">Bingley</title>
  <content type="text">Hours: 10, Items: 2, IPM: 0.0033</content>
  <link rel="self" type="application/atom+xml"
      href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId"/>
  <link rel="edit" type="application/atom+xml"
      href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version"/>
  <gsx:name>Bingley</gsx:name>
  <gsx:hours>10</gsx:hours>
  <gsx:items>2</gsx:items>
  <gsx:ipm>0.0033</gsx:ipm>
</entry>

Per impostazione predefinita, le righe restituite nel feed elenco vengono restituite in ordine di riga. L'API Fogli v3 fornisce i parametri di query per modificare l'ordine.

Inverti ordine:

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full?reverse=true

Ordina in base a una colonna specifica:

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
             ?orderby=column:lastname

L'API Fogli v3 consente anche di filtrare righe specifiche tramite un modello (cui si fa riferimento alle intestazioni di colonna):

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

API v4

Con l'API Fogli v4, è possibile recuperare le righe in base all'intervallo utilizzando spreadsheets.values.get o spreadsheets.values.batchGet di machine learning. Ad esempio, quanto segue restituisce tutte le righe in "Foglio1":

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1

La risposta a questa richiesta ha una struttura simile alla seguente:

{
  "range": "Sheet1",
  "majorDimension": "ROWS",
  "values": [["Name", "Hours", "Items", "IPM"],
             ["Bingley", "10", "2", "0.0033"],
             ["Darcy", "14", "6", "0.0071"]]
}

Le celle vuote finali non vengono incluse nella risposta durante il recupero di intere celle righe, colonne o fogli.

L'API Fogli v4 non ha equivalenti per la query sull'ordine delle righe forniti dall'API Fogli v3. L'inversione dell'ordine è banale; semplicemente elaborerai l'array values restituito in ordine inverso. L'opzione Ordine per colonna non è supportato per le letture, ma è possibile ordinare i dati nel foglio (utilizzando un SortRange). richiesta e quindi leggerla.

L'API Fogli v4 al momento non ha un equivalente diretto per le query strutturate dell'API Fogli v3. Tuttavia, puoi recuperare i dati pertinenti e a seconda delle necessità nella tua applicazione.

Aggiungi una nuova riga di dati

Puoi aggiungere una nuova riga di dati a un foglio utilizzando una delle due API.

API v3

Per determinare l'URL di un feed basato su elenco per un determinato foglio di lavoro, recupera il feed dei fogli di lavoro e individua l'URL del post nel foglio di lavoro che ti interessa.

Per aggiungere una riga di dati, invia una richiesta POST all'URL del post, utilizzando un'intestazione di autorizzazione appropriata. Ad esempio:

POST https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full

Il corpo della richiesta POST deve contenere una voce per i dati di riga da add, con 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 spreadsheets.values.append . L'esempio seguente scrive una nuova riga di dati sotto l'ultima riga tabella in "Sheet1" 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 ti consente anche di aggiungere celle con specifiche proprietà e formattazione utilizzando 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 di della voce, se necessario. Assicurati che il valore ID nella voce che utilizzi corrisponda all'ID della voce esistente.

Una volta aggiornata la voce, invia una richiesta PUT con la voce il 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 Fogli v4, puoi modificare una riga utilizzando Notazione A1 della riga che vuoi modificare e emettere un spreadsheets.values.update di sovrascrivere la riga. L'intervallo specificato deve fare riferimento solo ai nella prima cella della riga; l'API deduce le celle da aggiornare in base 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 .

La richiesta e il corpo della richiesta di esempio seguente 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 dalla spreadsheet.values.batchUpdate ; è più efficiente utilizzare questo metodo se si apportano più di riga o di cella.

Inoltre, l'API Fogli v4 consente anche di modificare le proprietà della cella e la formattazione delle celle utilizzando UpdateCells o RepeatCell in un spreadsheets.batchUpdate.

Elimina una riga

Entrambe le API supportano l'eliminazione delle righe. Una riga eliminata viene rimossa dalla foglio di lavoro e alle righe sottostanti viene spostato uno in alto.

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 modificata da un altro client da quando l'hai recuperato, includi un'intestazione If-Match HTTP che contiene il valore ETag della riga originale. Puoi determinare l'originale il valore ETag della riga esaminando l'attributo gd:etag dell'elemento voce.

Se vuoi eliminare la riga indipendentemente dal fatto che l'aggiornamento sia stato effettuato o meno da qualcun altro da quando l'hai recuperato, 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 un spreadsheet.batchUpdate di chiamata al metodo DeleteDimension richiesta. Questa richiesta può essere utilizzata anche per rimuovere colonne e gli sviluppatori e scegli di rimuovere solo parte di una riga o di una colonna. Ad esempio, seguente rimuove la sesta riga di un foglio con l'ID specificato (gli indici della riga sono in base zero, con startIndex inclusi ed endIndex esclusivi):

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

È possibile recuperare l'elemento sheetId di un foglio utilizzando il metodo spreadsheet.get.

Recuperare i dati delle celle

L'API Fogli v3 fornisce un feed di celle per l'accesso di base a tutti i dati archiviati in un in un foglio di lavoro. Per l'accesso in lettura, il feed di celle può fornire l'intero foglio contenuto o un intervallo di celle del foglio definito da un set di parametri di query, ma solo come un singolo blocco. Gli intervalli separati devono essere recuperati separatamente usando richieste GET aggiuntive.

L'API Fogli v4 può recuperare qualsiasi insieme di dati di celle da un foglio (inclusi più intervalli separati). L'API Fogli v3 può restituire solo i contenuti delle celle come valori di input (come verrebbero inseriti da un utente con una tastiera) e/o gli output di formula (se numerica); l'API Fogli v4 concede l'accesso completo ai 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 la sezione feed dei fogli di lavoro e trova l'URL del feed di celle nella voce del foglio di lavoro che ti interessa.

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

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

Alle celle viene fatto riferimento usando i numeri di riga e colonna. Il recupero di uno specifico questo intervallo può essere eseguito utilizzando max-row, min-row, max-col e min-col parametri di ricerca. Ad esempio, quanto segue recupera tutte le celle nella colonna 4 (D), a partire dalla riga 2:

GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
             ?min-row=2&min-col=4&max-col=4

L'API Fogli v3 restituisce il inputValue delle celle recuperate: valore che un utente altrimenti digiterebbe nell'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 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 spreadsheets.values.get o spreadsheets.values.batchGet rispettivamente per l'intervallo o gli intervalli di interesse. Ad esempio, seguente restituisce le celle nella colonna D di "Sheet2", a partire dalla riga 2, in ordine colonna-maggiore e restituire le formule così come sono state inserite (trailing vuoto celle sono omesse):

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet2!D2:D?majorDimension=COLUMNS&valueRenderOption=FORMULA

La struttura della risposta a questa richiesta è simile alla seguente:

{
  "spreadsheetId": spreadsheetId,
  "valueRanges": [
      {"range": "Sheet2!D2:D",
       "majorDimension": "COLUMNS",
       "values": [["Widget", 234, "=FLOOR(C4/(B4*60),.0001)", "=D4\*1000"]]
      }]
}

È più efficiente usare spreadsheet.values.batchGet se intendi recuperare più intervalli di dati di celle. Se vuoi accedere alle proprietà delle celle come la formattazione, spreadsheet.get è obbligatorio.

Modifica una cella

L'API Fogli v3 ti consente di modificare i contenuti delle celle inviando un comando PUT il feed di celle con la voce di cella modificata come corpo della richiesta.

L'API Fogli v4, invece, fornisce spreadsheets.values.update e spreadsheets.values.batchUpdate per modificare il contenuto della cella.

API v3

Per modificare il contenuto di una singola cella, individua innanzitutto la voce della cella nella feed delle celle. La voce contiene un URL di modifica. Aggiorna la voce in modo che rifletta i contenuti che deve contenere la cella, quindi invia una richiesta PUT all'URL di modifica con la voce di cella aggiornata come corpo della richiesta. Ad esempio, seguente aggiorna la cella D2 (R2C4) per contenere una formula SUM:

PUT https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full//R2C4/srevc


<entry xmlns="http://www.w3.org/2005/Atom"
    xmlns:gs="http://schemas.google.com/spreadsheets/2006">
  <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4</id>
  <link rel="edit" type="application/atom+xml"
    href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4"/>
  <gs:cell row="2" col="4" inputValue="=SUM(A1:B6)"/>
</entry>

API v4

La modifica di una singola cella nell'API Fogli v4 può essere eseguita con spreadsheets.values.update . Questo metodo richiede un parametro di query ValueInputOption, che specifica se i dati di input vengono trattati come se fossero inseriti UI di Fogli (USER_ENTERED), o lasciato non analizzato e preso così com'è (RAW). Per Ad esempio, il seguente aggiorna la cella D2 con una formula:

PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/D2?valueInputOption=USER_ENTERED
{"values": [["=SUM(A1:B6)"]]}

Se stai apportando modifiche a più celle, utilizza spreadsheets.values.batchUpdate per emetterli in un'unica richiesta.

Modificare più celle tramite una richiesta batch

Entrambe le API forniscono i mezzi per apportare modifiche al contenuto di più celle con una singola richiesta (batch). Le celle a cui si fa riferimento in una richiesta batch sono non deve essere necessariamente in un intervallo contingente.

Nel caso in cui una o più modifiche delle celle nel batch non vadano a buon fine, l'API Fogli v3 consente agli altri di completare l'operazione. Tuttavia, l'API Fogli v4 restituisce un errore se gli aggiornamenti in batch non vanno a buon fine e non ne applica nessuno.

API v3

Per modificare più celle, devi prima recuperare un feed di celle per il foglio di lavoro. La voce contiene un URL batch. Invia un POST a questo URL, insieme al corpo della richiesta che descrive le celle da aggiornare e i nuovi contenuti della cella. La richiesta POST e il corpo della richiesta hanno una struttura simile alla seguente:

POST https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/batch
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:batch="http://schemas.google.com/gdata/batch"
      xmlns:gs="http://schemas.google.com/spreadsheets/2006">
  <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full</id>
  <entry>
    <batch:id>request1</batch:id>
    <batch:operation type="update"/>
    <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4</id>
    <link rel="edit" type="application/atom+xml"
      href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4/version"/>
    <gs:cell row="2" col="4" inputValue="newData"/>
  </entry>
  ...
  <entry>
    <batch:id>request2</batch:id>
    <batch:operation type="update"/>
    <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C5</id>
    <link rel="edit" type="application/atom+xml"
      href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C5/version"/>
    <gs:cell row="5" col="2" inputValue="moreInfo"/>
  </entry>
</feed>

Il campo batch:id deve identificare in modo univoco la richiesta all'interno del batch. Per le modifiche delle celle, il campo batch:operation deve essere update. gs:cell identifica la cella per numero di riga e colonna e fornisce i nuovi dati da inserire. id contiene l'URL completo della cella da aggiornare. link deve avere un attributo href contenente il percorso completo alla 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 spreadsheets.values.batchUpdate .

La modifica di più celle può essere effettuata inviando una richiesta POST con le modifiche ai dati specificate nel corpo della richiesta. Ad esempio:

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values:batchUpdate
{
  "valueInputOption": "USER_ENTERED"
  "data": [
       {"range": "D4",
        "majorDimension": "ROWS",
        "values": [["newData"]]
       },
       {"range": "B5",
        "majorDimension": "ROWS",
        "values": [["moreInfo"]]
       }
  ]
}

Se hai specificato una singola cella come intervallo, tutti i valori forniti vengono scritto nel foglio che inizia con quella cella come coordinata in alto a sinistra. Se invece specifichi un intervallo a più celle, i valori forniti devono rientrare esattamente quell'intervallo; In caso contrario, l'API restituisce un errore.