Interfejs API Arkuszy Google umożliwia zapisywanie wartości i formuł w komórkach, zakresach, zestawach zakresów i całych arkuszach. Przykłady na tej stronie pokazują, jak można wykonywać niektóre typowe operacje zapisu za pomocą zasobu spreadsheets.values
interfejsu Sheets API.
Wartości komórek można też zapisywać za pomocą metody spreadsheet.batchUpdate
, co może być przydatne, jeśli chcesz jednocześnie zaktualizować formatowanie komórki lub inne właściwości, na które zasób spreadsheets.values
nie ma wpływu. Jeśli na przykład chcesz skopiować zakres komórek z jednego arkusza do drugiego, zastępując jednocześnie formułę i formatowanie komórki, możesz użyć metody UpdateCellsRequest
z parametrem spreadsheet.batchUpdate
.
Jednak w przypadku zapisywania prostych wartości łatwiej jest użyć metody spreadsheets.values.update
lub metody spreadsheets.values.batchUpdate
.
Przykłady te są przedstawione w formie żądań HTTP, aby były neutralne językowo. Aby dowiedzieć się, jak zaimplementować zapisywanie w różnych językach za pomocą bibliotek klienta interfejsu API Google, przeczytaj artykuł Czytanie i zapisywanie wartości komórek.
W tych przykładach obiekt zastępczy SPREADSHEET_ID
wskazuje miejsce, w którym należy podać identyfikator arkusza kalkulacyjnego, który można znaleźć w adresie URL arkusza kalkulacyjnego. Zakresy, do których mają być zapisywane dane, są określane za pomocą notacji A1. Przykładowy zakres to Arkusz1!A1:D5.
Pisanie pojedynczego zakresu
Począwszy od nowej, pustej arkusza kalkulacyjnego, ten przykładowy kod spreadsheets.values.update
pokazuje, jak zapisać wartości w zakresie. Parametr zapytania ValueInputOption
jest wymagany i określa, czy zapisane wartości mają być analizowane (np. czy ciąg znaków ma być konwertowany na datę).
Treść żądania to obiekt ValueRange
, który opisuje wartości zakresu do zapisania. Pole majorDimension
wskazuje, że tablice to listy wartości uporządkowane według wierszy. Istniejące wartości w zakresie docelowym zostaną zastąpione.
Protokół żądania przedstawiono poniżej.
PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
/values/Sheet1!A1:D5?valueInputOption=VALUE_INPUT_OPTION
{ "range": "Sheet1!A1:D5", "majorDimension": "ROWS", "values": [ ["Item", "Cost", "Stocked", "Ship Date"], ["Wheel", "$20.50", "4", "3/1/2016"], ["Door", "$15", "2", "3/15/2016"], ["Engine", "$100", "1", "3/20/2016"], ["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"] ], }
Odpowiedź składa się z obiektu UpdateValuesResponse
, takiego jak ten:
{
"spreadsheetId": SPREADSHEET_ID
,
"updatedRange": "Sheet1!A1:D5",
"updatedRows": 5,
"updatedColumns": 4,
"updatedCells": 20,
}
Wynikowy arkusz będzie wyglądał tak:
A | B | C | D | |
1 | Element | Koszt | W magazynie | Data wysyłki |
2 | Diabelski młyn | 20,50 PLN | 4 | 01.03.2016 r. |
3 | Drzwi | 15 | 2 | 15.03.2016 r. |
4 | Silnik | 100 zł | 1 | 20.03.2016 |
5 | Sumy | 135,50 PLN | 7 | 20.03.2016 |
Zapisz wybiórczo w zakresie
Podczas zapisywania wartości w zakresie można uniknąć zmiany niektórych istniejących komórek przez ustawienie odpowiednich elementów tablicy na null
. Komórkę możesz też wyczyścić, wpisując w niej pusty ciąg znaków (""
).
Począwszy od arkusza zawierającego te same dane, które zostały wygenerowane w powyższym przykładzie, poniższy przykładowy kod spreadsheets.values.update
pokazuje, jak zapisać wartości w zakresie B1:D4, pozostawiając niektóre komórki bez zmian i usuwając inne. Parametr zapytania ValueInputOption
jest wymagany i określa, czy zapisane wartości mają być analizowane (np. czy ciąg znaków ma być konwertowany na datę).
Treść żądania to obiekt ValueRange
opisujący wartości zakresu do zapisania. Pole majorDimension
wskazuje, że tablice są listami wartości uporządkowanych według kolumn.
Protokół żądania przedstawiono poniżej.
PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
/values/Sheet1!B1?valueInputOption=VALUE_INPUT_OPTION
{ "range": "Sheet1!B1", "majorDimension": "COLUMNS", "values": [ [null,"$1","$2", ""], [], [null,"4/1/2016", "4/15/2016", ""] ] }
W polu values
znajdują się zmiany wprowadzone w każdej kolumnie w zakresie. Pierwszy tablica wskazuje, że komórka B1 ma pozostać bez zmian (z powodu elementu tablicy null
), a komórka B4 ma zostać wyczyszczona (pusty ciąg znaków). Wartości komórek B2 i B3 zostały zaktualizowane. Trzecia tablica wykonuje te same operacje na kolumnie D, a druga pusta tablica wskazuje, że kolumna C ma pozostać bez zmian.
Odpowiedź zawiera obiekt UpdateValuesResponse
, na przykład:
{
"spreadsheetId": SPREADSHEET_ID
,
"updatedRange": "Sheet1!B1:D5",
"updatedRows": 3,
"updatedColumns": 2,
"updatedCells": 6,
}
Wygenerowany arkusz będzie wyglądał tak:
A | B | C | D | |
1 | Element | Koszt | W magazynie | Data wysyłki |
2 | Diabelski młyn | 1 USD | 4 | 01.04.2016 r. |
3 | Drzwi | 2 PLN | 2 | 15.04.2016 r. |
4 | Silnik | 1 | ||
5 | Sumy | 3 USD | 7 | 15.04.2016 r. |
Pamiętaj, że wiersz „Sumy”, mimo że nie został bezpośrednio zmieniony przez tę prośbę, uległ zmianie, ponieważ jego komórki zawierają formuły zależne od komórek, które zostały zmienione.
Pisanie do wielu zakresów
Począwszy od pustego arkusza, poniższy przykładowy kod spreadsheets.values.batchUpdate
pokazuje, jak zapisać wartości w zakresach Arkusz1!A1:A4 i Arkusz1!B1:D2. Istniejące wartości w zakresie docelowym zostaną zastąpione. Treść żądania składa się z obiektu ValueInputOption
, który pokazuje, jak interpretować dane wejściowe, oraz tablicy obiektów ValueRange
odpowiadających każdemu zakresowi zapisu. Pole majorDimension
określa, czy uwzględnione tablice mają być interpretowane jako tablice kolumn czy wierszy.
Protokół żądania przedstawiono poniżej.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
/values:batchUpdate
{ "valueInputOption": "VALUE_INPUT_OPTION", "data": [ { "range": "Sheet1!A1:A4", "majorDimension": "COLUMNS", "values": [ ["Item", "Wheel", "Door", "Engine"] ] }, { "range": "Sheet1!B1:D2", "majorDimension": "ROWS", "values": [ ["Cost", "Stocked", "Ship Date"], ["$20.50", "4", "3/1/2016"] ] } ] }
Odpowiedź składa się z obiektu zawierającego listę zaktualizowanych statystyk komórek oraz tablicy obiektów UpdateValuesResponse
, po jednym dla każdego zaktualizowanego zakresu. Na przykład:
{ "spreadsheetId":SPREADSHEET_ID
, "totalUpdatedRows": 4, "totalUpdatedColumns": 4, "totalUpdatedCells": 10, "totalUpdatedSheets": 1, "responses": [ { "spreadsheetId":SPREADSHEET_ID
, "updatedRange": "Sheet1!A1:A4", "updatedRows": 4, "updatedColumns": 1, "updatedCells": 4, }, { "spreadsheetId":SPREADSHEET_ID
, "updatedRange": "Sheet1!B1:D2", "updatedRows": 2, "updatedColumns": 3, "updatedCells": 6, } ], }
Wygenerowany arkusz będzie wyglądał tak:
A | B | C | D | |
1 | Element | Koszt | W magazynie | Data wysyłki |
2 | Diabelski młyn | 20,50 PLN | 4 | 01.03.2016 r. |
3 | Drzwi | |||
4 | Silnik | |||
5 |
Zapisywanie wartości bez analizowania
Począwszy od pustego arkusza, poniższy przykład kodu spreadsheets.values.update
pokazuje, jak zapisywać wartości w zakresie Arkusz1!A1:E1, ale używa parametru zapytania RAW
ValueInputOption
, aby zapobiec parsowaniu zapisanych ciągów jako formuł, wartości logicznych lub liczb. Występują one w postaci ciągów znaków, a wyrównanie tekstu jest wyrównane do lewej krawędzi arkusza.
Treść żądania to obiekt ValueRange
, który opisuje wartości zakresu do zapisania. Pole majorDimension
wskazuje, że tablice to listy wartości uporządkowane według wierszy. Istniejące wartości w zakresie docelowym zostaną zastąpione.
Protokół żądania przedstawiono poniżej.
PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
/values/Sheet1!A1:E1?valueInputOption=RAW
{ "range": "Sheet1!A1:E1", "majorDimension": "ROWS", "values": [ ["Data", 123.45, true, "=MAX(D2:D4)", "10"] ], }
Odpowiedź zawiera obiekt UpdateValuesResponse
, na przykład:
{
"spreadsheetId": SPREADSHEET_ID
,
"updatedRange": "Sheet1!A1:E1",
"updatedRows": 1,
"updatedColumns": 5,
"updatedCells": 5,
}
Wynikowy arkusz będzie wyglądał tak:
A | B | C | D | E | |
1 | Dane | 123,45 | PRAWDA | =MAKS.WYNIK(D2:D4) | 10 |
2 |
Zwróć uwagę, że „PRAWDA” jest wyśrodkowana i jest wartością logiczną, a „123.45” jest wyrównane do prawej, ponieważ jest liczbą, a „10” jest wyrównane do lewej, ponieważ jest ciągiem znaków. Formuła nie jest analizowana i również pojawia się jako ciąg znaków.
Dołączanie wartości
Zacznij od arkusza podobnego do tej w tabeli poniżej:
A | B | C | D | |
1 | Element | Koszt | W magazynie | Data wysyłki |
2 | Diabelski młyn | 20,50 PLN | 4 | 01.03.2016 r. |
3 |
Poniższy przykładowy kod spreadsheets.values.append
pokazuje, jak dodać 2 nowe wiersze wartości, zaczynając od wiersza 3. Parametr zapytania ValueInputOption
jest wymagany i określa, czy zapisane wartości mają być analizowane (np. czy ciąg znaków ma być konwertowany na datę).
Treść żądania to obiekt ValueRange
, który opisuje wartości zakresu do zapisania. Pole majorDimension
wskazuje, że tablice to listy wartości uporządkowane według wierszy.
Protokół żądania przedstawiono poniżej.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
/values/Sheet1!A1:E1:append?valueInputOption=VALUE_INPUT_OPTION
{ "range": "Sheet1!A1:E1", "majorDimension": "ROWS", "values": [ ["Door", "$15", "2", "3/15/2016"], ["Engine", "$100", "1", "3/20/2016"], ], }
Odpowiedź składa się z obiektu AppendValuesResponse
, na przykład tego:
{ "spreadsheetId":SPREADSHEET_ID
, "tableRange": "Sheet1!A1:D2", "updates": { "spreadsheetId":SPREADSHEET_ID
, "updatedRange": "Sheet1!A3:D4", "updatedRows": 2, "updatedColumns": 4, "updatedCells": 8, } }
Wygenerowany arkusz będzie wyglądał tak:
A | B | C | D | |
1 | Element | Koszt | W magazynie | Data wysyłki |
2 | Diabelski młyn | 20,50 PLN | 4 | 01.03.2016 r. |
3 | Drzwi | 15 | 2 | 15.03.2016 r. |
4 | Silnik | 100 zł | 1 | 20.03.2016 |
5 |