Migracja z Arkuszy API w wersji 3

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 Arkusze 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 Arkuszach API 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 ustala 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.