Oprócz wartości zawartych w komórkach arkusz kalkulacyjny zawiera wiele innych typów danych, takich jak:
- Wymiary
- Formaty komórek i obramowanie
- Zakresy nazwane
- Zakresy chronione
- Formatowanie warunkowe
Są to niektóre z wielu rodzajów danych, które wpływają na wygląd i działanie arkusza kalkulacyjnego. Metoda spreadsheets.batchUpdate
umożliwia aktualizowanie wszystkich tych szczegółów arkusza kalkulacyjnego. Zmiany są grupowane w grupie, więc jeśli jedno żądanie zakończy się niepowodzeniem, nie zostaną zapisane żadne pozostałe (potencjalnie zależne) zmiany.
Na tej stronie opisujemy podstawy korzystania z metody spreadsheets.batchUpdate
. Jeśli chcesz odczytywać i zapisywać dane o wartościach komórek, możesz też użyć zasobu spreadsheets.values
opisanego w artykule Odczytywanie i zapisywanie wartości komórek.
Kategorie działań
Operacje obsługiwane przez spreadsheets.batchUpdate
można podzielić na te ogólne kategorie:
Kategoria | Opis |
---|---|
Dodaj (i Duplikuj) | Dodaj nowe obiekty (czasami oparte na starych, np. w przypadku powielonych żądań). |
Aktualizuj (i Ustaw) | Aktualizuj określone właściwości obiektu, zwykle pozostawiając stare właściwości bez zmian (podczas gdy żądanie Set zastępuje wcześniejsze dane). |
Usuń | Usuń obiekty. |
W następnej sekcji użyjesz tych kategorii, aby opisać zachowanie konkretnych operacji.
Operacje aktualizacji zbiorczej
Metoda spreadsheets.batchUpdate
działa, przyjmując co najmniej 1 obiekt Request, z których każdy określa pojedynczy rodzaj żądania do wykonania. Jest wiele różnych rodzajów wniosków. Oto zestawienie typów żądań
pogrupowanych w różne kategorie.
Istnieją też dodatkowe żądania, które udają działania użytkownika w celu manipulowania danymi:
- AutoFillRequest
- CutPasteRequest
- CopyPasteRequest
- FindReplaceRequest
- PasteDataRequest
- TextToColumnsRequest
- SortRangeRequest
Limity
Więcej informacji o limitach komórek i wierszy w Arkuszach Google znajdziesz w artykule Pliki, które możesz przechowywać na Dysku Google.
Maski pól
Wiele żądań aktualizacji wymaga masek pól. Jest to rozdzielana przecinkami lista pól, na których można aktualizować tylko niektóre pola w obiekcie, a pozostałe pola pozostawić bez zmian. Maska pola *
jest traktowana jak symbol wieloznaczny i jest skrótem służącym do określania wszystkich pól w wiadomości (co oznacza, że pole może powrócić do stanu domyślnego, jeśli nie określisz dla niego wartości w żądaniu).
Więcej informacji o maskach pól znajdziesz w artykule Używanie masek pól.
W tym przykładzie użyto parametru UpdateSpreadsheetPropertiesRequest
do zaktualizowania tylko tytułu arkusza kalkulacyjnego:
Prośba:
POST .../v4/spreadsheets/spreadsheetId:batchUpdate
Treść żądania:
{
"requests": [{
"updateSpreadsheetProperties": {
"properties": {"title": "TITLE"},
"fields": "title"
}
}]
}
Zastąp TITLE nowym tytułem arkusza kalkulacyjnego.
Odpowiedzi
Podczas aktualizowania arkusza kalkulacyjnego niektóre rodzaje żądań mogą zwracać odpowiedzi. Są one zwracane w tablicy, a każda odpowiedź zajmuje ten sam indeks co odpowiednie żądanie. Niektóre żądania nie mają odpowiedzi – w przypadku nich odpowiedź jest pusta.
Zwykle żądania „add” zawierają odpowiedzi, które zwracają informacje takie jak identyfikator dodanego obiektu. Listę obsługiwanych odpowiedzi znajdziesz w sekcji Odpowiedzi.
Przykład
Ten przykładowy kod wykonuje te działania:
- Aktualizuje tytuł arkusza kalkulacyjnego za pomocą zmiennej
title
. - Wyszukuje i zastępuje wartości komórek w arkuszu kalkulacyjnym przy użyciu zmiennych
find
ireplacement
.