Arkusze mogą składać się z wielu arkuszy, z których każdy może zawierać dowolną liczbę wierszy lub kolumn. Komórka to lokalizacja na przecięciem konkretnego wiersza i kolumny. Może zawierać wartość danych. Interfejs Google Arkuszy API udostępnia zasób spreadsheets.values
, który umożliwia odczytywanie i zapisywanie wartości.
Na tej stronie znajdziesz podstawowe informacje na temat korzystania z zasobu spreadsheets.values
. Jeśli chcesz wstawić wiersze lub zaktualizować formatowanie bądź 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 odczytywania i zapisywania wartości, każdą dla konkretnego zadania:
Dostęp do zakresu | Materiały do przeczytania | Pisarstwo |
---|---|---|
Jeden zakres | spreadsheets.values.get |
spreadsheets.values.update |
Wiele zakresów | spreadsheets.values.batchGet |
spreadsheets.values.batchUpdate |
Dołączam | spreadsheets.values.append |
Ogólnie warto połączyć kilka odczytów lub aktualizacji z metodami batchGet
i batchUpdate
, ponieważ zwiększa to wydajność.
Przykłady każdej z tych metod znajdziesz na przykładach dotyczących czytania podstawowego i pisania podstawowego. Wszystkie przykłady znajdziesz na stronie z ich omówieniem.
Odczyt
Aby odczytać wartości danych z arkusza, potrzebujesz identyfikatora arkusza kalkulacyjnego i adnotacji A1 dla zakresu. Określenie zakresu bez identyfikatora arkusza (A1:B2
) oznacza, że żądanie jest wykonywane na pierwszym arkuszu w arkuszu kalkulacyjnym. Więcej informacji o identyfikatorach arkuszy kalkulacyjnych i zapisie A1 znajdziesz w artykule Omówienie interfejsu API Arkuszy Google.
Jest kilka opcjonalnych parametrów zapytania, które określają format wyników:
Parametr formatu | Wartość domyślna |
---|---|
majorDimension |
ILE.WIERSZY |
valueRenderOption |
FORMATTED_VALUE |
dateTimeRenderOption |
SERIAL_NUMBER |
Pamiętaj, że dateTimeRenderOption
należy używać tylko wtedy, gdy valueRenderOption
ma wartość inną niż FORMATTED_VALUE
.
Nie ma wyraźnego limitu zwracanych danych. Błędy nie zwracają żadnych danych. Puste końcowe wiersze i kolumny są pomijane.
Metody pobierania pojedynczej i grupowej zostały opisane poniżej. Przykłady podstawowych operacji odczytu znajdziesz w sekcji Podstawowe operacje odczytu.
Odczytaj pojedynczy zakres
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
.
Odczytuj wiele zakresów
Aby odczytać w arkuszu kalkulacyjnym wiele 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
.
Napisz
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 Omówienie interfejsu API Arkuszy Google.
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. Element ValueInputOption
określa sposób interpretowania danych wejściowych oraz to, czy ciągi wejściowe są analizowane, jak opisano w tej tabeli:
ValueInputOption |
Opis |
---|---|
RAW |
Dane wejściowe nie są przeanalizowane i zostały wstawione jako ciąg znaków. Na przykład wpisanie „=1+2” spowoduje umieszczenie w komórce ciągu, a nie formuły. Wartości niebędące ciągami, takie jak wartości logiczne czy liczby, są zawsze obsługiwane jako RAW . |
USER_ENTERED |
Dane wejściowe są analizowane dokładnie tak, jakby zostały wprowadzone w interfejsie Arkuszy. Na przykład „1 marca 2016 r.” stanie się datą, a ciąg „=1+2” stanie się formułą. Formaty można również wywnioskować, więc „100,15 PLN” staje się liczbą z sformatowaniem waluty. |
Poniżej opisujemy jednorazowe i zbiorcze metody aktualizacji. Przykłady podstawowych operacji zapisu znajdziesz w artykule Podstawowe pisanie.
Zapisz 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
, a jedynym wymaganym polem jest values
. Jeśli określisz parametr range
, musi on pasować do zakresu w adresie URL. W ValueRange
możesz opcjonalnie podać jej majorDimension
.
Domyślnie używana jest ROWS
. Jeśli podasz COLUMNS
, każda wewnętrzna tablica jest zapisywana w kolumnie, a nie w wierszu.
Podczas aktualizowania wartości bez danych są pomijane. Aby wyczyścić dane, użyj pustego ciągu znaków („”).
Zapisz wiele zakresów
Jeśli chcesz zapisać wiele nieciągłych zakresów, możesz użyć żądania spreadsheets.values.batchUpdate
:
Google Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Treść zbiorczego żądania aktualizacji musi być obiektem BatchUpdateValuesRequest
, który zawiera obiekt ValueInputOption
i listę obiektów ValueRange
(po jednym dla każdego zapisanego zakresu). Każdy obiekt ValueRange
określa własne dane range
i majorDimension
oraz własne dane wejściowe.
Dołącz 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
, a jedynym wymaganym polem jest values
. Jeśli określisz parametr range
, musi on pasować do zakresu w adresie URL. W ValueRange
możesz opcjonalnie podać jej majorDimension
.
Domyślnie używana jest ROWS
. Jeśli podasz COLUMNS
, każda wewnętrzna tablica jest zapisywana w kolumnie, a nie 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 tabeli. Weźmy na przykład Sheet1
, który 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 |
W arkuszu są 2 tabele: A1:C2
i B4:D6
. Dołączone wartości będą rozpoczynać się o B7
w przypadku wszystkich tych danych wejściowych range
:
Sheet1
, ponieważ sprawdzi wszystkie dane w arkuszu i ustali, że tabela pod adresemB4:D6
jest ostatnią tabelą.B4
lubC5:D5
, bo oba są w tabeliB4:D6
.B2:D4
, ponieważ ostatnia tabela w zakresie to tabelaB4:D6
(mimo że zawiera ona też tabelęA1:C2
).A3:G10
, ponieważ ostatnia tabela w zakresie to tabelaB4:D6
(mimo że zaczyna się przed nią i kończy po niej).
W przypadku tych danych wejściowych range
nie można było zapisać danych od B7
:
- Funkcja
A1
zaczęłaby pisać oA3
, bo jest ona w tabeliA1:C2
. - Funkcja
E4
mogłaby zacząć zapisywać dane oE4
, ponieważ nie ma go w żadnej tabeli. (z tych samych powodów funkcjaA4
również zaczęła pisać oA4
).
Możesz też zdecydować, 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 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.