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 równoważne operacje w interfejsie Sheets API w wersji 4. Mapowanie koncentruje się głównie na zbiorze spreadsheets.values, który zapewnia bezpośrednią obsługę 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ą zgodne z strukturami XML używanymi w wersji 3.
Więcej informacji o zasobach dostępnych w interfejsie Sheets API 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 być modyfikowany. Te wartości pojawiają się w ramach adresu URL punktu końcowego interfejsu API, jako parametry zapytania lub w ramach treści żą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 jakie uprawnienia prosi.
interfejs API v3,
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 API w wersji 4
Interfejs Sheets API w wersji 4 używa 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 ani 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 API v3,
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
Interfejs API w wersji 4
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 zwracanych 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.
interfejs API v3,
W interfejsie Sheets API w wersji 3 dostępne są tylko 2 ustawienia projekcji. Projekcja full zwraca wszystkie dostępne informacje, a basic zwraca mniejszy, stały podzbiór danych (w przypadku arkuszy kalkulacyjnych, list i 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 dostosować.
Interfejs API w wersji 4
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 API v3,
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 Drive API Files.create. Wymaga to zadeklarowania w aplikacji zakresu https://www.googleapis.com/auth/drive.
Interfejs API w wersji 4
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
interfejs API v3,
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 API w wersji 4
Interfejs Sheets API w wersji 4 nie obsługuje tej operacji. Zalecamy przeniesienie aplikacji na użycie zakresu 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, używając 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.
Metoda spreadsheets.get interfejsu Sheets API w wersji 4 zapewnia dostęp do tych informacji i wielu innych.
interfejs API v3,
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 każdego arkusza znajdują się 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>
Interfejs API w wersji 4
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 arkuszy i ich rozmiarze 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 API v3,
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>
Interfejs API w wersji 4
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 w wersji 3 umożliwia aktualizowanie tytułów i rozmiaru arkuszy. Interfejs Sheets API w wersji 4 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.
interfejs API v3,
Aby zmienić tytuł lub rozmiar arkusza, zacznij od pobrania pliku danych arkusza i odnalezienia 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>
Interfejs API w wersji 4
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 należy zaktualizować właściwości tytułu i rozmiaru arkusza o identyfikatorze:
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.
interfejs API v3,
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
Interfejs API w wersji 4
Aby usunąć arkusz, prześlij żądanie DeleteSheet za pomocą metody 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.
interfejs API v3,
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:lastnameInterfejs 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<175Interfejs API w wersji 4
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 kod 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 puste komórki na końcu nie są uwzględniane w odpowiedzi.
Interfejs Sheets API v4 nie ma odpowiedników parametrów zapytania o kolejność wierszy, które są dostępne w interfejsie Sheets API v3. Odwrócenie kolejności jest proste: po prostu przetwórz zwróconą tablicę values w odwrotnej kolejności. Kolumna „Sortuj według” nie jest obsługiwana w przypadku odczytu, ale można posortować dane w arkuszu (za pomocą żądania SortRange), a 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.
interfejs API v3,
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.
Interfejs API w wersji 4
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.
interfejs API v3,
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 wpisem jako treść żą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>
Interfejs API w wersji 4
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 żądanie spreadsheets.values.update, aby zastąpić ten wiersz. Zakres musi dotyczyć tylko 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.
Dodatkowo interfejs Sheets API w wersji 4 umożliwia 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ę.
interfejs API v3,
Aby usunąć wiersz, najpierw pobierz go z pliku danych listy, a potem wyślij żądanie DELETE pod adresem URL edit podanym 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 polecenia If-Match: * i nie dodawaj etykiety ETag. (w tym przypadku nie musisz pobierać wiersza przed jego usunięciem).
Interfejs API w wersji 4
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ą usunąć tylko część wiersza lub kolumny. Na przykład poniższy kod usuwa 6. wiersz arkusza o danym identyfikatorze (indeksy wierszy są liczone od zera, a startIndex jest większy od zera, a mniejszy od endIndex):
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.
interfejs API v3,
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 opartych 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=4Interfejs 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 w komórkach o strukturze podobnej do tej:
<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>
Interfejs API w wersji 4
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 kod zwraca komórki w kolumnie D arkusza „Sheet2”, zaczynając od wiersza 2, w kolejności od kolumny do wiersza i zwraca formuły w takiej postaci, w jakiej zostały wprowadzone (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:
{
"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ść żądania stanowi zmodyfikowany wpis komórki.
Z kolei interfejs Sheets API w wersji 4 udostępnia metody spreadsheets.values.update i spreadsheets.values.batchUpdate do zmiany zawartości komórek.
interfejs API v3,
Aby edytować zawartość pojedynczej komórki, najpierw znajdź jej wpis w pliku danych komórek.
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>
Interfejs API w wersji 4
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 mają być traktowane tak, jakby zostały wprowadzone w interfejsie Arkuszy (USER_ENTERED), czy pozostawione w niezanalizowanej formie (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 aktualizacji zbiorczych się nie powiedzie, i nie stosuje żadnej z nich.
interfejs API v3,
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 przesyłania.
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 API w wersji 4
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, możesz wysłać żądanie POST z danymi zmianami 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.