Oprócz danych wartości zawartych w komórkach arkusz zawiera wiele innych typów danych, takich jak:
- Wymiary
- Formaty komórek i obramowania
- Zakresy nazwane
- Zakresy chronione
- Formatowanie warunkowe
To tylko niektóre z wielu rodzajów danych, które sterują wyglądem i działaniem arkusza kalkulacyjnego. Metoda spreadsheets.batchUpdate
pozwala zaktualizować dowolne szczegóły arkusza kalkulacyjnego. Zmiany są grupowane w partiach, aby w przypadku niepowodzenia jednego żądania żadne z innych (potencjalnie zależnych) zmian nie zostały zapisane.
Na tej stronie znajdziesz podstawowe informacje o metodach spreadsheets.batchUpdate
. Jeśli chcesz odczytywać i zapisywać dane wartości komórek, możesz też użyć zasobu spreadsheets.values
opisanego w artykule Odczytywanie i zapisywanie wartości komórek.
Kategorie operacji
Poszczególne operacje obsługiwane przez spreadsheets.batchUpdate
można podzielić na te ogólne kategorie:
Kategoria | Opis |
---|---|
Dodaj (i Duplikuj). | Dodawanie nowych obiektów (czasami na podstawie starych, jak w przypadku zduplikowanych żądań). |
Aktualizuj (i Ustaw) | zaktualizować określone właściwości obiektu, zazwyczaj pozostawiając stare właściwości bez zmian (żądanie Set zastępuje poprzednie dane); |
Usuń | Usuwanie obiektów. |
W następnej sekcji te kategorie są używane do opisywania zachowania konkretnych operacji.
Operacje zbiorczej aktualizacji
Metoda spreadsheets.batchUpdate
działa, przyjmując co najmniej 1 obiekt Request, z których każdy określa jeden rodzaj żądania do wykonania. Istnieją różne rodzaje żądań. Oto podział typów żądań na różne kategorie.
Istnieją też dodatkowe żądania, które naśladują działania użytkowników polegające na manipulowaniu 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ń „update” wymaga masek pól. Są to rozdzielane przecinkami listy pól, które mają zaktualizować tylko niektóre pola obiektu, pozostawiając inne pola bez zmian. Maska pola *
jest traktowana jak symbol wieloznaczny i jest skrótem do określenia 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 funkcji 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 odpowiadające jej żądanie. Niektóre żądania nie mają odpowiedzi, więc odpowiedź jest pusta.
Zazwyczaj żądania „add” mają 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:
- Zmienia tytuł arkusza kalkulacyjnego za pomocą zmiennej
title
. - Znajduje i zastępuje wartości komórek w arkuszu kalkulacyjnym za pomocą zmiennych
find
ireplacement
.