Arkusze kalkulacyjne mogą mieć wiele arkuszy, a każdy z nich może mieć dowolną liczbę wierszy lub kolumn. Komórka to lokalizacja na przecięciu określonego wiersza i kolumny, która może zawierać wartość danych. Interfejs Google Sheets API udostępnia zasób spreadsheets.values
, który umożliwia odczytywanie i zapisywanie wartości.
Na tej stronie znajdziesz podstawowe informacje o zasobach 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 sekcji 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 konkretnego zadania:
Dostęp do zasięgu | Czytanie | Pisanie |
---|---|---|
Pojedynczy zakres | spreadsheets.values.get |
spreadsheets.values.update |
Wiele zakresów | spreadsheets.values.batchGet |
spreadsheets.values.batchUpdate |
Dołączanie | spreadsheets.values.append |
Zazwyczaj warto łączyć większą liczbę odczytów lub aktualizacji z metodami batchGet
i batchUpdate
, ponieważ zwiększa to wydajność.
Przykłady każdej z tych metod znajdziesz na stronach z przykładami czytania i pisania. Aby wyświetlić wszystkie przykłady, przejdź na stronę z ich omówieniem.
Odczyt
Aby odczytać wartości danych z arkusza, musisz mieć identyfikator arkusza kalkulacyjnego i notację A1 zakresu. Określanie zakresu bez identyfikatora arkusza (A1:B2
) oznacza, że żądanie jest wykonywane 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 zależy od kilku opcjonalnych parametrów zapytania:
Parametr formatu | Wartość domyślna |
---|---|
majorDimension |
ILE.WIERSZY |
valueRenderOption |
FORMATTED_VALUE |
dateTimeRenderOption |
SERIAL_NUMBER |
Pamiętaj, że należy używać wartości dateTimeRenderOption
tylko wtedy, gdy wartość valueRenderOption
nie jest równa FORMATTED_VALUE
.
Nie ma wyraźnego limitu liczby zwracanych danych. Błędy nie zwracają żadnych danych. Pustych końcowych wierszy i kolumn nie uwzględnia się.
Metody pobierania pojedynczych i wielu elementów opisaliśmy poniżej. Przykłady podstawowych operacji odczytu znajdziesz w sekcji Podstawowe odczyty.
Czytanie pojedynczego zakresu
Aby odczytać pojedynczy zakres wartości z arkusza kalkulacyjnego, użyj zapytania spreadsheets.values.get
:
Google Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Odpowiedź na to żądanie jest zwracana jako obiekt ValueRange
.
Czytanie wielu zakresów
Aby odczytać z arkusza kalkulacyjnego kilka nieciągłych zakresów wartości, użyj żądania spreadsheets.values.batchGet
, które pozwala określić kilka 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 obiekt spreadsheetId
i listę obiektów ValueRange
.
Zapis
Aby zapisać dane w arkuszu, musisz podać identyfikator arkusza kalkulacyjnego, zakres komórek w notacji A1 oraz dane, które chcesz zapisać w odpowiednim obiekcie treści żądania. Więcej informacji o identyfikatorach arkuszy kalkulacyjnych i notacji A1 znajdziesz w artykule Omówienie 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 ciele żądania. Opcja ValueInputOption
określa, jak należy interpretować dane wejściowe i czy należy zanalizować ciągi wejściowe. Opis znajdziesz w tabeli poniżej:
ValueInputOption |
Opis |
---|---|
RAW |
Dane wejściowe nie są analizowane i są wstawiane jako ciąg znaków. Na przykład podanie wartości „=1+2” powoduje umieszczenie w komórce ciągu znaków, a nie formuły „=1+2”. (wartości inne niż tekstowe, takie jak wartości logiczne czy liczby, są zawsze traktowane jako RAW ). |
USER_ENTERED |
Dane wejściowe są analizowane tak, jakby zostały wprowadzone w interfejsie Arkuszy. Na przykład „1 marca 2016” stanie się datą, a „=1+2” – formułą. Formaty można też wywnioskować, więc „100.15 PLN” staje się liczbą z formatem waluty. |
Metody pojedynczej i zbiorczej aktualizacji opisane są poniżej. Przykłady podstawowych operacji zapisu znajdziesz w sekcji Podstawowe zapisywanie.
Zapisywanie w jednym zakresie
Aby zapisać dane w pojedynczym zakresie, użyj prośby 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 podano wartość range
, musi ona być zgodna z zakresem w adresie URL. W ValueRange
możesz opcjonalnie podać majorDimension
.
Domyślnie używana jest wartość ROWS
. Jeśli podano parametr COLUMNS
, każdy wewnętrzny tablica jest zapisywana w kolumnie, a nie w wierszu.
Podczas aktualizacji wartości bez danych są pomijane. Aby wyczyścić dane, użyj pustego ciągu znaków („”).
Pisanie wielu zakresów
Jeśli chcesz zapisać kilka zakresów nieciągłych, możesz użyć żądania spreadsheets.values.batchUpdate
:
Google Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Treść żądania zbiorczego musi być obiektem BatchUpdateValuesRequest
, który zawiera obiekt ValueInputOption
i listę obiektów ValueRange
(po jednym dla każdego zapisywanego zakresu). Każdy obiekt ValueRange
określa własne dane wejściowe range
, majorDimension
i dane wejściowe.
Dołączanie wartości
Aby dołączyć 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 podano wartość range
, musi ona być zgodna z zakresem w adresie URL. W ValueRange
możesz opcjonalnie podać majorDimension
.
Domyślnie używana jest wartość ROWS
. Jeśli podano parametr COLUMNS
, każdy wewnętrzny tablica jest zapisywana w kolumnie, a nie w wierszu.
Zakres danych wejściowych służy do wyszukiwania istniejących danych i znajdowania w tym zakresie „tabeli”. Wartości są dołączane do następnego wiersza tabeli, zaczynając od pierwszej kolumny tabeli. Na przykład Sheet1
może wyglądać tak:
A | B | C | D | E | |
1 | x | y | Z | ||
2 | x | y | Z | ||
3 | |||||
4 | x | y | |||
5 | y | Z | |||
6 | x | y | Z | ||
7 |
Na arkuszu znajdują się 2 tabele: A1:C2
i B4:D6
. Dodane wartości będą się zaczynać od B7
we wszystkich tych parametrach:range
Sheet1
, ponieważ sprawdzi wszystkie dane na arkuszu i ustali, że tabela w miejscuB4:D6
jest ostatnią.B4
lubC5:D5
, ponieważ obie te kolumny znajdują się w tabeliB4:D6
.B2:D4
, ponieważ ostatnia tabela w zakresie to tabelaB4:D6
(pomimo że zawiera ona też tabelęA1:C2
).A3:G10
, ponieważ ostatnia tabela w zakresie to tabelaB4:D6
(pomimo że zaczyna się przed nią i kończy po niej).
Te dane range
nie będą zapisywane w miejscu B7
:
A1
zacznie zapisywać dane odA3
, ponieważ jest to wartość w tabeliA1:C2
.E4
zacznie zapisywać dane odE4
, ponieważ nie znajduje się w żadnej tabeli. (A4
również zacznie pisać odA4
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 zastępują dane po tabeli. Aby zapisać nowe dane w nowych wierszach, użyj funkcji InsertDataOption
i podaj parametr insertDataOption=INSERT_ROWS
.
Więcej informacji o limitach komórek i wierszy w Arkuszach Google znajdziesz w artykule Pliki, które możesz przechowywać na Dysku Google.