Jeśli masz już aplikacje oparte na interfejsie Google Sheets API w wersji 3, możesz je przenieść do wersji 4. Wersja 4 jest oparta na formacie JSON, ma wygodniejszy interfejs i dodaje wiele funkcji, które nie są dostępne w wersji 3.
Ta strona zawiera mapowanie starszych poleceń interfejsu Sheets API w wersji 3 na ich odpowiedniki w interfejsie Sheets API w wersji 4. Mapowanie koncentruje się głównie na kolekcji spreadsheets.values, która zapewnia bezpośrednią funkcję odczytu i zapisu komórek. Inne aspekty, takie jak dodawanie arkuszy czy aktualizowanie ich właściwości, są obsługiwane przez kolekcję arkuszy. Pamiętaj, że struktury JSON interfejsu API w wersji 4 nie są wstecznie zgodne ze strukturami XML używanymi w wersji 3.
Więcej informacji o zasobach dostępnych w interfejsie API Arkuszy w wersji 4 znajdziesz w dokumentacji interfejsu API.
Notacje i terminy
W interfejsie API w wersji 3 arkusze w danym arkuszu kalkulacyjnym są nazywane „arkuszami”. Jest to synonim terminu „arkusz”, którego używa interfejs API w wersji 4.
Interfejsy API często wymagają podania identyfikatora arkusza kalkulacyjnego, z którym pracujesz. Często wymagają też identyfikatora arkusza, który ma zostać zmodyfikowany. Te wartości pojawiają się w adresie URL punktu końcowego interfejsu API, jako parametry zapytania lub w ciele żądania. Na tej stronie okna zastępcze spreadsheetId i sheetId odnoszą się odpowiednio do identyfikatorów arkusza kalkulacyjnego i arkusza. Gdy używasz metod opisanych na tej stronie, zastąp w tych miejscach rzeczywiste identyfikatory.
Interfejs API w wersji 3 przypisuje też identyfikator do wierszy pobranych za pomocą pliku danych listy. Na tej stronie jest on reprezentowany przez placeholder rowId.
Autoryzowanie żądań
Gdy aplikacja jest uruchomiona, prosi użytkowników o przyznanie określonych uprawnień. Zakresy określone w aplikacji określają, o które uprawnienia prosi.
Interfejs Sheets API w wersji 3 działa z jednym zakresem autoryzacji:
https://spreadsheets.google.com/feeds
który jest aliasem
https://www.googleapis.com/auth/spreadsheets
Można użyć dowolnego formatu zakresu.
Interfejs Sheets API w wersji 4 korzysta z co najmniej jednego z tych zestawów zakresów:
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
Użyj zakresów tylko do odczytu, jeśli aplikacja nie musi wprowadzać zmian w arkuszach lub właściwościach użytkownika. Jeśli aplikacja nie potrzebuje ogólnego dostępu do Dysku, użyj zakresów arkuszy kalkulacyjnych zamiast zakresów Dysku.
Widoczność
W starszych wersjach interfejsu API termin widoczność odnosi się do dostępności danego arkusza kalkulacyjnego.
Interfejs Sheets API w wersji 3 określa widoczność bezpośrednio w swoich punktach końcowych. Arkusz kalkulacyjny public został „opublikowany w Internecie”, więc interfejs API może uzyskać do niego dostęp bez autoryzacji, podczas gdy arkusz kalkulacyjny private wymaga uwierzytelnienia. Widoczność jest określana w punkcie końcowym po identyfikatorze arkusza kalkulacyjnego:
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId /private/full
W nowej wersji interfejsu Sheets API 4 nie ma wyraźnego zadeklarowania widoczności. Wywołania interfejsu API są wykonywane za pomocą identyfikatorów arkuszy kalkulacyjnych. Jeśli aplikacja nie ma uprawnień dostępu do określonego arkusza kalkulacyjnego, zwracany jest błąd. W przeciwnym razie połączenie będzie kontynuowane.
Odwzorowanie
Termin projekcja jest używany przez interfejs Sheets API v3 w odniesieniu do zbioru danych zwracanego przez dane wywołanie interfejsu API – może to być cały zbiór danych lub jego stały podzbiór zdefiniowany w interfejsie API. Interfejs Sheets API w wersji 4 nie korzysta z projekcji, ale pozwala Ci lepiej kontrolować, jakie dane są zwracane.
W interfejsie Sheets API w wersji 3 dostępne są tylko 2 ustawienia projekcji. Projekcja full zwraca wszystkie dostępne informacje, a projekcja basic zwraca mniejszy, stały podzbiór danych (w przypadku arkuszy kalkulacyjnych, list i plików danych komórek).
Podobnie jak w przypadku widoczności, projekcja musi być określona w punkcie końcowym interfejsu API (po ustawieniu widoczności):
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId /public/basic
Mniejszy podzbiór danych udostępniany przez projekcję basic jest przydatny do zwiększania wydajności kodu, ale nie można go dostosowywać.
Interfejs Sheets API w wersji 4 może zwracać pełny zbiór danych, ale nie definiuje stałych podzbiorów analogicznych do ustawienia widoczności basic w interfejsie Sheets API w wersji 3.
Metody w kolekcji arkusz ograniczają ilość zwracanych danych za pomocą parametru zapytania fields.
Na przykład to zapytanie zwraca tylko tytuły wszystkich arkuszy w danym arkuszu kalkulacyjnym:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId ?fields=sheets.properties.title
Utwórz arkusz kalkulacyjny
Interfejs Sheets API w wersji 3 nie umożliwia tworzenia nowych arkuszy kalkulacyjnych. Zamiast tego do tworzenia nowych arkuszy kalkulacyjnych można użyć metody Files.create interfejsu Drive API. Wymaga to zadeklarowania w aplikacji zakresu https://www.googleapis.com/auth/drive.
Metody Drive API Files.create można też używać z interfejsem Sheets API w wersji 4, ale wymaga to od aplikacji podania zakresu https://www.googleapis.com/auth/drive.
Interfejs Sheets API w wersji 4 udostępnia metodę spreadsheets.create, która może też opcjonalnie dodawać arkusze, ustawiać właściwości arkuszy i dodawać zakresy nazwane. Na przykład poniższy kod tworzy nowy arkusz kalkulacyjny i nadaje mu nazwę „NewTitle”:
POST https://sheets.googleapis.com/v4/spreadsheets
{
"properties": {"title": "NewTitle"}
}Wyświetlanie listy arkuszy dla uwierzytelnionego użytkownika
Plik danych interfejsu Sheets API w wersji 3 umożliwia aplikacji pobranie listy wszystkich arkuszy dostępnych dla uwierzytelnionego użytkownika. Punkt końcowy pliku danych w arkuszu kalkulacyjnym:
GET https://spreadsheets.google.com/feeds/spreadsheets/private/full
Interfejs Sheets API w wersji 4 nie obsługuje tej operacji. Zalecamy przeniesienie aplikacji na zakres drive.file w połączeniu z selektorem Google do wybierania arkuszy kalkulacyjnych.
W przypadkach, gdy wymagane są listy arkuszy, można je odtworzyć za pomocą metody Files.list interfejsu Drive API, korzystając z zapytania mimeType:
GET https://www.googleapis.com/drive/v3/files
?q=mimeType='application/vnd.google-apps.spreadsheet'Użycie metody files.list interfejsu Drive API do wyświetlenia listy wszystkich arkuszy użytkownika wymaga ograniczonego zakresu.
Pobieranie metadanych arkusza
Interfejs Sheets API v3 udostępnia plik danych, który umożliwia dostęp do metadanych arkusza zawartych w danym arkuszu kalkulacyjnym (do danych wierszy i komórek uzyskuje się dostęp za pomocą osobnego pliku danych). Metadane obejmują informacje takie jak tytuły arkuszy i informacje o rozmiarze.
Interfejs Sheets API w wersji 4 udostępnia metodę spreadsheets.get, która umożliwia dostęp do tych informacji i wielu innych.
Plik danych arkusza jest dostępny z tego punktu końcowego interfejsu API (za pomocą odpowiedniego nagłówka autoryzacji):
GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId /private/full
Odpowiedź na to żądanie ma podobną strukturę, a dane z każdej karty są zawarte w osobnym elemencie <entry>:
<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>
Metody spreadsheets.get można używać do pobierania właściwości arkuszy i innych metadanych. Jest to znacznie więcej niż to, co jest dostępne w interfejsie Sheets API v3. Jeśli chcesz odczytać tylko właściwości arkusza, ustaw parametr zapytania includeGridData na false, aby zapobiec uwzględnianiu danych komórki arkusza:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId ?includeGridData=false
Odpowiedź Spreadsheet zawiera tablicę obiektów Sheet. Informacje o tytułach i rozmiarze arkuszy znajdziesz w elemencie SheetProperties tych obiektów. Na przykład:
{
"spreadsheetId": spreadsheetId ,
"sheets": [
{"properties": {
"sheetId": sheetId ,
"title": "Sheet1",
"index": 0,
"gridProperties": {
"rowCount": 100,
"columnCount": 20,
"frozenRowCount": 1,
"frozenColumnCount": 0,
"hideGridlines": false
},
...
},
...
},
...
],
...
}Dodawanie arkusza do arkusza kalkulacyjnego
Oba interfejsy API umożliwiają dodawanie nowych arkuszy do istniejącego arkusza kalkulacyjnego.
Interfejs Sheets API w wersji 3 może dodawać nowe arkusze do arkusza kalkulacyjnego, wysyłając to żądanie (uwierzytelnione) POST. Możesz określić rozmiar nowego arkusza:
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>
Nowe arkusze możesz dodawać, wysyłając żądanie AddSheet za pomocą metody spreadsheets.batchUpdate. W treści żądania możesz określić właściwości arkusza nowego arkusza. Wszystkie właściwości są opcjonalne. Podanie tytułu, który jest używany w istniejącym arkuszu, jest błędem.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId :batchUpdate
{
"requests": [{
"addSheet": {
"properties": {
"title": "Expenses",
"sheetType": "GRID",
"gridProperties": {
"rowCount": 50,
"columnCount": 10
}
}
}
}],
}Zmienianie tytułu i rozmiaru arkusza
Interfejs Sheets API v3 umożliwia aktualizowanie tytułów i rozmiaru arkuszy. Interfejs Sheets API v4 umożliwia to samo, ale można go też użyć do aktualizowania innych właściwości arkuszy. Pamiętaj, że zmniejszenie rozmiaru arkusza może spowodować usunięcie danych z przyciętych komórek bez ostrzeżenia.
Aby zmienić tytuł lub rozmiar arkusza, zacznij od pobrania pliku danych arkusza i znalezienia odpowiedniego wpisu arkusza, który zawiera adres URL edit.
Zaktualizuj metadane arkusza i prześlij je jako treść żądania PUT do adresu URL edycji. Na przykład:
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>
Aby zaktualizować rozmiar, tytuł i inne właściwości arkusza, wyślij żądanie updateSheetProperties za pomocą metody spreadsheets.batchUpdate. Treść żądania POST powinna zawierać właściwości, które mają zostać zmienione, a parametr fields powinien zawierać ich listę (jeśli chcesz zaktualizować wszystkie właściwości, użyj parametru fields:"*" jako skrótu do ich wszystkich). Na przykład poniższy przykład określa, że w arkuszu o podanym identyfikatorze należy zaktualizować właściwości tytułu i rozmiaru arkusza:
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)"
}
}
],
}Aby pobrać sheetId arkusza, użyj metody spreadsheets.get arkusza kalkulacyjnego.
Usuwanie arkusza
Oba interfejsy API mogą usuwać arkusze z danego arkusza kalkulacyjnego.
Aby usunąć arkusz, zacznij od pobrania pliku danych arkusza, a następnie wyślij żądanie DELETE pod adresem URL edit wpisu docelowego arkusza.
DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId /private/full/sheetId /version
Aby usunąć arkusz, wyślij żądanie DeleteSheet w metodzie spreadsheets.batchUpdate. Treść żądania POST powinna zawierać tylko sheetId arkusza, który ma zostać usunięty. Na przykład:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId :batchUpdate
{
"requests": [
{
"deleteSheet": {
"sheetId": sheetId
}
}
],
}Aby pobrać sheetId pojedynczego arkusza, użyj metody spreadsheets.get arkusza kalkulacyjnego.
Pobieranie danych wiersza
Plik danych z listą wierszy to jedna z 2 metod interfejsu Sheets API w wersji 3, które umożliwiają dostęp do danych w komórkach arkusza kalkulacyjnego (drugą jest plik danych z komórkami). Plik danych z wierszami służy do obsługi typowych operacji na arkuszu kalkulacyjnym (czytanie wiersza po wierszu, dołączanie wierszy, sortowanie), ale zakłada pewne założenia, które powodują, że nie nadaje się do niektórych zadań. W szczególności plik danych z listą zakłada, że puste wiersze oznaczają zakończenie pliku danych, a w pierwszym wierszu arkusza znajdują się nagłówki obowiązkowe.
Natomiast interfejs Sheets API w wersji 4 nie używa metod dostępu, które są specyficzne dla wiersza. Zamiast tego dane komórek arkusza są dostępne przez odwołanie do określonych zakresów wymaganych za pomocą notacji A1. Zakresy mogą być blokami komórek, pełnymi wierszami, pełnymi kolumnami lub pełnymi arkuszami. Interfejs API może też uzyskiwać dostęp do niespójnych zbiorów komórek.
Aby określić adres URL pliku danych opartego na liście dla danego arkusza, pobierz plik danych arkusza i znajdź adres URL pliku danych listy w odpowiednim wpisie arkusza.
Aby pobrać plik danych oparty na liście, wyślij żądanie GET do adresu URL pliku danych o liście, używając odpowiedniego nagłówka autoryzacji. Na przykład:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId /sheetId /private/full
Odpowiedź na to żądanie zawiera m.in. wpisy odpowiadające określonym wierszom. Poszczególne komórki są odwoływane za pomocą nazw podanych w wierszu nagłówka arkusza (obowiązkowo). Oto przykład wpisu w pojedynczym wierszu:
<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>
Domyślnie wiersze zwracane w pliku danych listy są zwracane w kolejności wierszy. Interfejs Sheets API w wersji 3 udostępnia parametry zapytania, które umożliwiają zmianę kolejności.
Odwrotna kolejność:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId /sheetId /private/full?reverse=true
sortowanie według konkretnej kolumny:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId /sheetId /private/full ?orderby=column:lastname
Interfejs Sheets API w wersji 3 umożliwia też filtrowanie określonych wierszy za pomocą zapytania strukturalnego (odwołującego się do nagłówków kolumn):
GET https://spreadsheets.google.com/feeds/list/spreadsheetId /sheetId /private/full ?sq=age>25%20and%20height<175
W interfejsie Sheets API w wersji 4 wiersze można pobierać według zakresu za pomocą metod spreadsheets.values.get lub spreadsheets.values.batchGet. Na przykład poniższy wiersz zwraca wszystkie wiersze w arkuszu „Sheet1”:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId /values/Sheet1
Odpowiedź na to żądanie ma strukturę podobną do tej:
{
"range": "Sheet1",
"majorDimension": "ROWS",
"values": [["Name", "Hours", "Items", "IPM"],
["Bingley", "10", "2", "0.0033"],
["Darcy", "14", "6", "0.0071"]]
}Podczas pobierania całych wierszy, kolumn lub arkuszy nie są uwzględniane ostatnie puste komórki.
Interfejs Sheets API w wersji 4 nie ma odpowiedników parametrów zapytania o kolejność wierszy, które są dostępne w interfejsie Sheets API w wersji 3. Odwrócenie kolejności jest proste: po prostu przetwórz zwróconą tablicę values w odwrotnej kolejności. Kolumna „Sortowanie według” nie jest obsługiwana w przypadku odczytu, ale można posortować dane w arkuszu (za pomocą żądania SortRange) i następnie je odczytać.
Interfejs Sheets API v4 nie ma obecnie bezpośredniego odpowiednika zapytań uporządkowanych interfejsu Sheets API v3. Możesz jednak pobierać odpowiednie dane i sortować je w swojej aplikacji.
Dodawanie nowego wiersza danych
Możesz dodać nowy wiersz danych do arkusza, korzystając z dowolnego interfejsu API.
Aby określić adres URL pliku danych opartego na liście dla danego arkusza, pobierz plik danych arkusza i znajdź adres URL przesłania w odpowiednim wpisie arkusza.
Aby dodać wiersz danych, wyślij żądanie POST do adresu URL postu, używając odpowiedniego nagłówka autoryzacji. Na przykład:
POST https://spreadsheets.google.com/feeds/list/spreadsheetId /sheetId /private/full
Treść żądania POST powinna zawierać wpis z danymi wiersza do dodania, w którym poszczególne komórki są odwoływane za pomocą nagłówków kolumn:
<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>
Nowe wiersze są dodawane na końcu wybranego arkusza.
Za pomocą interfejsu Sheets API w wersji 4 możesz dołączać wiersze za pomocą metody spreadsheets.values.append. W tym przykładzie nowy wiersz danych jest zapisywany pod ostatnią tabelą w arkuszu „Sheet1”.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId /append/Sheet1
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}Interfejs Sheets API w wersji 4 umożliwia też dołączanie komórek z określonymi właściwościami i formatowaniem za pomocą żądań AppendCells w ramach żądania spreadsheets.batchUpdate.
Edytowanie wiersza za pomocą nowych danych
Oba interfejsy API umożliwiają aktualizowanie danych wiersza za pomocą nowych wartości.
Aby edytować wiersz danych, sprawdź plik danych listy i znajdź wpis dla wiersza, który chcesz zaktualizować. W razie potrzeby zaktualizuj zawartość tego wpisu. Upewnij się, że wartość identyfikatora w używanym wpisie dokładnie odpowiada identyfikatorowi istniejącego wpisu.
Po zaktualizowaniu wpisu wyślij żądanie PUT z odpowiednim wpisem jako treścią żądania do adresu URL edit podanego w tym wierszu, używając odpowiedniego nagłówka autoryzacji. Na przykład:
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>
Za pomocą interfejsu Sheets API w wersji 4 możesz edytować wiersz, używając notacji A1 wiersza, który chcesz edytować, i wysyłając prośbę spreadsheets.values.update, aby zastąpić ten wiersz. Zakres musi odnosić się tylko do pierwszej komórki w wierszu; interfejs API określa komórki do zaktualizowania na podstawie wartości podanych w żądaniu. Jeśli zamiast tego określisz zakres obejmujący wiele komórek, podane wartości muszą mieścić się w tym zakresie. W przeciwnym razie interfejs API zwróci błąd.
W tym przykładowym żądaniu i treści żądania dodawane są dane do czwartego wiersza arkusza „Sheet1”:
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId /values/Sheet1!A4
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}Dane wiersza możesz też zaktualizować za pomocą metody spreadsheet.values.batchUpdate. Jest to bardziej wydajne, jeśli chcesz zaktualizować wiele wierszy lub komórek.
Interfejs Sheets API w wersji 4 umożliwia też edytowanie właściwości komórek i formatowania komórek za pomocą żądań UpdateCells lub RepeatCell w ramach żądania spreadsheets.batchUpdate.
Usuwanie wiersza
Oba interfejsy API obsługują usuwanie wierszy. Usunięto wiersz z arkusza kalkulacyjnego, a wiersze poniżej niego przesunięto o jeden w górę.
Aby usunąć wiersz, najpierw pobierz go z pliku danych listy, a potem wyślij żądanie DELETE pod adres URL edit podany w danych wiersza.
Jest to ten sam adres URL, który został użyty do zaktualizowania wiersza.
DELETE https://spreadsheets.google.com/feeds/list/spreadsheetId /sheetId /private/full/rowId /version
Jeśli chcesz mieć pewność, że nie usuniesz wiersza, który został zmieniony przez innego klienta od czasu jego pobrania, dodaj nagłówek HTTP If-Match zawierający wartość ETag oryginalnego wiersza. Wartość ETag oryginalnego wiersza możesz określić, sprawdzając atrybut gd:etag elementu entry.
Jeśli chcesz usunąć wiersz niezależnie od tego, czy ktoś inny go zaktualizował od czasu jego pobrania, użyj If-Match: * i nie dodawaj ETag. (w tym przypadku nie musisz pobierać wiersza przed jego usunięciem).
Usuwanie wierszy za pomocą interfejsu Sheets API w wersji 4 odbywa się przez wywołanie metody spreadsheet.batchUpdate z żądaniem DeleteDimension. Za pomocą tej metody można też usuwać kolumny, a deweloperzy mogą zdecydować się na usunięcie tylko części wiersza lub kolumny. Na przykład poniższy kod usuwa 6. wiersz arkusza o podanym identyfikatorze (indeksy wierszy są liczone od zera, a startIndex zawiera startIndex, a endIndex nie zawiera):
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId :batchUpdate
{
"requests": [
{
"deleteDimension": {
"range": {
"sheetId": sheetId ,
"dimension": "ROWS",
"startIndex": 5,
"endIndex": 6
}
}
}
],
}Wartość sheetId arkusza można pobrać za pomocą metody spreadsheet.get.
Pobieranie danych komórki
Interfejs Sheets API w wersji 3 udostępnia kanał komórek, który zapewnia podstawowy dostęp do wszystkich danych przechowywanych w arkuszu kalkulacyjnym. W przypadku dostępu tylko do odczytu kanał danych komórek może zawierać całą zawartość arkusza lub zakres komórek arkusza zdefiniowany przez zestaw parametrów zapytania, ale tylko jako pojedynczy blok – zakresy niespójne muszą być pobierane osobno za pomocą dodatkowych żądań GET.
Interfejs Sheets API w wersji 4 może pobierać dowolny zbiór danych komórek z arkusza (w tym wiele nieciągłych zakresów). Interfejs Sheets API w wersji 3 może zwracać tylko zawartość komórki jako wartości wejściowe (wpisane przez użytkownika na klawiaturze) lub wyniki formuły (jeśli jest liczbowa). Interfejs Sheets API w wersji 4 zapewnia pełny dostęp do wartości, formuł, formatowania, hiperłączy, walidacji danych i innych właściwości.
Aby określić adres URL pliku danych opartego na komórkach dla danego arkusza, przejrzyj plik danych arkusza i znajdź adres URL pliku danych komórek w odpowiednim wpisie arkusza.
Aby pobrać plik danych oparty na komórkach, wyślij żądanie GET do adresu URL pliku danych opartego na komórkach, używając odpowiedniego nagłówka autoryzacji. Na przykład:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId /sheetId /private/full
Odwołania do komórek są podawane za pomocą numeru wiersza i kolumny. Aby pobrać jeden konkretny zakres, użyj parametrów zapytania max-row, min-row, max-col i min-col. Na przykład ta formuła pobiera wszystkie komórki z kolumny
4 (D), zaczynając od wiersza 2:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId /sheetId /private/full ?min-row=2&min-col=4&max-col=4
Interfejs Sheets API w wersji 3 zwraca inputValue pobranych komórek – wartość, którą użytkownik wpisuje w interfejsie Google Sheets, aby zmienić komórkę. Wartość inputValue może być wartością dosłowną lub formułą. Interfejs API zwraca też czasami wartość numericValue, na przykład gdy formuła zwraca liczbę. Odpowiedź może na przykład zawierać wpisy komórek o podobnej strukturze:
<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>
Pobierz dane komórki, wywołując metodę spreadsheets.values.get lub spreadsheets.values.batchGet odpowiednio dla zakresu lub zakresów, które Cię interesują. Na przykład poniższy wiersz zwraca komórki w kolumnie D w arkuszu „Sheet2”, zaczynając od wiersza 2, w kolejności od kolumny do wiersza i zwracając formuły w postaci wpisanej (puste komórki na końcu są pomijane):
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId /values/Sheet2!D2:D?majorDimension=COLUMNS&valueRenderOption=FORMULA
Odpowiedź na to żądanie ma podobną strukturę do tej:
{
"spreadsheetId": spreadsheetId ,
"valueRanges": [
{"range": "Sheet2!D2:D",
"majorDimension": "COLUMNS",
"values": [["Widget", 234, "=FLOOR(C4/(B4*60),.0001)", "=D4\*1000"]]
}]
}Jeśli chcesz pobrać wiele zakresów danych komórek, wydajniej jest użyć funkcji spreadsheet.values.batchGet. Jeśli chcesz uzyskać dostęp do właściwości komórki, takich jak formatowanie, musisz użyć metody spreadsheet.get.
Edytowanie komórki
Interfejs Sheets API w wersji 3 umożliwia edytowanie zawartości komórki przez wysłanie do pliku danych komórek polecenia PUT, którego treść to zmodyfikowany wpis komórki.
Interfejs Sheets API w wersji 4 udostępnia natomiast metody spreadsheets.values.update i spreadsheets.values.batchUpdate do zmiany zawartości komórek.
Aby edytować zawartość pojedynczej komórki, najpierw znajdź jej wpis w pliku danych komórki.
Wpis zawiera adres URL do edycji. Zaktualizuj wpis, aby odzwierciedlał zawartość, którą chcesz mieć w komórce, a następnie wyślij PUT do adresu URL edycji z zaktualizowanym wpisem komórki jako treścią żądania. Na przykład poniższe polecenie zaktualizuje komórkę D2 (R2C4), aby zawierała formułę 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>
Edytowanie pojedynczej komórki w interfejsie Sheets API w wersji 4 można wykonać za pomocą metody spreadsheets.values.update. Ta metoda wymaga parametru zapytania ValueInputOption, który określa, czy dane wejściowe są traktowane tak, jakby zostały wprowadzone w interfejsie Arkuszy (USER_ENTERED), czy pozostawione bez analizy i pobrane w obecnej postaci (RAW). Na przykład poniższa formuła aktualizuje komórkę D2:
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId /values/D2?valueInputOption=USER_ENTERED
{"values": [["=SUM(A1:B6)"]]}Jeśli wprowadzasz zmiany w wielu komórkach, użyj metody spreadsheets.values.batchUpdate, aby wprowadzić je w jednym żądaniu.
Edytowanie wielu komórek za pomocą żądania zbiorczego
Oba interfejsy API umożliwiają wprowadzanie zmian w treści wielu komórek za pomocą pojedynczego żądania zbiorczego. Komórki, do których odwołuje się żądanie zbiorcze, nie muszą znajdować się w ciągłym zakresie.
Jeśli co najmniej 1 edycja komórki w zbiorze zakończy się niepowodzeniem, interfejs Sheets API w wersji 3 umożliwi wykonanie pozostałych edycji. Jednak interfejs Sheets API w wersji 4 zwraca błąd, jeśli któreś z pakietowych aktualizacji się nie powiedzie, i nie stosuje żadnej z nich.
Aby edytować wiele komórek, najpierw pobierz plik danych komórek dla arkusza. Wpis zawiera adres URL zbiorczy. Wyślij POSTżądanie do tego adresu URL wraz z treścią żądania zawierającą opis komórek, które chcesz zaktualizować, oraz nową zawartość komórek. Żądanie POST i jego treść mają strukturę podobną do tej:
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>
Pole batch:id powinno jednoznacznie identyfikować żądanie w ramach zbiorczego zgłoszenia.
W przypadku edycji komórek pole batch:operation powinno mieć wartość update. gs:cellidentyfikuje komórkę według numeru wiersza i kolumny oraz podaje nowe dane do wstawienia. id zawiera pełny adres URL komórki, która ma zostać zaktualizowana.
Element link musi zawierać atrybut href, który zawiera pełną ścieżkę do identyfikatora komórki. W przypadku każdego wpisu wszystkie te pola są wymagane.
Interfejs Sheets API w wersji 4 umożliwia zbiorczą edycję wartości komórek za pomocą metody spreadsheets.values.batchUpdate.
Aby edytować wiele komórek, wyślij żądanie POST z zmianami danych określonymi w ciele żądania. Na przykład:
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"]]
}
]
}Jeśli jako zakres podano pojedynczą komórkę, wszystkie podane wartości zostaną zapisane na arkuszu, zaczynając od lewego górnego rogu tej komórki. Jeśli zamiast tego określisz zakres obejmujący wiele komórek, podane wartości muszą dokładnie pasować do tego zakresu. W przeciwnym razie interfejs API zwróci błąd.