Jeśli masz aplikacje oparte na interfejsie Google Sheets API w wersji 3, możesz przejść na interfejs Google Sheets API w wersji 4. Wersja 4 jest oparta na formacie JSON, ma łatwiejszy w obsłudze interfejs i zawiera wiele funkcji, które nie są dostępne w wersji 3.
Na tej stronie znajdziesz 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średnie funkcje odczytu i zapisu komórek. Inne aspekty, takie jak dodawanie arkuszy czy aktualizowanie ich właściwości, są obsługiwane przez kolekcję spreadsheets. 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 Google w wersji 4 znajdziesz w dokumentacji interfejsu API.
Oznaczenia i terminy
Interfejs API w wersji 3 określa arkusze w ramach konkretnego arkusza kalkulacyjnego jako „arkusze”. Jest to synonim terminu „arkusze” używanego w interfejsie 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 jest modyfikowany. Te wartości pojawiają się w adresie URL punktu końcowego interfejsu API, jako parametry zapytania lub w treści żądania. Na tej stronie symbole zastępcze spreadsheetId i sheetId oznaczają odpowiednio identyfikatory arkusza kalkulacyjnego i arkusza. Jeśli korzystasz z metod opisanych na tej stronie, w tych miejscach wstaw rzeczywiste identyfikatory.
Interfejs API w wersji 3 przypisuje też identyfikator do wierszy pobranych za pomocą listy. Na tej stronie jest on reprezentowany przez symbol zastępczy rowId.
Autoryzowanie żądań
Gdy aplikacja jest uruchomiona, prosi użytkowników o przyznanie określonych uprawnień. Zakresy określone w aplikacji decydują o to, o jakie uprawnienia będzie ona prosić.
API w wersji 3
Interfejs Sheets API w wersji 3 działa w ramach jednego zakresu autoryzacji:
https://spreadsheets.google.com/feeds
który jest aliasem
https://www.googleapis.com/auth/spreadsheets
Możesz użyć dowolnego formatu zakresu.
Interfejs API w wersji 4
Interfejs Sheets API w wersji 4 korzysta z co najmniej jednego z tych 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
Jeśli aplikacja nie musi wprowadzać zmian w arkuszach użytkownika ani w ich właściwościach, używaj zakresów tylko do odczytu. Jeśli aplikacja nie potrzebuje ogólnego dostępu do Dysku, używaj zakresów arkuszy kalkulacyjnych zamiast zakresów Dysku.
Widoczność
W starszych wersjach interfejsu API termin visibility (widoczność) odnosi się do dostępności danego arkusza kalkulacyjnego.
API w wersji 3
Interfejs Arkuszy API w wersji 3 wyraża widoczność bezpośrednio w swoich punktach końcowych. Arkusz kalkulacyjny public został „opublikowany w internecie”, więc można uzyskać do niego dostęp za pomocą interfejsu API bez autoryzacji, natomiast arkusz private wymaga uwierzytelniania. Widoczność jest określona w punkcie końcowym po identyfikatorze arkusza kalkulacyjnego:
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
Interfejs API w wersji 4
W nowym interfejsie Sheets API w wersji 4 nie ma wyraźnej deklaracji widoczności. Wywołania interfejsu API są wykonywane przy użyciu 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 zostanie nawiązane.
Odwzorowanie
Termin projekcja jest używany w interfejsie Sheets API w wersji 3 do określania zbioru danych zwracanego przez dane wywołanie interfejsu API – wszystkich danych lub stałego podzbioru zdefiniowanego w interfejsie API. Interfejs Sheets API w wersji 4 nie używa projekcji, ale daje większą kontrolę nad tym, jakie dane są zwracane.
API w wersji 3
W interfejsie Arkuszy API w wersji 3 dostępne są tylko 2 ustawienia projekcji. full
projection zwraca wszystkie dostępne informacje, a basic zwraca mniejszy, stały podzbiór danych (w przypadku arkuszy, list i komórek).
Podobnie jak widoczność, projekcję należy określić 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 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 arkuszy kalkulacyjnych 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
API w wersji 3
Interfejs Sheets API w wersji 3 nie umożliwia tworzenia nowych arkuszy kalkulacyjnych. Zamiast tego można użyć metody Files.create interfejsu Drive API do tworzenia nowych plików arkuszy kalkulacyjnych. Wymaga to zadeklarowania przez aplikację 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 podania przez aplikację zakresu https://www.googleapis.com/auth/drive.
Odpowiednikiem tej metody jest metoda spreadsheets.create w interfejsie Sheets API w wersji 4, która może też opcjonalnie dodawać arkusze, ustawiać właściwości arkusza kalkulacyjnego i arkusza oraz dodawać nazwane zakresy. 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"}
}Tworzenie listy arkuszy dla uwierzytelnionego użytkownika
API w wersji 3
Plik danych interfejsu Sheets API w wersji 3 umożliwia aplikacji pobranie listy wszystkich arkuszy kalkulacyjnych dostępnych dla uwierzytelnionego użytkownika. Punkt końcowy pliku danych w arkuszu kalkulacyjnym to:
GET https://spreadsheets.google.com/feeds/spreadsheets/private/full
Interfejs API w wersji 4
Interfejs Sheets API w wersji 4 nie udostępnia tej konkretnej operacji. Zalecamy migrację aplikacji, aby korzystała z zakresu drive.file w połączeniu z selektorem plików Google do wybierania arkuszy kalkulacyjnych.
W przypadku, gdy wymagane jest wyświetlenie listy arkuszy, można to zrobić przy użyciu 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 Arkuszy API w wersji 3 udostępnia plik danych, który umożliwia dostęp do metadanych arkusza zawartych w danym arkuszu kalkulacyjnym (dostęp do danych wierszy i komórek jest uzyskiwany za pomocą osobnego pliku danych). Metadane zawierają informacje takie jak tytuły arkuszy i rozmiar.
Metoda spreadsheets.get interfejsu Sheets API w wersji 4 zapewnia dostęp do tych i wielu innych informacji.
API w wersji 3
Plik arkusza jest dostępny w tym punkcie końcowym interfejsu API (z użyciem 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 uzyskiwania właściwości arkusza i innych metadanych, czyli znacznie więcej niż w przypadku interfejsu Sheets API w wersji 3. Jeśli chcesz tylko odczytać właściwości arkusza, ustaw parametr zapytania includeGridData na false, aby zapobiec uwzględnianiu danych komórek arkusza kalkulacyjnego:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?includeGridData=false
Odpowiedź Spreadsheet zawiera tablicę obiektów Sheet. Tytuły arkuszy i informacje o rozmiarze można znaleźć 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.
API w wersji 3
Interfejs Sheets API w wersji 3 może dodawać nowe arkusze do arkusza kalkulacyjnego, wysyłając to (uwierzytelnione) żądanie 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
Możesz dodawać nowe arkusze, wysyłając żądanie AddSheet w metodzie spreadsheets.batchUpdate. W treści żądania możesz określić właściwości nowego arkusza. Wszystkie właściwości są opcjonalne. Podanie tytułu, który jest używany w przypadku istniejącego arkusza, jest błędem.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [{
"addSheet": {
"properties": {
"title": "Expenses",
"sheetType": "GRID",
"gridProperties": {
"rowCount": 50,
"columnCount": 10
}
}
}
}],
}Zmiana tytułu i rozmiaru arkusza
Interfejs Sheets API w wersji 3 umożliwia aktualizowanie tytułów i rozmiarów arkuszy. Interfejs Sheets API w wersji 4 również to umożliwia, ale można go też używać do aktualizowania innych właściwości arkusza. Pamiętaj, że zmniejszenie rozmiaru arkusza może spowodować usunięcie danych z przyciętych komórek bez ostrzeżenia.
API w wersji 3
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 wyślij je jako treść PUTżądania na adres 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 w metodzie spreadsheets.batchUpdate. Treść żądania POST powinna zawierać właściwości, które mają zostać zmienione, a parametr fields powinien wyraźnie je wymieniać (jeśli chcesz zaktualizować wszystkie właściwości, użyj fields:"*" jako skrótu do ich wszystkich). Na przykład poniższy kod określa, że należy zaktualizować właściwości tytułu i rozmiaru arkusza o podanym 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ć sheetIdarkusza, użyj metody arkusza kalkulacyjnego spreadsheets.get.
Usuwanie arkusza
Oba interfejsy API mogą usuwać arkusze z danego arkusza kalkulacyjnego.
API w wersji 3
Aby usunąć arkusz, najpierw pobierz plik danych arkusza, a następnie wyślij żądanie DELETE na adres URL edit docelowego wpisu arkusza.
DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
Interfejs API w wersji 4
Aby usunąć arkusz, wyślij żądanie DeleteSheet w metodzie spreadsheets.batchUpdate. Treść żądania POST powinna zawierać tylko sheetId arkusza do usunięcia. 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 udostępnianych przez interfejs 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 wierszy ma obsługiwać typowe operacje na arkuszach kalkulacyjnych (odczytywanie wierszy, dołączanie wierszy, sortowanie), ale zawiera pewne założenia, które sprawiają, że nie nadaje się do niektórych zadań. W szczególności plik danych listy zakłada, że puste wiersze oznaczają koniec pliku danych, a w pierwszym wierszu arkusza znajdują się obowiązkowe nagłówki.
Natomiast interfejs Sheets API w wersji 4 nie używa metod dostępu, które są specyficzne dla wiersza. Zamiast tego dostęp do danych w komórkach arkusza uzyskuje się przez odwoływanie się do konkretnych zakresów za pomocą notacji A1. Zakresy mogą być blokami komórek, całymi wierszami, całymi kolumnami lub całymi arkuszami. Interfejs API może też uzyskiwać dostęp do rozłącznych zbiorów komórek.
API w wersji 3
Aby określić adres URL kanału opartego na liście dla danego arkusza, pobierz kanał arkusza i znajdź adres URL kanału listy w interesującym Cię wpisie arkusza.
Aby pobrać plik danych oparty na liście, wyślij żądanie GET na adres URL pliku danych opartego na 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 poszczególnym wierszom. Poszczególne komórki są określane za pomocą nazw podanych w (obowiązkowym) wierszu nagłówka arkusza. Oto przykład wpisu w jednym 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 Arkuszy API w wersji 3 udostępnia parametry zapytania, które pozwalają zmienić kolejność.
Odwrotna kolejność:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full?reverse=true
Sortowanie według określonej 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ą uporządkowanego zapytania (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
Za pomocą interfejsu Sheets API w wersji 4 można pobierać wiersze według zakresu, korzystając z metod spreadsheets.values.get lub spreadsheets.values.batchGet. Na przykład poniższe polecenie zwraca wszystkie wiersze w arkuszu „Arkusz1”:
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 dotyczących kolejności wierszy, które są dostępne w interfejsie Sheets API v3. Odwrócenie kolejności jest proste: wystarczy przetworzyć zwróconą tablicę values w odwrotnej kolejności. Sortowanie według kolumny nie jest obsługiwane 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 dla zapytań strukturalnych interfejsu Sheets API v3. Możesz jednak pobrać odpowiednie dane i w razie potrzeby posortować je w aplikacji.
Dodawanie nowego wiersza danych
Nowy wiersz danych możesz dodać do arkusza za pomocą dowolnego interfejsu API.
API w wersji 3
Aby określić adres URL kanału opartego na liście dla danego arkusza, pobierz kanał arkusza i znajdź adres URL posta w interesującym Cię wpisie arkusza.
Aby dodać wiersz danych, wyślij żądanie POST na adres URL posta,
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, z poszczególnymi komórkami, do których odwołuje się nagłówek kolumny:
<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 określonego arkusza.
Interfejs API w wersji 4
Za pomocą interfejsu Sheets API w wersji 4 możesz dodawać wiersze przy użyciu metody spreadsheets.values.append. W tym przykładzie zapisujemy nowy wiersz danych poniżej ostatniej tabeli w arkuszu „Arkusz1”.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}Dodatkowo interfejs Arkuszy API w wersji 4 umożliwia dołączanie komórek o określonych właściwościach i formatowaniu za pomocą żądań AppendCells w spreadsheets.batchUpdate.
Edytowanie wiersza za pomocą nowych danych
Oba interfejsy API umożliwiają aktualizowanie danych wierszy za pomocą nowych wartości.
API w wersji 3
Aby edytować wiersz danych, sprawdź plik danych z listą, aby znaleźć wpis w wierszu, 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ścią żądania na adres URL edit podany 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
Interfejs Sheets API w wersji 4 umożliwia edytowanie wiersza przy użyciu notacji A1 wiersza, który chcesz edytować, i wysłanie żądania spreadsheets.values.update w celu zastąpienia tego wiersza. Określony zakres musi odnosić się tylko do pierwszej komórki w wierszu. Interfejs API wnioskuje, które komórki należy zaktualizować, na podstawie wartości podanych w żądaniu. Jeśli zamiast tego określisz zakres wielu komórek, podane wartości muszą się w nim mieścić. W przeciwnym razie interfejs API zwróci błąd.
Ten przykładowy kod żądania i treści żądania dodaje dane do czwartego wiersza arkusza „Arkusz1”:
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A4
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}Możesz też aktualizować dane wierszy za pomocą metody spreadsheet.values.batchUpdate. Jest ona bardziej wydajna, jeśli wprowadzasz wiele zmian w wierszach lub komórkach.
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 spreadsheets.batchUpdate.
Usuwanie wiersza
Oba interfejsy API obsługują usuwanie wierszy. Usunięty wiersz jest usuwany z arkusza kalkulacyjnego, a wiersze poniżej są przesuwane o jeden wiersz w górę.
API w wersji 3
Aby usunąć wiersz, najpierw pobierz go z pliku danych listy, a następnie wyślij żądanie DELETE na adres URL edit podany we wpisie wiersza.
Jest to ten sam adres URL, który służy do aktualizowania 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, dołącz nagłówek HTTP If-Match, który zawiera oryginalną wartość ETag wiersza. Oryginalną wartość ETag 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, gdy został przez Ciebie pobrany, użyj If-Match: * i nie uwzględniaj tagu 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 za pomocą żądania DeleteDimension. Za pomocą tej prośby można też usuwać kolumny. Deweloperzy mogą też usuwać tylko część wiersza lub kolumny. Na przykład poniższy kod usuwa 6 wiersz arkusza o podanym identyfikatorze (indeksy wierszy są oparte na zerze, a startIndex jest włączony, a endIndex wyłączony):
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteDimension": {
"range": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 5,
"endIndex": 6
}
}
}
],
}sheetId arkusza można pobrać za pomocą metody spreadsheet.get.
Pobieranie danych z komórki
Interfejs Arkuszy w wersji 3 udostępnia kanał komórek, który umożliwia podstawowy dostęp do wszystkich danych przechowywanych w arkuszu kalkulacyjnym. W przypadku dostępu do odczytu kanał komórek może udostępniać całą zawartość arkusza lub zakres komórek arkusza zdefiniowany przez zestaw parametrów zapytania, ale tylko jako pojedynczy blok – rozłączne zakresy muszą być pobierane oddzielnie za pomocą dodatkowych żądań GET.
Interfejs Arkuszy Google API w wersji 4 może pobrać dowolny zestaw danych z komórek arkusza (w tym wiele rozłącznych zakresów). Interfejs Sheets API w wersji 3 może zwracać tylko zawartość komórek jako wartości wejściowe (takie, jakie użytkownik wpisuje z klawiatury) lub wyniki formuł (jeśli są to wartości liczbowe). Interfejs Sheets API w wersji 4 zapewnia pełny dostęp do wartości, formuł, formatowania, hiperlinków, weryfikacji danych i innych właściwości.
API w wersji 3
Aby określić adres URL pliku danych opartego na komórkach dla danego arkusza, sprawdź plik danych arkusza i znajdź adres URL pliku danych opartego na komórkach w interesującym Cię wpisie arkusza.
Aby pobrać plik danych oparty na komórkach, wyślij żądanie GET na adres URL pliku danych komórek, używając odpowiedniego nagłówka autoryzacji. Na przykład:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
Do komórek odwołuje się za pomocą numeru wiersza i kolumny. Pobieranie pojedynczego zakresu można przeprowadzić za pomocą parametrów zapytania max-row, min-row, max-col i min-col. Na przykład poniższe polecenie pobiera wszystkie komórki w kolumnie 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, czyli wartość, którą użytkownik wpisałby w interfejsie Google Sheets, aby manipulować komórką. Wartość inputValue może być wartością literalną lub formułą. Interfejs API czasami zwraca też wartość numericValue, np. gdy formuła daje w wyniku 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 z komórek, 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ższa formuła zwraca komórki w kolumnie D arkusza „Arkusz2”, zaczynając od wiersza 2, w kolejności kolumnowej i zwraca formuły w takiej postaci, w jakiej zostały wpisane (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 strukturę podobną 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 z komórek, wydajniej jest użyć metody spreadsheet.values.batchGet. Jeśli chcesz uzyskać dostęp do właściwości komórek, takich jak formatowanie, musisz użyć metody spreadsheet.get.
Edytowanie komórki
Interfejs Arkuszy API w wersji 3 umożliwia edytowanie zawartości komórek przez wysłanie polecenia PUT do pliku danych komórek ze zmodyfikowanym wpisem komórki jako treścią żądania.
Interfejs Sheets API w wersji 4 udostępnia natomiast metody spreadsheets.values.update i spreadsheets.values.batchUpdate do zmiany zawartości komórek.
API w wersji 3
Aby edytować zawartość pojedynczej komórki, najpierw znajdź wpis tej komórki w pliku danych komórek.
Wpis zawiera adres URL do edycji. Zaktualizuj wpis, aby odzwierciedlał zawartość, którą ma zawierać komórka, a następnie wyślij żądanie PUT na adres URL edycjiPUT z zaktualizowanym wpisem w komórce jako treścią żądania. Na przykład poniższy kod aktualizuje 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 przeprowadzić 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 wpisane w interfejsie Arkuszy (USER_ENTERED), czy też pozostawione bez analizy i traktowane jako takie (RAW). Na przykład poniższy kod aktualizuje komórkę D2 za pomocą formuły:
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/D2?valueInputOption=USER_ENTERED
{"values": [["=SUM(A1:B6)"]]}Jeśli wprowadzasz wiele zmian w komórkach, użyj metody spreadsheets.values.batchUpdate, aby wysłać 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ą jednego żądania (zbiorczego). Komórki, do których odnosi się żądanie zbiorcze, nie muszą znajdować się w ciągłym zakresie.
Jeśli co najmniej 1 zmiana komórki w partii nie powiedzie się, interfejs Arkuszy API w wersji 3 zezwoli na wykonanie pozostałych zmian. Jeśli jednak któraś z aktualizacji w pakiecie się nie powiedzie, interfejs Sheets API w wersji 4 zwróci błąd i nie zastosuje żadnej z nich.
API w wersji 3
Aby edytować wiele komórek, najpierw pobierz plik danych komórek arkusza. Wpis zawiera adres URL pliku wsadowego. Wyślij POSTżądanie na ten adres URL wraz z treścią żądania opisującą komórki, które chcesz zaktualizować, oraz nową zawartość komórek. Żądanie POST i treść żądania
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 partii.
W przypadku edycji komórek pole batch:operation powinno mieć wartość update. gs:cell
określa 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.
link musi mieć atrybut href, który zawiera pełną ścieżkę do identyfikatora komórki. Wszystkie te pola są wymagane w przypadku każdego wpisu.
Interfejs API w wersji 4
Interfejs Sheets API w wersji 4 umożliwia zbiorcze edytowanie wartości komórek za pomocą metody spreadsheets.values.batchUpdate.
Edytowanie wielu komórek można przeprowadzić, wysyłając żądanie POST ze zmianami danych określonymi w treści żą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 jedną komórkę, wszystkie podane wartości zostaną zapisane w arkuszu, zaczynając od tej komórki jako współrzędnej w lewym górnym rogu. Jeśli zamiast tego określisz zakres wielu komórek, podane wartości muszą dokładnie pasować do tego zakresu. W przeciwnym razie interfejs API zwróci błąd.