Jeśli masz już aplikacje oparte na interfejsie Google Sheets API w wersji 3, możesz przeprowadzić migrację na interfejs Google Sheets API w wersji 4. Wersja 4 jest oparta na formacie JSON, ma łatwiejszy w użyciu interfejs i oferuje wiele funkcji niedostępnych w wersji 3.
Na tej stronie znajduje się mapowanie między starszymi poleceniami interfejsu API Arkuszy w wersji 3 i ich odpowiednikami w interfejsie Arkuszach Google w wersji 4. Mapowanie skupia się głównie na kolekcji spreadsheets.values, która udostępnia funkcje bezpośredniego odczytu i zapisu komórek. Inne aspekty, takie jak dodawanie arkuszy lub aktualizowanie właściwości arkusza, są obsługiwane przez kolekcję arkuszy kalkulacyjnych. Pamiętaj, że struktury JSON interfejsu API w wersji 4 nie są zgodne wstecznie ze strukturami XML używanymi w wersji 3.
Więcej informacji o zasobach dostępnych w interfejsie Arkuszach Google w wersji 4 znajdziesz w dokumentacji API.
Zapis i warunki
W interfejsie API w wersji 3 arkusze w danym arkuszu kalkulacyjnym są nazywane „arkuszami”. Jest to synonim z terminem „arkusze” używanym w interfejsie API wersji 4.
Interfejsy API często wymagają podania identyfikatora arkusza kalkulacyjnego, z którym pracujesz. Często wymagają też identyfikatora edytowanego arkusza. Wartości te pojawiają się jako część adresu URL punktu końcowego interfejsu API, jako parametry zapytania lub jako część treści żądania. Na tej stronie symbole zastępcze spreadsheetId i sheetId odnoszą się odpowiednio do identyfikatorów arkusza kalkulacyjnego i arkusza. Korzystając z metod opisanych na tej stronie, zastąp rzeczywiste identyfikatory w tych lokalizacjach.
Interfejs API w wersji 3 przypisuje identyfikator do wierszy pobranych za pomocą pliku danych listy. Na tej stronie ten identyfikator jest reprezentowany przez zmienną rowId.
Autoryzowanie żądań
Gdy aplikacja jest uruchamiana, prosi użytkowników o przyznanie pewnych uprawnień. Zakresy określone w aplikacji określają, o jakie uprawnienia chce ona korzystać.
Interfejs API (wersja 3)
Interfejs API Arkuszy w wersji 3 działa z jednym zakresem autoryzacji:
https://spreadsheets.google.com/feeds
który jest aliasem dla
https://www.googleapis.com/auth/spreadsheets
Możesz użyć dowolnego formatu zakresu.
Interfejs API w wersji 4
Interfejs API Arkuszy 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
Jeśli aplikacja nie musi wprowadzać zmian w arkuszach lub właściwościach arkusza użytkownika, używaj zakresów tylko do odczytu. Jeśli aplikacja nie wymaga ogólnego dostępu do Dysku, używaj zakresów arkuszy kalkulacyjnych zamiast zakresów Dysku.
Widoczność
W starszych wersjach interfejsu API określenie widoczność oznacza dostępność danego arkusza kalkulacyjnego.
Interfejs API (wersja 3)
Interfejs Arkuszy API w wersji 3 wyraża widoczność bezpośrednio w swoich punktach końcowych. Arkusz kalkulacyjny public został oznaczony jako „Opublikowano w internecie”, więc można uzyskać do niego dostęp bez autoryzacji, natomiast arkusz kalkulacyjny private wymaga uwierzytelnienia. Widoczność jest podana 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 Arkuszy 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 rozmowa będzie kontynuowana.
Odwzorowanie
Termin projekcja jest używany w interfejsie API Arkuszy w wersji 3 i oznacza zbiór danych zwracanych przez określone wywołanie interfejsu API – wszystkie lub stały podzbiór zdefiniowany w interfejsie API. Interfejs API Arkuszy w wersji 4 nie korzysta z projekcji, lecz daje Ci większą kontrolę nad tym, jakie dane są zwracane.
Interfejs API (wersja 3)
W interfejsie Arkuszach Google w wersji 3 są dostępne tylko 2 ustawienia projekcji. Odwzorowanie full zwraca wszystkie dostępne informacje, natomiast funkcja basic zwraca mniejszy, stały podzbiór danych (w przypadku plików danych z arkuszy, list i komórek).
Podobnie jak widoczność, rzut musi być określony w punkcie końcowym interfejsu API (po ustawieniu widoczności):
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic
Mniejszy podzbiór danych dostarczanych przez projekcję basic pomaga zwiększyć wydajność kodu, ale nie można go dostosować.
Interfejs API w wersji 4
Chociaż interfejs API Arkuszy w wersji 4 może zwracać pełny zbiór danych, nie definiuje stałych podzbiorów analogicznych do ustawienia widoczności basic w interfejsie Arkuszach Google w wersji 3.
Metody w kolekcji arkuszy kalkulacyjnych ograniczają ilość danych zwracanych przez zastosowanie parametru zapytania fields.
Na przykład to zapytanie zwróci 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 (wersja 3)
Interfejs Arkuszy API w wersji 3 nie umożliwia tworzenia nowych arkuszy kalkulacyjnych. Do tworzenia nowych plików arkuszy kalkulacyjnych można natomiast używać metody Files.create interfejsu Drive API. Wymaga to zadeklarowania przez aplikację zakresu https://www.googleapis.com/auth/drive.
Interfejs API w wersji 4
Metody Files.create interfejsu Drive API można też używać w interfejsie Arkuszy API w wersji 4, ale wymaga ona dostarczenia przez aplikację zakresu https://www.googleapis.com/auth/drive.
Alternatywą dla interfejsu API Arkuszy w wersji 4 jest metoda spreadsheets.create – pozwala ona również opcjonalnie dodawać arkusze, określać ich właściwości i zakresy nazwane. Poniższy przykład tworzy nowy arkusz kalkulacyjny o nazwie „NowyTytuł”:
POST https://sheets.googleapis.com/v4/spreadsheets
{
"properties": {"title": "NewTitle"}
}Wyświetlenie listy arkuszy kalkulacyjnych dla uwierzytelnionego użytkownika
Interfejs API (wersja 3)
Plik danych Arkuszy Google w wersji 3 umożliwia aplikacji pobieranie listy wszystkich arkuszy kalkulacyjnych dostępnych dla uwierzytelnionego użytkownika. Punkt końcowy pliku danych arkusza kalkulacyjnego to:
GET https://spreadsheets.google.com/feeds/spreadsheets/private/full
Interfejs API w wersji 4
Interfejs Arkuszach Google w wersji 4 nie umożliwia tej operacji. Zalecamy migrację aplikacji, aby używała zakresu drive.file w połączeniu z selektorem Google do wyboru arkusza kalkulacyjnego.
Jeśli wymagane jest wyświetlanie listy arkuszy kalkulacyjnych, można je odtworzyć za pomocą metody Files.list interfejsu Drive API i zapytania mimeType:
GET https://www.googleapis.com/drive/v3/files
?q=mimeType='application/vnd.google-apps.spreadsheet'
Używanie metody files.list interfejsu Drive API do wyświetlania listy wszystkich arkuszy kalkulacyjnych użytkownika wymaga zakresu z ograniczeniami.
Pobieranie metadanych arkusza
Interfejs API Arkuszy w wersji 3 udostępnia plik danych, który umożliwia dostęp do metadanych arkusza zawartych w danym arkuszu kalkulacyjnym (dane dotyczące wierszy i komórek są dostępne w osobnym pliku danych). Metadane obejmują informacje, takie jak tytuły arkuszy i informacje o rozmiarze.
Metoda spreadsheets.get interfejsu API Arkuszy v4 zapewnia dostęp do tych i wielu innych informacji.
Interfejs API (wersja 3)
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ę, z danymi z każdego arkusza zawartym w osobnym pliku <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
Metoda spreadsheets.get może być używana do pozyskiwania właściwości arkusza i innych metadanych – to znacznie więcej niż w przypadku interfejsu API Arkuszy w wersji 3. Jeśli chcesz tylko odczytać właściwości arkusza, ustaw parametr zapytania includeGridData na false, by zapobiec uwzględnianiu danych komórek w arkuszu kalkulacyjnym:
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.
Interfejs API (wersja 3)
Interfejs API Arkuszy 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 dodać nowe arkusze, wysyłając żądanie AddSheet za pomocą metody 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 użytego 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 Arkuszach Google w wersji 3 umożliwia aktualizowanie tytułów i rozmiarów arkuszy. Interfejs API Arkuszy w wersji 4 też na to zezwala, ale może być też używany do aktualizowania innych właściwości arkuszy. Pamiętaj, że zmniejszenie rozmiaru arkusza może spowodować usunięcie danych w przyciętych komórkach bez ostrzeżenia.
Interfejs API (wersja 3)
Aby zmienić tytuł lub rozmiar arkusza, zacznij od pobrania pliku danych arkusza i znalezienia odpowiedniego wpisu zawierającego adres URL edit.
Zaktualizuj metadane arkusza i wyślij je jako treść żądania PUT 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 jawnie wymienia te właściwości (jeśli chcesz zaktualizować wszystkie właściwości, wymień je wszystkie za pomocą skrótu fields:"*"). Na przykład ten parametr określa, że tytuł i właściwości rozmiaru arkusza powinny zostać zaktualizowane w przypadku 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ć sheetId arkusza, użyj metody spreadsheets.get arkusza kalkulacyjnego.
Usuwanie arkusza
Oba interfejsy API mogą usuwać arkusze z danego arkusza kalkulacyjnego.
Interfejs API (wersja 3)
Aby usunąć arkusz, zacznij od pobrania pliku danych arkusza, a następnie wyślij żądanie DELETE na adres URL edit wpisu arkusza docelowego.
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 parametr sheetId, który ma zostać usunięty z arkusza. Na przykład:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteSheet": {
"sheetId": sheetId
}
}
],
}
Aby pobrać sheetId z pojedynczego arkusza, użyj metody spreadsheets.get arkusza kalkulacyjnego.
Pobieranie danych wiersza
Plik danych wierszy listy to jedna z dwóch metod uzyskiwania dostępu do danych w komórkach arkusza kalkulacyjnego (druga to plik danych komórek) udostępnianego przez interfejs API Arkuszy w wersji 3. Plik danych wierszy obsługuje typowe operacje w arkuszu kalkulacyjnym (odczytywanie wiersza po wierszu, dodawanie wierszy, sortowanie), ale przyjmuje określone założenia, które sprawiają, że nie nadaje się on do niektórych zadań. W szczególności plik danych z listą zakłada, że puste wiersze są zakończeniami pliku danych, a wymagane nagłówki znajdują się w pierwszym wierszu arkusza.
W przeciwieństwie do tego interfejsu interfejs API Arkuszy w wersji 4 nie używa metod dostępu właściwych dla poszczególnych wierszy. Dostęp do danych komórki arkusza uzyskuje się przez odwoływanie się do konkretnych zakresów wymaganych w notacji A1. Zakresy mogą obejmować bloki komórek, całe wiersze, całe kolumny lub całe arkusze. Interfejs API ma też dostęp do rozłączonych zbiorów komórek.
Interfejs API (wersja 3)
Aby określić adres URL kanału opartego na liście w przypadku danego arkusza, pobierz plik danych arkusza i znajdź adres URL tego pliku we wpisie arkusza.
Aby pobrać plik danych oparty na listach, wyślij żądanie GET na adres URL pliku danych, korzystając z odpowiedniego nagłówka autoryzacji. Na przykład:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
Odpowiedź na to żądanie zawiera między innymi wpisy odpowiadające określonym wierszom. Do poszczególnych komórek odwołują się nazwy podane w wierszu nagłówka arkusza (wymagane). Oto np. taki wpis 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 z listą są zwracane w kolejności wierszy. Interfejs API Arkuszy w wersji 3 udostępnia parametry zapytania, które pozwalają zmienić tę kolejność.
Odwróć kolejność:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full?reverse=true
Uporządkuj według określonej kolumny:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?orderby=column:lastname
Interfejs API Arkuszy w wersji 3 umożliwia też filtrowanie konkretnych wierszy za pomocą uporządkowanych zapytań (odwołanych 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 API Arkuszy w wersji 4 wiersze można pobierać według zakresu przy użyciu metod spreadsheets.values.get lub spreadsheets.values.batchGet. Ta opcja zwraca na przykład wszystkie wiersze w kolumnie „Arkusz1”:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1
Struktura odpowiedzi na to żądanie ma podobną strukturę:
{
"range": "Sheet1",
"majorDimension": "ROWS",
"values": [["Name", "Hours", "Items", "IPM"],
["Bingley", "10", "2", "0.0033"],
["Darcy", "14", "6", "0.0071"]]
}
Puste komórki na końcu nie są uwzględniane w odpowiedzi podczas pobierania całych wierszy, kolumn ani arkuszy.
Interfejs API Arkuszy w wersji 4 nie ma odpowiedników parametrów zapytań w kolejności wierszy udostępnianej przez interfejs Arkuszy Google w wersji 3. Odwrotna kolejność jest banalna. Wystarczy, że przetworzysz zwróconą tablicę values w odwrotnej kolejności. Sortowanie według kolumny nie jest obsługiwane w przypadku odczytów, ale można posortować dane w arkuszu (za pomocą żądania SortRange), a potem je odczytać.
Interfejs API Arkuszy w wersji 4 nie ma obecnie bezpośredniego odpowiednika ustrukturyzowanych zapytań interfejsu Sheets API w wersji 3. Możesz jednak pobrać odpowiednie dane i posortować je w swojej aplikacji.
Dodawanie nowego wiersza danych
Nowy wiersz danych możesz dodać do arkusza za pomocą interfejsu API.
Interfejs API (wersja 3)
Aby określić adres URL kanału opartego na liście w danym arkuszu, pobierz plik danych arkusza i znajdź adres URL posta we wpisie arkusza.
Aby dodać wiersz danych, wyślij żądanie POST na adres URL posta, korzystając z odpowiedniego nagłówka autoryzacji. Na przykład:
POST https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
Treść żądania POST powinna zawierać wpis dotyczący danych wiersza do dodania oraz poszczególnych komórek, do których odwołują się nagłówki 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ą dołączane na końcu określonego arkusza.
Interfejs API w wersji 4
Za pomocą interfejsu API Arkuszy w wersji 4 możesz dołączać wiersze za pomocą metody spreadsheets.values.append. W tym przykładzie wpisujesz nowy wiersz danych pod ostatnią tabelą w arkuszu „Arkusz1” w arkuszu kalkulacyjnym.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}
Dodatkowo interfejs Arkuszach Google w wersji 4 umożliwia też dołączanie komórek z określonymi właściwościami i formatowaniem za pomocą żądań AppendCells w pliku spreadsheets.batchUpdate.
Edytowanie wiersza z nowymi danymi
Oba interfejsy API umożliwiają aktualizowanie danych wierszy za pomocą nowych wartości.
Interfejs API (wersja 3)
Jeśli chcesz edytować wiersz danych, w pliku danych listy znajdź wpis odpowiadający wierszowi, który chcesz zaktualizować. W razie potrzeby zaktualizuj jego zawartość. Upewnij się, że wartość identyfikatora we wpisie jest dokładnie taka sama jak identyfikator istniejącego wpisu.
Po zaktualizowaniu wpisu wyślij żądanie PUT z tym wpisem jako treścią żądania na adres URL edit podany w tym wierszu, korzystając z 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 API Arkuszy w wersji 4 możesz edytować wiersz, używając notacji A1 w tym wierszu, który chcesz edytować, i wysyłać żądanie jego zastąpienia spreadsheets.values.update. Określony zakres musi się odnosić tylko do pierwszej komórki w wierszu. Interfejs API określa komórki, które mają zostać zaktualizowane, na podstawie wartości podanych w żądaniu. Jeśli zamiast tego określisz zakres wielokomórkowy, podane wartości muszą mieścić się w tym zakresie. W przeciwnym razie interfejs API zwróci błąd.
Poniższe przykładowe żądanie i treść żądania dodają dane do 4 wiersza w arkuszu „Arkusz1”:
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A4
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}
Możesz też zaktualizować dane w wierszach, korzystając z metody spreadsheet.values.batchUpdate. Ta metoda lepiej sprawdza się w przypadku aktualizowania wielu wierszy lub komórek.
Dodatkowo interfejs API Arkuszy w wersji 4 umożliwia edytowanie właściwości komórek i formatowania komórek za pomocą żądań UpdateCells lub RepeatCell w pliku spreadsheets.batchUpdate.
Usuwanie wiersza
Oba interfejsy API obsługują usuwanie wierszy. Usunięty wiersz jest usuwany z arkusza kalkulacyjnego, a wiersze znajdujące się pod nim są przenoszone do góry.
Interfejs API (wersja 3)
Aby usunąć wiersz, najpierw pobierz wiersz do usunięcia z pliku danych z listą, a potem wyślij żądanie DELETE na adres URL edit podany we wpisie tego wiersza.
Jest to ten sam adres URL, który jest używany do aktualizowania wiersza.
DELETE https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
Jeśli nie chcesz usunąć wiersza, który został zmieniony przez innego klienta od czasu jego pobrania, dołącz nagłówek HTTP If-Match zawierający wartość ETag oryginalnego wiersza. Aby określić wartość ETag w pierwotnym wierszu, sprawdź atrybut gd:etag elementu wpisu.
Jeśli chcesz usunąć wiersz niezależnie od tego, czy ktoś inny zaktualizował go od czasu jego pobrania, użyj funkcji If-Match: * i nie dołączaj tagu ETag. W takim przypadku nie musisz pobierać wiersza przed jego usunięciem.
Interfejs API w wersji 4
Usuwanie wierszy za pomocą interfejsu API Arkuszy w wersji 4 jest obsługiwane przez wywołanie metody spreadsheet.batchUpdate za pomocą żądania DeleteDimension. W ten sposób możesz też usunąć kolumny oraz programistów albo usunąć tylko część wiersza lub kolumny. Na przykład poniższy wiersz usuwa szósty wiersz arkusza o podanym identyfikatorze (indeksy wierszy są liczone od zera, a indeksy zaczynają się od wartości zerowej, a indeksy zaczynają się od początku indeksu i bez parametru endIndex):
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteDimension": {
"range": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 5,
"endIndex": 6
}
}
}
],
}
Element sheetId arkusza można pobrać przy użyciu metody spreadsheet.get.
Pobieranie danych z komórki
Interfejs Arkuszy API w wersji 3 udostępnia plik danych komórek, który zapewnia 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 zdefiniowanych przez zbiór parametrów zapytania, ale tylko jako pojedynczy blok – rozłączonych zakresów należy pobierać oddzielnie przy użyciu dodatkowych żądań GET.
Interfejs API Arkuszy w wersji 4 może pobierać z arkusza dowolny zestaw danych komórek (w tym wiele rozłączonych zakresów). Interfejs API Arkuszy w wersji 3 może zwracać zawartość komórek tylko jako wartości wejściowe (wpisywane przez użytkownika przy użyciu klawiatury) lub jako dane wyjściowe formuły (jeśli mają wartości liczbowe). Interfejs API Arkuszy w wersji 4 zapewnia pełny dostęp do wartości, formuł, formatowania, hiperlinków, sprawdzania poprawności danych i innych właściwości.
Interfejs API (wersja 3)
Aby określić adres URL kanału opartego na komórkach w danym arkuszu, sprawdź plik danych arkusza i znajdź adres URL tego pliku w odpowiednim wpisie arkusza.
Aby pobrać kanał oparty na komórkach, wyślij żądanie GET na adres URL tego pliku, korzystając z odpowiedniego nagłówka autoryzacji. Na przykład:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
Do komórek odwołuje się numer wiersza i kolumny. Pojedynczy zakres można pobrać za pomocą parametrów zapytania max-row, min-row, max-col i min-col. Na przykład ten kod 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 API Arkuszy Google w wersji 3 zwraca inputValue pobranych komórek – wartości, które użytkownik w innym przypadku wpisałby w interfejsie Arkuszy Google, aby manipulować komórką. inputValue może być literałem lub formułą. Interfejs API czasami zwraca też numericValue, na przykład gdy formuła zwraca liczbę. Na przykład odpowiedź może zawierać wpisy komórek 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
Możesz pobierać dane z komórek, wywołując metodę spreadsheets.values.get lub spreadsheets.values.batchGet dla odpowiedniego zakresu lub zakresów zainteresowań. Na przykład ten kod zwraca komórki w kolumnie D arkusza „Arkusz2”, zaczynając od wiersza 2 w wielkiej kolejności w kolumnie „kolumny” i zwracając formuły (na końcu puste komórki 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ę:
{
"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órkowych, wygodniej 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 Arkuszy API w wersji 3 umożliwia edytowanie zawartości komórki przez wydanie polecenia PUT w pliku danych komórek, w którym jako treść żądania możesz wpisać zmodyfikowany wpis komórki.
Interfejs Arkuszy API w wersji 4 udostępnia natomiast metody spreadsheets.values.update i metody spreadsheets.values.batchUpdate do zmiany zawartości komórek.
Interfejs API (wersja 3)
Aby edytować zawartość pojedynczej komórki, najpierw znajdź jej wpis w pliku danych komórki.
Wpis zawiera adres URL edycji. Zaktualizuj wpis, tak aby odzwierciedlał zawartość, którą ma zawierać komórka, a następnie wyślij żądanie PUT do adresu URL do edycji, używając zaktualizowanego wpisu w komórce jako treści żądania. Na przykład poniższy kod aktualizuje komórkę D2 (R2C4) tak, 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
W interfejsie Arkuszach API w wersji 4 edytowanie pojedynczych komórek można wprowadzać za pomocą metody spreadsheets.values.update. Ta metoda wymaga parametru zapytania ValueInputOption, który określa, czy dane wejściowe są traktowane tak, jakby były wprowadzone w interfejsie Arkuszy (USER_ENTERED) czy pozostawione bez analizy i bez zmian (RAW). Na przykład poniżej 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 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 zapewniają sposoby wprowadzania zmian w treści wielu komórek za pomocą jednego żądania (zbiorczego). Komórki, do których odwołuje się żądanie zbiorcze, nie muszą być w zakresie warunkowym.
Jeśli nie uda się wprowadzić zmian w co najmniej 1 komórce w grupie, interfejs API Arkuszy w wersji 3 pozwala na odniesienie sukcesu innym użytkownikom. Interfejs Arkuszy API w wersji 4 zwraca jednak błąd, jeśli któraś z aktualizacji wsadowych się nie powiedzie. W takim przypadku żadna z nich nie zostanie zastosowana.
Interfejs API (wersja 3)
Aby edytować wiele komórek, najpierw pobierz plik danych komórek dla arkusza. Wpis zawiera adres URL grupy. Wyślij na ten adres URL żądanie POST z treścią żądania zawierającą opis komórek, które chcesz zaktualizować, oraz ich nową zawartość. Żądanie i treść żądania POST 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 wsadu.
Aby można było edytować komórkę, pole batch:operation powinno mieć wartość update. gs:cell identyfikuje komórkę według numeru wiersza i kolumny oraz podaje nowe dane, które mają być w niej wstawione. id zawiera pełny adres URL komórki, która ma zostać zaktualizowana.
link musi mieć atrybut href zawierający pełną ścieżkę do identyfikatora komórki. Wszystkie te pola są wymagane w przypadku każdego wpisu.
Interfejs API w wersji 4
Interfejs Arkuszy API w wersji 4 umożliwia edytowanie zbiorcze wartości komórek za pomocą metody spreadsheets.values.batchUpdate.
Aby edytować wiele komórek, możesz wysłać żą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 podasz jedną komórkę, wszystkie podane wartości zostaną zapisane w arkuszu, począwszy od tej komórki jako współrzędnych w lewym górnym rogu. 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.