Arkusz kalkulacyjny może mieć wiele arkuszy, a każdy z nich może zawierać dowolną liczbę wierszy lub kolumn. Komórka to miejsce na przecięciu określonego wiersza i kolumny, które może zawierać wartość danych. Interfejs Google Sheets API udostępnia zasób spreadsheets.values
umożliwiający odczytywanie i zapisywanie wartości.
Na tej stronie znajdziesz podstawowe informacje o korzystaniu z zasobu spreadsheets.values
. Jeśli chcesz wstawić wiersze lub zaktualizować formatowanie i inne właściwości arkusza, musisz użyć metody spreadsheets.batchUpdate
opisanej w artykule Aktualizowanie arkuszy kalkulacyjnych.
Metody
Zasób spreadsheets.values
udostępnia te metody odczytu i zapisu wartości, z których każda służy do określonego zadania:
Dostęp do zakresu | Czytanie | Pisanie |
---|---|---|
Pojedynczy zakres | spreadsheets.values.get | spreadsheets.values.update |
Wiele zakresów | spreadsheets.values.batchGet | spreadsheets.values.batchUpdate |
Dołączanie | spreadsheets.values.append |
Ogólnie rzecz biorąc, warto łączyć wiele odczytów lub aktualizacji z metodami batchGet
i batchUpdate
(odpowiednio), ponieważ zwiększa to wydajność.
Przykłady każdej z tych metod znajdziesz na stronach z przykładami podstawowego odczytu i podstawowego zapisu. Wszystkie przykłady znajdziesz na stronie z omówieniem przykładów.
Odczyt
Aby odczytać wartości danych z arkusza, potrzebujesz identyfikatora arkusza kalkulacyjnego i notacji A1 dla zakresu. Określenie zakresu bez identyfikatora arkusza (A1:B2
) oznacza, że żądanie zostanie wykonane w pierwszym arkuszu w arkuszu kalkulacyjnym. Więcej informacji o identyfikatorach arkuszy kalkulacyjnych i notacji A1 znajdziesz w artykule Przegląd interfejsu Google Sheets API.
Format danych wyjściowych kontroluje kilka opcjonalnych parametrów zapytania:
Formatowanie parametru | Wartość domyślna |
---|---|
majorDimension | WIERSZE |
valueRenderOption | FORMATTED_VALUE |
dateTimeRenderOption | SERIAL_NUMBER |
Pamiętaj, że dateTimeRenderOption
należy używać tylko wtedy, gdy valueRenderOption
nie jest FORMATTED_VALUE
.
Nie ma wyraźnego limitu ilości zwracanych danych. Błędy nie zwracają żadnych danych. Puste wiersze i kolumny na końcu są pomijane.
Metody pobierania pojedynczych i grupowych danych opisujemy poniżej. Przykłady podstawowych operacji odczytu znajdziesz w artykule Podstawowe odczytywanie.
Odczytywanie pojedynczego zakresu
Aby odczytać pojedynczy zakres wartości z arkusza kalkulacyjnego, użyj żądania spreadsheets.values.get
:
Google Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Odpowiedź na to żądanie jest zwracana jako obiekt ValueRange
.
Odczytywanie wielu zakresów
Aby odczytać z arkusza kalkulacyjnego wiele nieciągłych zakresów wartości, użyj żądania spreadsheets.values.batchGet
, które umożliwia określenie kilku zakresów do pobrania:
Google Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Odpowiedź na to żądanie jest zwracana jako obiekt BatchGetValuesResponse
, który zawiera spreadsheetId
i listę obiektów ValueRange
.
Zapis
Aby zapisać dane w arkuszu, potrzebujesz identyfikatora arkusza kalkulacyjnego, zakresu komórek w notacji A1 i danych, które chcesz zapisać w odpowiednim obiekcie treści żądania. Więcej informacji o identyfikatorach arkuszy kalkulacyjnych i notacji A1 znajdziesz w artykule Przegląd interfejsu Google Sheets API.
Aktualizacje wymagają prawidłowego parametru ValueInputOption
. W przypadku pojedynczych aktualizacji jest to wymagany parametr zapytania. W przypadku aktualizacji zbiorczych ten parametr jest wymagany w treści żądania. Parametr ValueInputOption
określa, jak należy interpretować dane wejściowe i czy ciągi wejściowe mają być analizowane, czy nie. Opis znajdziesz w tej tabeli:
ValueInputOption | Opis |
---|---|
RAW | Dane wejściowe nie są analizowane i są wstawiane jako ciąg znaków. Na przykład po wpisaniu „=1+2” w komórce pojawi się ciąg znaków „=1+2”, a nie formuła. (Wartości inne niż ciągi tekstowe, np. wartości logiczne lub liczby, są zawsze traktowane jako RAW ). |
USER_ENTERED | Dane wejściowe są analizowane dokładnie tak, jakby zostały wpisane w interfejsie Arkuszy. Na przykład „1 marca 2016 r.” stanie się datą, a „=1+2” – formułą. Formaty można też wywnioskować, więc „100,15 zł” staje się liczbą z formatowaniem waluty. |
Poniżej znajdziesz opis metod aktualizacji pojedynczej i zbiorczej. Przykłady podstawowych operacji zapisu znajdziesz w sekcji Podstawowe operacje zapisu.
Zapisywanie w jednym zakresie
Aby zapisać dane w jednym zakresie, użyj żądania spreadsheets.values.update
:
Google Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Treść żądania aktualizacji musi być obiektem ValueRange
, ale jedynym wymaganym polem jest values
. Jeśli podasz wartość range
, musi ona być zgodna z zakresem w adresie URL. W ValueRange
możesz opcjonalnie określić majorDimension
. Domyślnie używany jest znak ROWS
. Jeśli podasz COLUMNS
, każda tablica wewnętrzna zostanie zapisana w kolumnie zamiast w wierszu.
Podczas aktualizacji wartości bez danych są pomijane. Aby wyczyścić dane, użyj pustego ciągu znaków ("").
Wpisz kilka zakresów
Jeśli chcesz zapisać kilka nieciągłych zakresów, możesz użyć tego żądania:spreadsheets.values.batchUpdate
Google Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Treść zbiorczego żądania aktualizacji musi być obiektem BatchUpdateValuesRequest
zawierającym ValueInputOption
i listę obiektów ValueRange
(po jednym dla każdego zapisanego zakresu). Każdy obiekt ValueRange
określa własne range
, majorDimension
i dane wejściowe.
Dołączanie wartości
Aby dodać dane po tabeli danych w arkuszu, użyj żądania spreadsheets.values.append
:
Google Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Treść żądania aktualizacji musi być obiektem ValueRange
, ale jedynym wymaganym polem jest values
. Jeśli podasz wartość range
, musi ona być zgodna z zakresem w adresie URL. W ValueRange
możesz opcjonalnie określić majorDimension
. Domyślnie używany jest znak ROWS
. Jeśli podasz COLUMNS
, każda tablica wewnętrzna zostanie zapisana w kolumnie zamiast w wierszu.
Zakres wejściowy służy do wyszukiwania istniejących danych i znajdowania w nim „tabeli”. Wartości są dołączane do następnego wiersza tabeli, zaczynając od pierwszej kolumny. Na przykład znak Sheet1
wygląda tak:
A | B | C | D | E | |
1 | x | r. | Z | ||
2 | x | r. | Z | ||
3 | |||||
4 | x | r. | |||
5 | r. | Z | |||
6 | x | r. | Z | ||
7 |
Arkusz zawiera 2 tabele: A1:C2
i B4:D6
. Dołączone wartości będą zaczynać się od B7
w przypadku wszystkich tych danych wejściowych: range
Sheet1
, ponieważ przeanalizuje wszystkie dane w arkuszu i stwierdzi, że tabela wB4:D6
jest ostatnią tabelą.B4
lubC5:D5
, ponieważ oba te pola znajdują się w tabeliB4:D6
.B2:D4
, ponieważ ostatnią tabelą w zakresie jest tabelaB4:D6
(mimo że zawiera ona też tabelęA1:C2
).A3:G10
, ponieważ ostatnią tabelą w zakresie jest tabelaB4:D6
(mimo że zaczyna się przed nią i kończy po niej).
Poniższe dane wejściowe range
nie zaczną się zapisywać o godzinie B7
:
A1
zacznie pisać odA3
, ponieważ znajduje się ona w tabeliA1:C2
.E4
zacznie pisać odE4
, ponieważ nie znajduje się on w żadnej tabeli. (A4
również zacznie pisać oA4
z tych samych powodów).
Możesz też wybrać, czy chcesz zastąpić istniejące dane po tabeli, czy wstawić nowe wiersze dla nowych danych. Domyślnie dane wejściowe nadpisują dane po tabeli. Aby zapisać nowe dane w nowych wierszach, użyj InsertDataOption
i określ insertDataOption=INSERT_ROWS
.
Więcej informacji o limitach komórek i wierszy w Arkuszach znajdziesz w artykule Pliki, które możesz przechowywać na Dysku Google.