Jeśli masz już aplikacje oparte na interfejsie API Arkuszy Google w wersji 3, możesz przejść na Interfejs API Arkuszy Google w wersji 4. Wersja v4 jest oparta na formacie JSON i jest łatwiejsza w obsłudze i udostępnia znaczną ilość funkcji, które są niedostępne w wersji 3.
Na tej stronie znajdziesz mapowanie między starszymi poleceniami interfejsu Arkuszy API w wersji 3 a ich operacji w interfejsie Arkuszy Google w wersji 4. Mapowanie koncentruje się głównie na spreadsheets.values , który zapewnia bezpośredni odczyt i zapis komórek. Inne aspekty, takie jak dodawanie arkuszy czy aktualizowanie właściwości, są obsługiwane przez kolekcję arkuszy kalkulacyjnych. Pamiętaj, że struktury JSON interfejsu API w wersji 4 nie są zgodne wstecznie z interfejsem API w wersji 4 Struktury XML używane w wersji 3.
Więcej informacji o zasobach dostępnych w interfejsie Arkuszy Google w wersji 4 znajdziesz w dokumentacji Dokumentacja API.
Zapis i warunki
W interfejsie API w wersji 3 arkusze w określonym arkuszu kalkulacyjnym są nazywane „arkuszami roboczymi”. Jest to równoznaczne z terminem „arkusze” z których korzysta interfejs API w wersji 4.
Interfejsy API często wymagają określenia identyfikatora arkusza kalkulacyjnego arkusza kalkulacyjnego, nad którym pracujesz. Często wymagają też identyfikatora użytkownika arkuszu kalkulacyjnym. Te wartości pojawiają się jako część punktu końcowego API adresu URL, parametrów zapytania lub treści żądania. Na tej stronie parametr obiekty zastępcze spreadsheetId i sheetId odnosi się odpowiednio do identyfikatorów arkuszy kalkulacyjnych i arkuszy. Korzystanie z metod opisane na tej stronie, zastąp rzeczywiste identyfikatory w tych lokalizacjach.
Interfejs API w wersji 3 przypisuje identyfikator także do wierszy pobieranych za pomocą jego parametru lista kanałów; jest reprezentowane na tej stronie przez zmienną rowId.
Autoryzowanie żądań
Po uruchomieniu aplikacji prosi użytkowników o przyznanie określonych uprawnień. zakresy, które określone w aplikacji określają, o jakie uprawnienia 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
Użyj zakresów tylko do odczytu, jeśli aplikacja nie musi wprowadzać zmian w do arkuszy kalkulacyjnych lub właściwości arkusza użytkownika. Zamiast nich używaj zakresów arkuszy kalkulacyjnych Zakresy Dysku, jeśli aplikacja nie wymaga ogólnego dostępu do Dysku.
Widoczność
W starszych wersjach interfejsu API termin widoczność jest używany w odniesieniu do dostępności konkretnego arkusza kalkulacyjnego.
Interfejs API w wersji 3
Interfejs Arkuszy API w wersji 3 wyraża widoczność bezpośrednio w punktach końcowych. public
arkusz kalkulacyjny został opublikowany w internecie. dlatego mają dostęp do
Interfejs API bez autoryzacji, podczas gdy arkusz kalkulacyjny private
wymaga
uwierzytelnianie. Widoczność jest określana w punkcie końcowym po fragmencie
identyfikator 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 dostępu do określonego arkusza kalkulacyjnego, zwracany jest błąd. W przeciwnym razie rozmowa jest kontynuowana.
Odwzorowanie
Termin rzutowanie jest używany w interfejsie Arkuszy API w wersji 3 do określenia zbioru danych. zwracane przez określone wywołanie interfejsu API – całość lub ustalony podzbiór. zdefiniowane w interfejsie API. Interfejs Arkuszy API w wersji 4 nie korzysta z projekcji. raczej pozwala lepiej kontrolować to, 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
rzutowanie zwraca wszystkie dostępne informacje, natomiast basic
zwraca
mniejszego, stałego podzbioru danych (dla plików danych arkuszy, list i komórek).
Podobnie jak w przypadku widoczności, 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 zapewnianych przez prognozę basic
jest cenny
, 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 ma zdefiniowanego
podzbiory analogiczne do ustawienia widoczności interfejsu API basic
w wersji 3.
Metody w arkuszu kalkulacyjnym
ograniczają ilość danych zwracanych za pomocą
parametr zapytania fields.
Na przykład poniższe 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 interfejsu Drive API Files.create
można użyć do tworzenia nowych plików arkuszy kalkulacyjnych. Wymaga to parametru
aplikacji do deklarowania zakresu https://www.googleapis.com/auth/drive
.
Interfejs API w wersji 4
Metoda Files.create interfejsu Drive API umożliwia
być używane z interfejsem Arkuszy API w wersji 4, ale aplikacja musi udostępnić
zakres https://www.googleapis.com/auth/drive
.
Jako równoważną wersję interfejsu Arkuszy API w wersji 4 zapewnia spreadsheets.create , która może opcjonalnie dodawać arkusze, ustawiać arkusz kalkulacyjny i arkusz i dodać zakresy nazwane. Na przykład ten kod tworzy nowy tag arkusza kalkulacyjnego o nazwie „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 Arkuszy API w wersji 3 umożliwia aplikacji pobieranie listy wszystkich arkusze kalkulacyjne dla uwierzytelnionego użytkownika. Plik danych w arkuszu kalkulacyjnym Punkt końcowy 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 migracji aplikacji do zakresu drive.file w połączeniu z Selektor Google umożliwiający wybór arkusza kalkulacyjnego.
Jeśli wymagane są listy arkuszy kalkulacyjnych, można je powielić.
za pomocą metody Files.list interfejsu Drive API, przy użyciu
zapytanie 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 Arkuszy API w wersji 3 udostępnia plik danych umożliwiający dostęp do metadanych arkusza zawarte w danym arkuszu kalkulacyjnym (dostęp do danych z wierszy i komórek można uzyskać za pomocą oddzielnym pliku danych). Metadane zawierają takie informacje, jak tytuły arkuszy informacje o rozmiarze.
Interfejs Arkuszy API w wersji 4 spreadsheets.get umożliwia dostęp do tych i wielu innych informacji.
Interfejs API w wersji 3
Plik danych arkusza jest dostępny z tego punktu końcowego interfejsu API (za pomocą odpowiedni nagłówek autoryzacji):
GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
Odpowiedź na to żądanie ma podobną strukturę:
dane każdego arkusza zawarte w osobnym arkuszu <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
Plik spreadsheets.get
może być używana do pozyskiwania właściwości arkusza i innych metadanych.
niż jest dostępny
w Arkuszach API w wersji 3. Jeśli tylko
chcesz odczytać właściwości arkusza, ustaw zapytanie includeGridData
na false
, aby zapobiec uwzględnianiu danych komórek arkusza kalkulacyjnego:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?includeGridData=false
Spreadsheet
odpowiedź zawiera tablicę Sheet
obiekty; tytuły arkuszy i informacje o rozmiarze można znaleźć
na licencji 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 umożliwia dodawanie nowych arkuszy do arkusza kalkulacyjnego przez utworzenie
następujące (uwierzytelnione) żądanie POST
. Możesz określić rozmiar
nowy arkusz:
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
Aby dodać nowe arkusze, utwórz AddSheet żądanie w arkuszu spreadsheets.batchUpdate. . W treści żądania możesz określić właściwości arkusza nowy arkusz; Wszystkie właściwości są opcjonalne. Podanie atrybutu tytuł używany w istniejącym arkuszu.
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 Arkuszy API w wersji 3 umożliwia aktualizowanie tytułów i rozmiaru arkuszy. Interfejs Arkuszy API w wersji 4 pozwala na to również, ale może też służyć do aktualizowania innych właściwości arkusza. Pamiętaj, że zmniejszenie rozmiaru arkusza może spowodować, że dane w przyciętych komórkach usunięto bez ostrzeżenia.
Interfejs API w wersji 3
Aby zmienić tytuł lub rozmiar arkusza, zacznij od pobrania
pliku danych arkusza kalkulacyjnego oraz
znalezienie żądanego wpisu 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, utwórz
updateSheetProperties
w sekcji
spreadsheets.batchUpdate
. Treść żądania POST
powinna zawierać właściwości, które mają
została zmieniona, a parametr fields
powinien zawierać jawną listę tych właściwości
(jeśli chcesz zaktualizować wszystkie właściwości, użyj fields:"*"
jako skrótu
wszystkich). Dla:
W poniższym przykładzie poniżej określamy, że tytuł i rozmiar arkusza
należy zaktualizować właściwości 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 arkusza kalkulacyjnego spreadsheets.get.
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 kalkulacyjnego, a potem
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
DeleteSheet
w sekcji
spreadsheets.batchUpdate
. Treść żądania POST
powinna zawierać tylko sheetId dla
arkusza kalkulacyjnego do usunięcia. Na przykład:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{ "requests": [ { "deleteSheet": { "sheetId": sheetId } } ], }
Aby pobrać atrybut sheetId pojedynczego arkusza, użyj arkusz kalkulacyjny spreadsheets.get .
Pobieranie danych wiersza
Plik danych z listą wierszy jest jedną z dwóch metod, które są dostępne w interfejsie Arkuszy Google w wersji 3. uzyskiwania dostępu do danych w komórkach arkusza kalkulacyjnego (drugiej jest plikiem danych komórek). plik danych dotyczący wierszy służy do obsługi typowych operacji w arkuszu kalkulacyjnym (odczytywanie wierszy po wierszu, dodawania wierszy, sortowania), ale przyjmuje pewne założenia, które sprawiają, że do niektórych zadań. Plik danych z listą zakłada, że puste wiersze są plikami danych. zakończeń, a wymagane nagłówki znajdują się w pierwszym wierszu arkusza kalkulacyjnego.
Interfejs Arkusze API w wersji 4 nie korzysta z metod dostępu, które są z poszczególnych wierszy. Zamiast tego dostęp do danych w komórce arkusza uzyskuje się przez odwołanie do określonego elementu wymagane są zakresy w notacji A1. zakresy mogą być blokami komórek, całymi wierszami, całymi kolumnami lub całymi arkuszami. 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, pobierz plik danych arkusza w odpowiednim wpisie arkusza roboczego odszukaj adres URL kanału listy.
Aby pobrać kanał oparty na liście, wyślij żądanie GET
na adres URL kanału listy.
za pomocą 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 następujące informacje: odpowiadające konkretnym wierszom. Do poszczególnych komórek odwołują się odwołania nazwy podane w (obowiązkowym) wierszu nagłówka arkusza. Na przykład tutaj to 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ą 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 Arkusze API w wersji 3 umożliwia też filtrowanie określonych wierszy za pomocą uporządkowanych danych zapytanie (wywoływane przez nagłówki 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 za pomocą 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"]] }
Puste komórki na końcu nie są uwzględniane w odpowiedzi podczas pobierania całych wiersze, kolumny lub arkusze.
Interfejs Arkuszy API w wersji 4 nie ma odpowiednika zapytania dotyczącego kolejności wierszy
parametrów udostępnianych przez interfejs Arkuszy API w wersji 3. Odwrotna kolejność jest banalna. po prostu
przetworzyć zwróconą tablicę values
w odwrotnej kolejności. Kolejność według kolumny to nie
obsługiwanych odczytów, ale można sortować dane w arkuszu (za pomocą funkcji
SortRange)
i odczytać go.
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 uporządkować je według potrzeb 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 odszukaj adres URL posta we wpisie arkusza, który Cię interesuje.
Aby dodać wiersz danych, wyślij żądanie POST
na adres URL posta.
za pomocą odpowiedniego nagłówka autoryzacji. Na przykład:
POST https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
Treść żądania POST
powinna zawierać wpis danych wiersza
dodaj z poszczególnymi komórkami, 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ą dodawane na końcu określonego arkusza.
Interfejs API w wersji 4
W przypadku interfejsu Arkuszy API w wersji 4 możesz dołączać wiersze za pomocą funkcji spreadsheets.values.append . Ten przykład powoduje zapisanie nowego wiersza danych pod ostatnim tabela w „Arkusz1” arkusza kalkulacyjnego.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1
{ "values": [["Elizabeth", "2", "0.5", "60"]] }
Interfejs Arkuszy API w wersji 4 umożliwia też dodawanie komórek z określonymi właściwości i formatowania za pomocą AppendCells żądania w 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 zmodyfikować wiersz danych, przejrzyj plik danych z listą aby znaleźć wpis dotyczący wiersza, który chcesz zaktualizować. Zaktualizuj zawartość w razie potrzeby. Upewnij się, że używana przez Ciebie wartość identyfikatora we wpisie jest dokładnie taka sama pasuje do identyfikatora istniejącego wpisu.
Po zaktualizowaniu wpisu wyślij żądanie PUT
z wpisem jako
treść żądania do adresu URL edit
podanego w tym wierszu,
za pomocą 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 interfejsie Arkuszy Google w wersji 4 możesz edytować wiersz za pomocą Zapis A1 wiersza, który chcesz zapisać edytując i publikując spreadsheets.values.update nadpisać ten wiersz. Podany zakres musi odnosić się tylko do pierwsza komórka w wierszu; interfejs API „wybiera komórki do zaktualizowania” na podstawie podane w żądaniu. Jeśli zamiast tego określisz zakres wielokomórkowy, podane wartości muszą mieścić się w tym zakresie; jeśli nie, interfejs API zwróci błąd .
Poniższe przykładowe żądanie i treść żądania dodaje dane do czwarty wiersz "Arkusz1":
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A4
{ "values": [["Elizabeth", "2", "0.5", "60"]] }
Możesz również zaktualizować dane wierszy z spreadsheet.values.batchUpdate ; ta metoda jest skuteczniejsza, jeśli tworzysz wiele aktualizacje wierszy lub komórek.
Dodatkowo interfejs Arkuszy API w wersji 4 umożliwia edytowanie właściwości komórek formatowanie komórek za pomocą UpdateCells lub RepeatCell żądania w 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 o jeden w górę.
Interfejs API w wersji 3
Aby usunąć wiersz, najpierw pobierz go z
kanał listy,
a następnie wyślij żądanie DELETE
na adres URL w usłudze 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
Aby mieć pewność, że nie usuniesz wiersza, który został zmieniony przez innego klienta od momentu pobrania, dołącz nagłówek HTTP If-Match zawierający wartość ETag pierwotnego wiersza. Oryginał możesz sprawdzić, wartości ETag wiersza, sprawdzając atrybut gd:etag elementu wpisu.
Jeśli chcesz usunąć wiersz niezależnie od tego, czy ktoś inny zaktualizował go od czasu pobrania, użyj operatora If-Match: * i nie uwzględniaj parametru 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 polecenie spreadsheet.batchUpdate. za pomocą funkcji DeleteDimension użytkownika. Tego żądania można też użyć, aby usunąć kolumny. Deweloperzy i wybierz usunięcie tylko części wiersza lub kolumny. Na przykład parametr to spowoduje usunięcie szóstego wiersza arkusza o podanym identyfikatorze (indeksy wierszy) wartości są liczone od zera, przy czym wartości startIndex (włącznie) i endIndex są wyłączone):
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{ "requests": [ { "deleteDimension": { "range": { "sheetId": sheetId, "dimension": "ROWS", "startIndex": 5, "endIndex": 6 } } } ], }
Wartość sheetId arkusza można pobrać za pomocą spreadsheet.get.
Odzyskaj dane komórkowe
Interfejs Arkuszy API w wersji 3 udostępnia plik danych komórek zapewniający podstawowy dostęp do wszystkich danych
arkusz kalkulacyjny. Aby umożliwić odczyt, plik danych komórek może zawierać cały arkusz
zawartość lub zakres komórek arkusza zdefiniowany przez zestaw parametrów zapytania,
ale tylko jako pojedynczy blok – należy pobrać rozłączone zakresy
oddzielnie za pomocą dodatkowych żądań GET
.
Interfejs Arkuszy API w wersji 4 może pobierać z arkusza dowolny zestaw danych komórek (w tym wielu 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ła (jeśli jest liczbą); interfejs Arkusze API w wersji 4 przyznaje 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 opartego na komórkach dla danego arkusza, sprawdź w plik danych arkusza kalkulacyjnego i odszukaj adres URL kanału komórek we wpisie arkusza, który Cię interesuje.
Aby pobrać kanał komórkowy, wyślij żądanie GET
na adres URL kanału komórek.
za pomocą 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. Pobieranie konkretnego
można to zrobić przy użyciu funkcji max-row
, min-row
, max-col
i min-col
parametrów zapytania. 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 Arkuszy API w wersji 3 zwraca inputValue
pobranych komórek –
wartość, którą użytkownik w innej sytuacji wpisuje w Arkuszach Google
za pomocą interfejsu edycji komórek. inputValue
może być wartością literałową
lub formułę. Interfejs API czasem zwraca też numericValue
; np.
gdy formuła zwróci liczbę. Na przykład odpowiedź może zawierać komórkę
wpisy 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
Aby pobrać dane komórkowe, wywołaj spreadsheets.values.get lub spreadsheets.values.batchGet dla odpowiedniego zakresu lub zakresów zainteresowań. Na przykład parametr poniżej zwraca komórki w kolumnie D tabeli „Arkusz2”, zaczynając od wiersza 2, w kolejności stosowania kolumn i zwracanych formuł zgodnie z podanymi wartościami (na ścieżce puste pole 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 strukturę podobną do:
{ "spreadsheetId": spreadsheetId, "valueRanges": [ {"range": "Sheet2!D2:D", "majorDimension": "COLUMNS", "values": [["Widget", 234, "=FLOOR(C4/(B4*60),.0001)", "=D4\*1000"]] }] }
Łatwiej jest użyć spreadsheet.values.batchGet jeśli zamierzasz pobrać wiele zakresów danych komórkowych. Jeśli chcesz dostęp do właściwości komórek, takich jak formatowanie, spreadsheet.get .
Edytowanie komórki
Interfejs Arkuszy API w wersji 3 umożliwia edytowanie zawartości komórki przez polecenie PUT
kanał komórek ze zmodyfikowanym wpisem komórki jako treścią żądania.
Interfejs Arkuszy API w wersji 4 zapewnia natomiast spreadsheets.values.update oraz spreadsheets.values.batchUpdate metod zmiany zawartości komórki.
Interfejs API w wersji 3
Aby edytować zawartość pojedynczej komórki, najpierw znajdź wpis tej komórki w sekcji
kanału komórkowego.
Wpis zawiera adres URL edycji. Zaktualizuj wpis tak, aby odzwierciedlał jego treść
które chcesz zmienić w komórce, a następnie wyślij żądanie PUT
do adresu URL.
ze zaktualizowanym wpisem komórki w treści żądania. Na przykład parametr
następujące zaktualizowanie komórki 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
Edytowanie pojedynczej komórki w interfejsie Arkuszy API w wersji 4 można edytować za pomocą
spreadsheets.values.update
. Ta metoda wymaga parametru zapytania ValueInputOption
, który
określa, czy dane wejściowe są traktowane tak, jakby zostały wprowadzone w funkcji
Interfejs Arkuszy (USER_ENTERED
) lub nieprzetworzone i pobrane w niezmienionej formie (RAW
). Dla:
poniższy przykład 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 funkcji spreadsheets.values.batchUpdate aby przesłać je 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, to 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. Jednak interfejs Arkusze API w wersji 4 zwraca błąd. , jeśli któraś z aktualizacji zbiorczych nie powiedzie się i w takim przypadku żadna z nich nie zostanie zastosowana.
Interfejs API w wersji 3
Aby edytować wiele komórek, najpierw pobierz plik danych w komórce
w arkuszu kalkulacyjnym. Wpis zawiera adres URL grupy. Wyślij POST
do tego adresu URL wraz z treścią żądania opisującą komórki,
i chcesz zaktualizować zawartość komórki. Żą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 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
aby ją tam wstawić. id
zawiera pełny adres URL komórki przeznaczonej do aktualizacji.
link
musi mieć atrybut href
zawierający pełną ścieżkę do
identyfikator 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ą spreadsheets.values.batchUpdate .
Aby edytować wiele komórek, wyślij żądanie POST
za pomocą funkcji
zmian danych określonych 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 określono jedną komórkę, wszystkie podane wartości będą zapisane 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ą pasować dokładnie ten zakres; w przeciwnym razie interfejs API zwróci błąd.