Arkusze mogą zawierać wiele arkuszy, a każdy z nich może zawierać 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 opisaliśmy podstawy korzystania z zasobu spreadsheets.values
. Jeśli chcesz wstawić w arkuszu wiersze lub zaktualizować formatowanie i inne właściwości, użyj metody spreadsheets.batchUpdate
opisanej w artykule Aktualizowanie arkuszy kalkulacyjnych.
Metody
Zasób spreadsheets.values
udostępnia te metody odczytywania i zapisywania wartości, każdą w konkretnym zadaniu:
Dostęp do zakresu | Reading | 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 warto łączyć kilka 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 odczytu podstawowego i podstawowego pisania. Listę wszystkich przykładów znajdziesz na stronie z omówieniem przykładów.
Odczyt
Aby odczytać wartości danych z arkusza, potrzebujesz identyfikatora arkusza i notacji A1 dla zakresu. Jeśli określisz zakres bez identyfikatora arkusza (A1:B2
), żądanie zostanie wykonane na pierwszym arkuszu w arkuszu kalkulacyjnym. Więcej informacji o identyfikatorach arkuszy 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
używaj tylko wtedy, gdy valueRenderOption
nie ma wartości FORMATTED_VALUE
.
Nie ma wyraźnego ograniczenia 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.
Odczytuj dane o pojedynczym zakresie
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 odczytywać wiele nieciągłych zakresów wartości z arkusza kalkulacyjnego, 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 spreadsheetId
i listę obiektów ValueRange
.
Zapis
Aby pisać 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 i notacji A1 znajdziesz w artykule Omówienie interfejsu API Arkuszy Google.
Aktualizacje wymagają prawidłowego parametru ValueInputOption
.
W przypadku aktualizacji pojedynczych jest 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 i to, czy ciągi wejściowe mają być analizowane, czy nie, zgodnie z opisem w tej tabeli:
ValueInputOption |
Opis |
---|---|
RAW |
Dane wejściowe nie są analizowane i są wstawiane jako ciąg znaków. Jeśli na przykład wpiszesz „=1+2”, w komórce zostanie umieszczony ciąg, a nie formuła. Wartości inne niż ciągi znaków, takie jak wartości logiczne i liczby, są zawsze obsługiwane 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” stanie się formułą. Formaty też można wywnioskować, więc „100,15 USD” stanie się liczbą z formatowaniem waluty. |
Poniżej opisano metody pojedynczej i zbiorczej aktualizacji. Przykłady podstawowych operacji zapisu znajdziesz w artykule Podstawowe informacje o 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 określono range
, musi on być zgodny z zakresem w adresie URL. W polu ValueRange
możesz opcjonalnie określić jego majorDimension
.
Domyślnie używany jest 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
, 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
, 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 określono range
, musi on być zgodny z zakresem w adresie URL. W polu ValueRange
możesz opcjonalnie określić jego majorDimension
.
Domyślnie używany jest 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 tabeli. Weźmy na przykład atrybut 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 będą zaczynać 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
(mimo że zawiera też tabelęA1:C2
).A3:G10
, ponieważ ostatnia tabela w zakresie to tabelaB4:D6
(mimo że rozpoczyna się przed nią i kończy po niej).
Te dane wejściowe range
nie zaczęłyby zapisywać informacji po B7
:
- Funkcja
A1
zacznie pisać odA3
, bo ta wartość znajduje się w tabeliA1:C2
. E4
zacznie wpisywać tekst odE4
, ponieważ nie znajduje się w żadnej tabeli. (A4
z tych samych powodów zacząłby też pisać na adresA4
).
Dodatkowo możesz wybrać, czy chcesz zastąpić istniejące dane po tabeli, czy wstawić nowe wiersze na nowe dane. Domyślnie dane wejściowe
zastępują dane 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.