Jeśli masz już aplikacje oparte na interfejsie Google Arkuszy Google API w wersji 3, możesz przejść na interfejs Google Arkusze API w wersji 4. Wersja v4 jest oparta na formacie JSON, ma łatwiejszy w użyciu interfejs i oferuje znacznie więcej funkcji, które nie są dostępne w wersji 3.
Ta strona zawiera mapowanie między starszymi poleceniami interfejsu Arkuszy API w wersji 3 i ich odpowiednikami w interfejsie Arkuszy API w wersji 4. Mapowanie koncentruje 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 arkuszy, są obsługiwane przez kolekcję arkuszy kalkulacyjnych. Pamiętaj, że struktury JSON interfejsu API w wersji 4 nie są zgodne wstecz ze strukturami XML używanymi w wersji 3.
Więcej informacji o zasobach dostępnych w interfejsie Arkuszy v4 API znajdziesz w dokumentacji interfejsu API.
Zapis i warunki
W interfejsie API w wersji 3 arkusze w określonym arkuszu kalkulacyjnym są nazywane „arkuszami roboczymi”. Jest to odpowiednik terminu „arkusze”, którego używa interfejs API wersji 4.
Interfejsy API często wymagają określenia identyfikatora arkusza kalkulacyjnego, którego używasz. Często wymagają też identyfikatora edytowanego arkusza. Wartości te pojawiają się jako część adresu URL punktu końcowego API, jako parametry zapytania lub jako część treści żądania. Na tej stronie obiekty zastępcze spreadsheetId i sheetId odnoszą się odpowiednio do identyfikatora arkusza kalkulacyjnego i arkusza. Jeśli korzystasz z metod opisanych na tej stronie, zastąp rzeczywiste identyfikatory w tych lokalizacjach.
Interfejs API w wersji 3 przypisuje identyfikator także do wierszy pobranych za pomocą pliku danych z listą. Jest to reprezentowane na tej stronie przez zmienną rowId.
Autoryzowanie żądań
Podczas uruchamiania aplikacji prosi ona użytkowników o przyznanie określonych uprawnień. Zakresy określone w aplikacji określają, o jakie uprawnienia się prosi.
Interfejs API w wersji 3
Interfejs Arkuszy API 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żywać dowolnego formatu zakresu.
Interfejs API w wersji 4
Interfejs Arkuszy 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
Jeśli aplikacja nie musi wprowadzać zmian we właściwościach arkuszy ani arkuszy użytkownika, użyj 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 na Dysku.
Widoczność
W starszych wersjach interfejsu API termin visibility odnosi się do dostępności danego arkusza kalkulacyjnego.
Interfejs API w wersji 3
Interfejs Arkuszy API w wersji 3 wyraża widoczność bezpośrednio w punktach końcowych. Arkusz kalkulacyjny public
został „opublikowany w internecie”, więc interfejs API ma dostęp bez autoryzacji, a 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 nowym interfejsie Arkuszy Google 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 rzutowanie jest używany w interfejsie Arkuszy Google w wersji 3 do odwoływania się do zbioru danych zwracanych przez określone wywołanie interfejsu API – całości lub stałego podzbioru zdefiniowanym w interfejsie API. Interfejs Arkusze API w wersji 4 nie korzysta z rzutowania. Daje Ci większą kontrolę nad tym, jakie dane są zwracane.
Interfejs API w wersji 3
W interfejsie Arkuszy API w wersji 3 dostępne są tylko dwa ustawienia wyświetlania. full
zwraca wszystkie dostępne informacje, a basic
zwraca mniejszy, stały podzbiór danych (dla plików danych arkuszy, list i komórek).
Podobnie jak w przypadku widoczności, rzutowanie 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 dostarczany przez prognozę basic
jest cenny dla zwiększenia wydajności kodu, ale nie można go dostosować.
Interfejs API w wersji 4
Chociaż interfejs Arkusze API w wersji 4 może zwracać pełny zbiór danych, nie definiuje stałych podzbiorów analogicznych do ustawienia widoczności interfejsu basic
dostępnego w interfejsie Arkuszy 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 konkretnym arkuszu kalkulacyjnym:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title
Utwórz arkusz kalkulacyjny
Interfejs API w wersji 3
Interfejs Arkuszy API w wersji 3 nie umożliwia tworzenia nowych arkuszy kalkulacyjnych.
Zamiast tego do tworzenia nowych plików arkuszy kalkulacyjnych można używać metody Drive API Files.create. Wymaga to zadeklarowania zakresu https://www.googleapis.com/auth/drive
przez aplikację.
Interfejs API w wersji 4
Metody Files.create interfejsu API Dysku można też używać z interfejsem Arkuszy API w wersji 4, ale wymaga ona podania zakresu https://www.googleapis.com/auth/drive
w aplikacji.
Jako odpowiednik interfejsu Arkuszy API w wersji 4 dostępny jest też metoda spreadsheets.create, która pozwala opcjonalnie dodawać arkusze, ustawiać ich właściwości oraz dodawać zakresy nazwane. Przykład poniżej pozwala utworzyć nowy arkusz kalkulacyjny i nadać mu nazwę „NewTitle”:
POST https://sheets.googleapis.com/v4/spreadsheets
{ "properties": {"title": "NewTitle"} }
Wyświetlanie listy arkuszy kalkulacyjnych dla uwierzytelnionego użytkownika
Interfejs API w wersji 3
Plik danych interfejsu Arkuszy Google w wersji 3 umożliwia aplikacji pobieranie 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 Arkuszy API w wersji 4 nie umożliwia tej konkretnej operacji. Zalecamy migrację aplikacji, aby móc korzystać z zakresu drive.file w połączeniu z selektorem Google do wybierania arkuszy kalkulacyjnych.
Jeśli lista arkuszy kalkulacyjnych jest wymagana, można ją zreplikować przy użyciu metody Drive API Files.list przy użyciu 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 ograniczonego zakresu.
Pobieranie metadanych arkusza
Interfejs Arkuszy API w wersji 3 udostępnia plik danych umożliwiający dostęp do metadanych arkusza zawartych w danym arkuszu kalkulacyjnym (dane wierszy i komórek są dostępne za pomocą osobnego pliku danych). Metadane zawierają informacje takie jak tytuły arkuszy i informacje o rozmiarze.
Dostęp do tych i wielu innych informacji zapewnia metoda spreadsheets.get interfejsu Arkuszy API w wersji 4.
Interfejs API w wersji 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
Struktura odpowiedzi na to żądanie jest podobna do tej, w której 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
Metodę spreadsheets.get można używać do pobierania właściwości arkusza i innych metadanych – znacznie częściej niż w przypadku interfejsu Arkuszy API w wersji 3. Jeśli chcesz tylko odczytywać 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 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 w wersji 3
Interfejs Arkuszy 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
Nowe arkusze możesz dodawać, tworzą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 używanego dla istniejącego arkusza powoduje błąd.
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 Arkusze API w wersji 3 umożliwia aktualizowanie tytułów i rozmiaru arkuszy. Interfejs Arkusze API w wersji 4 również pozwala na to, ale może też służyć 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 w wersji 3
Aby zmienić tytuł lub rozmiar arkusza, pobierz plik danych arkusza i znajdź odpowiedni wpis arkusza, który zawiera adres URL edit
.
Zaktualizuj metadane arkusza i wyś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 w metodzie spreadsheets.batchUpdate. Treść żądania POST
powinna zawierać właściwości, które chcesz zmienić, a parametr fields
powinien ich zawierać jawną listę (jeśli chcesz zaktualizować wszystkie właściwości, użyj fields:"*"
jako skróconego opisu wszystkich). Na przykład ten sposób określa, że właściwości tytułu i 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ć właściwość sheetId arkusza, użyj metody spreadsheets.get arkusza kalkulacyjnego.
Usuwanie arkusza
Każdy z interfejsów API może usuwać arkusze z danego arkusza kalkulacyjnego.
Interfejs API w wersji 3
Aby usunąć arkusz, zacznij od pobrania pliku danych arkusza, a następnie wyślij żądanie DELETE
na adres 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, utwórz żądanie DeleteSheet w metodzie spreadsheets.batchUpdate. Treść żądania POST
powinna zawierać tylko sheetId dla 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ć właściwość sheetId pojedynczego arkusza kalkulacyjnego, użyj metody spreadsheets.get arkusza kalkulacyjnego.
Pobieranie danych wiersza
Plik danych z listą wierszy to jedna z dwóch metod dostępu do danych w komórkach arkusza kalkulacyjnego (druga to plik danych komórek), który jest dostępny w wersji 3 interfejsu Arkuszy API. Plik danych wierszy ma obsługiwać typowe operacje w arkuszach kalkulacyjnych (odczytywanie wierszy po wierszu, dołączanie wierszy, sortowanie), ale przyjmuje pewne 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 stanowią zakończenie pliku danych, a wymagane nagłówki znajdują się w pierwszym wierszu arkusza.
Interfejs Arkusze API w wersji 4 nie korzysta z metod dostępu, które są związane z poszczególnymi wierszami. Zamiast tego dostęp do danych w komórce arkusza uzyskuje się przez odwoływanie się do konkretnych zakresów wymaganych przy użyciu notacji A1. Zakresy mogą być blokami komórek, całych wierszy, całych kolumn lub całych arkuszy. Interfejs API ma również dostęp do rozłączonych zbiorów komórek.
Interfejs API w wersji 3
Aby określić adres URL kanału opartego na liście dla danego arkusza kalkulacyjnego, pobierz plik danych arkusza i znajdź adres URL kanału listy w odpowiednim wpisie w arkuszu.
Aby pobrać kanał oparty na liście, wyślij żądanie GET
na adres URL kanału z listą, 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. Do poszczególnych komórek odwołują się nazwy podane w (obowiązkowym) wierszu nagłówka arkusza. Oto przykładowy wpis z jednym wierszem:
<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ą produktów są zwracane w kolejności wierszy. Interfejs Arkuszy API w wersji 3 zawiera parametry zapytania umożliwiające zmianę tej kolejności.
Odwróć 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:lastname
Interfejs Arkuszy API w wersji 3 umożliwia też filtrowanie określonych 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<175
Interfejs API w wersji 4
W interfejsie Arkuszy API w wersji 4 można pobierać wiersze według zakresu przy użyciu metod spreadsheets.values.get lub spreadsheets.values.batchGet). Na przykład poniższe działanie zwraca wszystkie wiersze z kolumny „Sheet1”:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1
Struktura odpowiedzi na to żądanie wygląda tak:
{ "range": "Sheet1", "majorDimension": "ROWS", "values": [["Name", "Hours", "Items", "IPM"], ["Bingley", "10", "2", "0.0033"], ["Darcy", "14", "6", "0.0071"]] }
Końcowe puste komórki nie są uwzględniane w odpowiedzi podczas pobierania całych wierszy, kolumn ani arkuszy.
Interfejs Arkuszy API w wersji 4 nie ma odpowiednika parametrów zapytania dotyczących kolejności wierszy dostarczanych przez interfejs Arkusze API w wersji 3. Odwrotny rząd jest trywialny – przetwórz zwróconą tablicę values
w odwrotnej kolejności. Sortowanie według kolumny nie jest obsługiwane w przypadku odczytów, ale można sortować dane w arkuszu (za pomocą żądania SortRange), a następnie je odczytywać.
Interfejs Arkusze API w wersji 4 nie ma obecnie bezpośredniego odpowiednika zapytań uporządkowanych w interfejsie Arkuszy API w wersji 3. Możesz jednak pobrać odpowiednie dane i sortować je w aplikacji.
Dodaj nowy wiersz danych
Nowy wiersz danych możesz dodać do arkusza za pomocą dowolnego z tych interfejsów API.
Interfejs API w wersji 3
Aby określić adres URL kanału opartego na liście dla danego arkusza, pobierz plik danych arkusza i znajdź adres URL posta we wpisie arkusza, który Cię interesuje.
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, w których poszczególne komórki odwołują się do 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 określonego arkusza.
Interfejs API w wersji 4
Interfejs Arkuszy API w wersji 4 umożliwia dodawanie wierszy przy użyciu metody spreadsheets.values.append. Ten przykład pokazuje nowy wiersz danych pod ostatnią tabelą w arkuszu „Arkusz1” arkusza kalkulacyjnego.
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 dodawanie 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 w wersji 3
Aby edytować wiersz danych, przejrzyj plik danych z listą i odszukaj wpis wiersza, który chcesz zaktualizować. W razie potrzeby zaktualizuj zawartość tego wpisu. Upewnij się, że wartość identyfikatora we wskazanym wpisie jest dokładnie taka sama jak identyfikator 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
W przypadku interfejsu Arkuszy API w wersji 4 możesz edytować wiersz przy użyciu notacji A1, którą chcesz edytować, i wysłać żądanie spreadsheets.values.update, aby zastąpić ten wiersz. Podany zakres musi odwoływać się tylko do pierwszej komórki w wierszu. Interfejs API szacuje, że komórki do zaktualizowania mają zostać zaktualizowane na podstawie wartości podanych w żądaniu. Jeśli zamiast tego określisz zakres wielokomórkowy, podane przez Ciebie wartości muszą się do niego mieścić. W przeciwnym razie interfejs API zwróci błąd.
To przykładowe żądanie i treść żądania dodaje dane do czwartego wiersza arkusza „Sheet1”:
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A4
{ "values": [["Elizabeth", "2", "0.5", "60"]] }
Dane wierszy można też aktualizować za pomocą metody spreadsheet.values.batchUpdate. Ta metoda jest skuteczniejsza w przypadku aktualizacji wielu wierszy lub komórek.
Dodatkowo interfejs Arkuszy API w wersji 4 umożliwia edytowanie właściwości komórek oraz formatowanie 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ę niżej są przenoszone o jeden w górę.
Interfejs API w wersji 3
Aby usunąć wiersz, najpierw pobierz wiersz do usunięcia z pliku danych z listą, a następnie wyślij żądanie DELETE
na adres URL edit
podany we wpisie wiersza.
Jest to ten sam adres URL, który został użyty do aktualizacji 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 pierwotnego wiersza. Wartość ETag pierwotnego wiersza możesz określić, sprawdzając atrybut gd:etag elementu wpisu.
Jeśli chcesz usunąć wiersz niezależnie od tego, czy ktoś inny zaktualizował go po pobraniu, użyj funkcji If-Match: * i nie dodawaj ETag. W takim przypadku nie musisz pobierać wiersza przed jego usunięciem.
Interfejs API w wersji 4
Usuwanie wierszy z interfejsem Arkuszy Google w wersji 4 odbywa się przez wywołanie metody spreadsheet.batchUpdate za pomocą żądania DeleteDimension. Za pomocą tego żądania można też usunąć kolumny, a programista – usunąć tylko część wiersza lub kolumny. Na przykład poniższy przykład usuwa 6 wiersz arkusza o podanym identyfikatorze (indeksy wierszy są liczone od zera, przy czym wartości startIndex włącznie i końcowe są wyłączone):
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{ "requests": [ { "deleteDimension": { "range": { "sheetId": sheetId, "dimension": "ROWS", "startIndex": 5, "endIndex": 6 } } } ], }
Identyfikator sheetId arkusza można pobrać przy użyciu metody spreadsheet.get.
Odzyskaj dane komórkowe
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. Aby umożliwić odczyt całej zawartości arkusza lub zakresu komórek arkusza zdefiniowanych przez zestaw parametrów zapytania, ale tylko w postaci pojedynczego bloku – rozłączone zakresy trzeba pobierać osobno przy użyciu dodatkowych żądań GET
.
Interfejs Arkuszy API w wersji 4 może pobierać dowolny zbiór danych komórek z arkusza (w tym wiele rozłącznych zakresów). Interfejs Arkuszy API w wersji 3 może zwracać zawartość komórek tylko jako wartości wejściowe (takie jak wpisywane przez użytkownika na klawiaturze) lub dane wyjściowe formuły (w przypadku wartości liczbowych). Interfejs Arkuszy API 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 w wersji 3
Aby określić adres URL pliku danych bazującego na komórkach dla danego arkusza, sprawdź plik danych arkusza i znajdź adres URL tego pliku we wpisie arkusza, który Cię interesuje.
Aby pobrać plik danych w formacie komórkowym, wyślij żądanie GET
na adres URL kanału komórek, korzystając z odpowiedniego nagłówka autoryzacji. Na przykład:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
Odwołania do komórek odwołują się za pomocą numerów wierszy i kolumn. Aby pobrać konkretny zakres, użyj parametrów zapytania max-row
, min-row
, max-col
i min-col
. Na przykład to 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=4
Interfejs Arkusze API w wersji 3 zwraca wartość inputValue
pobranych komórek – wartość, którą użytkownik w innej sytuacji wpisuje w interfejsie Arkuszy Google, aby wykonać operację na komórce. inputValue
może być wartością literału lub formułą. Interfejs API czasem zwraca też numericValue
, np. gdy formuła zwróci liczbę. Odpowiedź może na przykład zawierać wpisy komórek podobne 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 wybranego zakresu lub zakresu zainteresowań. Na przykład poniższa metoda zwraca komórki w kolumnie D arkusza „Arkusz2”, zaczynając od wiersza 2, w kolejności rzędu kolumn i zwracając formuły zgodnie z podanymi wartościami (pomijane są puste komórki śledzące):
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet2!D2:D?majorDimension=COLUMNS&valueRenderOption=FORMULA
Odpowiedź na to żądanie ma strukturę podobną do:
{ "spreadsheetId": spreadsheetId, "valueRanges": [ {"range": "Sheet2!D2:D", "majorDimension": "COLUMNS", "values": [["Widget", 234, "=FLOOR(C4/(B4*60),.0001)", "=D4\*1000"]] }] }
Jeśli chcesz pobierać wiele zakresów danych w komórkach, lepiej użyć metody 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 uruchomienie polecenia PUT
do pliku danych komórek ze zmodyfikowanym wpisem komórki jako treścią żądania.
Interfejs Arkuszy API w wersji 4 udostępnia natomiast metody spreadsheets.values.update i spreadsheets.values.batchUpdate) do modyfikowania zawartości komórek.
Interfejs API w wersji 3
Aby edytować zawartość pojedynczej komórki, najpierw znajdź wpis tej komórki w kanale komórki.
Wpis zawiera adres URL edycji. Zaktualizuj wpis, aby odzwierciedlał zawartość, którą chcesz umieścić w komórce, a następnie wyślij żądanie PUT
do edycji adresu URL ze zaktualizowanym wpisem komórki w treści żądania. Przykład poniżej 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 pojedynczych komórek w interfejsie Arkuszy API w wersji 4 można edytować przy użyciu 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 bez przeanalizowania i zabrane w niezmienionej formie (RAW
). Na przykład poniższy wynik aktualizuje komórkę D2 o formułę:
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ć zmiany w jednym żądaniu.
Edycja wielu komórek za pomocą żądania zbiorczego
Oba interfejsy API zapewniają sposoby wprowadzania zmian w zawartości wielu komórek za pomocą pojedynczego żądania (zbiorczego). Komórki, do których odwołuje się żądanie zbiorcze, nie muszą być w stałym zakresie.
Jeśli co najmniej jedna zmiana w komórce w grupie nie powiedzie się, interfejs Arkuszy API w wersji 3 umożliwia powodzenie pozostałych zmian. Jeśli jednak któraś z aktualizacji zbiorczych nie powiedzie się, interfejs Arkuszy API w wersji 4 zwraca błąd i w takim przypadku żadna z nich nie jest stosowana.
Interfejs API w wersji 3
Aby edytować wiele komórek, najpierw pobierz plik danych sieci komórkowej dla arkusza. Wpis zawiera adres URL grupy. Na ten adres URL wyślij żądanie POST
wraz z treścią żądania opisującym komórki, które chcesz zaktualizować, oraz zawartość nowej komórki. Struktura żądania i treści żądania POST
jest podobna 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 porcie.
Aby można było edytować komórkę, pole batch:operation
powinno zawierać wartość update
. gs:cell
identyfikuje komórkę według numeru wiersza i kolumny oraz podaje nowe dane do wstawienia. id
zawiera pełny adres URL komórki przeznaczonej do aktualizacji.
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 zbiorczą edycję wartości komórek za pomocą metody spreadsheets.values.batchUpdate.
Aby edytować wiele komórek, wyślij żą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 zakres to jedna komórka, wszystkie podane wartości są zapisywane w arkuszu, zaczynając od tej komórki jako współrzędnej lewego górnego rogu. Jeśli zamiast tego określisz zakres wielokomórkowy, podane wartości muszą dokładnie do niego pasować. W przeciwnym razie interfejs API zwróci błąd.