Arkusze mogą zawierać wiele arkuszy, a każdy z nich może mieć dowolną liczbę wierszy lub kolumn. Komórka to lokalizacja na przecięciu konkretnego wiersza i kolumny i może zawierać wartość danych. Interfejs API Arkuszy Google udostępnia zasób spreadsheets.values
umożliwiający odczytywanie i zapisywanie wartości.
Na tej stronie opisujemy podstawy korzystania z zasobu spreadsheets.values
. Jeśli chcesz wstawić w arkuszu wiersze lub zaktualizować formatowanie i inne właściwości, musisz użyć metody spreadsheets.batchUpdate
opisanej w sekcji Aktualizowanie arkuszy kalkulacyjnych.
Metody
Zasób spreadsheets.values
udostępnia poniższe metody odczytu i zapisu wartości, każdą z osobna dla konkretnego zadania:
Dostęp do zakresu | Czytanie | Pisarstwo |
---|---|---|
Pojedynczy zakres | spreadsheets.values.get |
spreadsheets.values.update |
Wiele zakresów | spreadsheets.values.batchGet |
spreadsheets.values.batchUpdate |
Dołączanie | spreadsheets.values.append |
Ogólnie dobrze jest łączyć wiele odczytów lub aktualizacji za pomocą metod batchGet
i batchUpdate
, ponieważ zwiększa to wydajność.
Przykłady każdej z tych metod znajdziesz na stronach z przykładami na temat czytania podstawowego i podstawowego pisania. 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 danego zakresu. Jeśli określisz zakres bez identyfikatora arkusza (A1:B2
), żądanie zostanie wykonane w pierwszym arkuszu w arkuszu kalkulacyjnym. Więcej informacji o identyfikatorach arkuszy kalkulacyjnych i notacji A1 znajdziesz w artykule Omówienie interfejsu API Arkuszy Google.
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 dateTimeRenderOption
należy używać tylko wtedy, gdy valueRenderOption
nie zawiera wartości FORMATTED_VALUE
.
Nie ma wyraźnego limitu ilości zwracanych danych. Błędy nie zwracają żadnych danych. Puste końcowe wiersze i kolumny są pomijane.
Poniżej opisano metody pobierania w pojedynczej i grupowej. Przykłady podstawowych operacji odczytu znajdziesz w sekcji Odczyt podstawowy.
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
.
Odczytaj wiele zakresów
Aby odczytać z arkusza kalkulacyjnego 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
zawierający spreadsheetId
i listę obiektów ValueRange
.
Zapis
Aby zapisywać coś w arkuszu, potrzebujesz identyfikatora arkusza kalkulacyjnego, zakresu komórek w notacji A1 oraz danych, które chcesz zapisywać 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 interpretacji danych wejściowych oraz to, czy ciągi wejściowe mają być analizowane, czy nie. Opisaliśmy to w tej tabeli:
ValueInputOption |
Opis |
---|---|
RAW |
Dane wejściowe nie są analizowane i zostały wstawione jako ciąg. Na przykład wpisanie ciągu „=1+2” spowoduje umieszczenie w komórce ciągu, a nie formuły, czyli „=1+2”. Wartości inne niż ciągi, takie jak wartości logiczne i liczby, są zawsze obsługiwane jako RAW . |
USER_ENTERED |
Dane wejściowe są analizowane dokładnie tak, jakby były wprowadzane w interfejsie Arkuszy. Na przykład „1 marca 2016 r.” stanie się datą, a „=1+2” stanie się formułą. Formaty również można wywnioskować, więc „100,15 PLN” staje się liczbą z formatowaniem waluty. |
Poniżej opisano metody aktualizacji w pojedynczej i zbiorczej. Przykłady podstawowych operacji zapisu znajdziesz w artykule o podstawowym pisaniu.
Zapisz w jednym zakresie
Aby zapisać dane w pojedynczym zakresie, użyj żądania spreadsheets.values.update
:
Google Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Treść żądania aktualizacji musi być obiektem ValueRange
, chociaż jedynym wymaganym polem jest values
. Jeśli jest określony parametr range
, musi on być zgodny z zakresem w adresie URL. W polu ValueRange
możesz opcjonalnie określić jego majorDimension
.
Domyślnie używana jest etykieta ROWS
. Jeśli określono COLUMNS
, każda tablica wewnętrzna 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ść żądania aktualizacji zbiorczej musi być obiektem BatchUpdateValuesRequest
zawierającym ValueInputOption
i listę obiektów ValueRange
(po 1 na każdy zapisany zakres). Każdy obiekt ValueRange
określa własne dane range
, majorDimension
i 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
, chociaż jedynym wymaganym polem jest values
. Jeśli jest określony parametr range
, musi on być zgodny z zakresem w adresie URL. W polu ValueRange
możesz opcjonalnie określić jego majorDimension
.
Domyślnie używana jest etykieta ROWS
. Jeśli określono COLUMNS
, każda tablica wewnętrzna jest zapisywana w kolumnie, a nie w wierszu.
Zakres danych wejściowych 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. Weźmy na przykład Sheet1
, który wygląda tak:
O | 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
. Dodane wartości rozpoczynają się od B7
w przypadku wszystkich tych danych wejściowych range
:
Sheet1
, ponieważ sprawdzi wszystkie dane w arkuszu i ustali, że tabela wB4:D6
jest ostatnią tabelą.B4
lubC5:D5
, ponieważ oba są w tabeliB4:D6
.B2:D4
, ponieważ ostatnia tabela w zakresie jest tabeląB4:D6
(pomimo że zawiera 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).
Te dane wejściowe range
nie zaczęłyby zapisywać informacji od B7
:
- Funkcja
A1
zacznie pisać odA3
, bo jest to tabelaA1:C2
. - Funkcja
E4
zacznie pisać odE4
, ponieważ nie znajduje się w żadnej tabeli. (Z tych samych powodówA4
może też zacząć pisać na adresA4
).
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 znajdujące się po tabeli. Aby zapisać nowe dane w nowych wierszach, użyj funkcji InsertDataOption
i wpisz 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.