Ten dokument opisuje podstawy korzystania z
spreadsheets.batchUpdate
metody w zasobie
spreadsheets.
Oprócz danych wartości zawartych w komórkach a arkusz kalkulacyjny zawiera wiele innych typów danych, takich jak:
- Wymiary
- Formaty i obramowania komórek
- Zakresy nazwane
- Zakresy chronione
- Formatowanie warunkowe
To tylko niektóre z wielu rodzajów danych, które kontrolują wygląd i działanie arkusza kalkulacyjnego. Metoda spreadsheets.batchUpdate umożliwia aktualizowanie dowolnych z tych szczegółów arkusza kalkulacyjnego. Zmiany są grupowane w pakiet, dzięki czemu jeśli jedno żądanie się nie powiedzie, żadne z pozostałych (potencjalnie zależnych) zmian nie zostaną zapisane.
Jeśli musisz odczytywać i zapisywać dane wartości komórek, możesz też użyć zasobu
spreadsheets.values
, jak opisano w artykule Odczytywanie i zapisywanie wartości komórek.
Typy operacji
Operacje obsługiwane przez metodę spreadsheets.batchUpdate można podzielić na te ogólne typy:
| Kategoria | Opis |
|---|---|
| Dodaj (i Duplikuj) | Dodawanie nowych obiektów (czasami na podstawie starych, jak w przypadku żądań Duplikuj). |
| Aktualizuj (i Ustaw) | Aktualizowanie niektórych właściwości obiektu, zwykle bez zmiany starych właściwości (natomiast żądanie Ustaw zastępuje poprzednie dane). |
| Usuń | Usuwanie obiektów. |
Te kategorie są używane w następnej sekcji do opisania działania konkretnych operacji.
Operacje aktualizacji zbiorczej
Metoda spreadsheets.batchUpdate działa poprzez pobieranie co najmniej 1
Request
obiektów, z których każdy określa pojedynczy rodzaj żądania do wykonania. W tabeli poniżej znajdziesz typy żądań aktualizacji zbiorczej pogrupowane według obiektu zasobu i typu operacji:
Żądania manipulowania danymi
Istnieją też dodatkowe żądania, które naśladują działania użytkownika związane z manipulowaniem danymi:
| Żądanie | Opis |
|---|---|
AutoFillRequest |
Automatycznie wypełnia więcej danych na podstawie istniejących danych. |
CopyPasteRequest |
Kopiuje dane z jednego obszaru i wkleja je do innego. |
CutPasteRequest |
Wycina dane z jednego obszaru i wkleja je do innego. |
DeleteDuplicatesRequest |
Usuwa wiersze zawierające zduplikowane wartości w określonych kolumnach zakresu komórek. |
FindReplaceRequest |
Znajduje i zastępuje wystąpienia tekstu innym tekstem. |
PasteDataRequest |
Wkleja dane (HTML lub rozdzielane) do arkusza. |
RandomizeRangeRequest |
Losuje kolejność wierszy w zakresie. |
SortRangeRequest |
Sortuje dane w zakresie. |
TextToColumnsRequest |
Konwertuje kolumnę tekstu na wiele kolumn tekstu. |
TrimWhitespaceRequest |
Usuwa z komórek białe znaki (takie jak spacje, tabulatory lub nowe wiersze). |
Więcej informacji o limitach komórek i wierszy w Arkuszach Google znajdziesz w artykule Pliki, które możesz przechowywać na Dysku Google.
Używanie masek pól do aktualizowania określonych pól
Wiele żądań aktualizacji wymaga a FieldMask. Maska pól to rozdzielana przecinkami lista pól używana do wskazywania, które pola w obiekcie mają zostać zaktualizowane, a które mają pozostać bez zmian. Użycie maski pól zapobiega przypadkowemu zastąpieniu pól, które nie są określone w żądaniu.
Więcej informacji o maskach pól znajdziesz w artykule Aktualizowanie za pomocą maski pól.
Poniższy przykładowy kod pokazuje, jak użyć
UpdateSpreadsheetPropertiesRequest
aby zaktualizować tylko tytuł arkusza kalkulacyjnego:
Żądanie
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
Treść żądania
{
"requests": [{
"updateSpreadsheetProperties": {
"properties": {"title": "TITLE"},
"fields": "title"
}
}]
}Zastąp TITLE nowym tytułem arkusza kalkulacyjnego.
Odpowiedzi na aktualizację zbiorczą
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, a w takich przypadkach odpowiedź jest pusta.
Zwykle żądania „dodaj” mają odpowiedzi, które zwracają informacje takie jak identyfikator dodanego obiektu. Listę obsługiwanych odpowiedzi znajdziesz w sekcji
Responses.
Przykładowy kod: aktualizacja zbiorcza arkusza kalkulacyjnego
Poniższy przykładowy kod pokazuje, jak wykonać te czynności:
- Zaktualizuj tytuł arkusza kalkulacyjnego za pomocą zmiennej
title. - Znajdź i zastąp wartości komórek w arkuszu kalkulacyjnym za pomocą zmiennych
findireplacement.