Ta strona została przetłumaczona przez Cloud Translation API.

Pisanie podstawowe

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 API Arkuszy.

Pamiętaj, że możesz też zapisywać wartości komórek za pomocą metody spreadsheet.batchUpdate, co może być przydatne, jeśli chcesz jednocześnie aktualizować formatowanie komórek 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 innego, zastępując zarówno formułę komórki, jak i formatowanie komórek, możesz użyć metody UpdateCellsRequest z właściwością spreadsheet.batchUpdate.

Jednak w przypadku prostych wartości łatwiej jest użyć metody spreadsheets.values.update lub spreadsheets.values.batchUpdate.

Te przykłady mają postać żądań HTTP, które nie mają związku z językiem. Aby dowiedzieć się, jak wdrożyć zapisy w różnych językach za pomocą bibliotek klienta interfejsu API Google, przeczytaj artykuł Odczytywanie i zapisywanie wartości komórek.

W tych przykładach zmienna SPREADSHEET_ID wskazuje miejsce, w którym należy podać identyfikator arkusza kalkulacyjnego, który można znaleźć w adresie URL arkusza. Zakresy, w których mają być zapisywane dane, określa się za pomocą notacji A1. Przykładowy zakres to Arkusz1!A1:D5.

Zapisz pojedynczy zakres

Poniższy przykładowy kod spreadsheets.values.update pokazuje, jak zapisywać wartości w zakresie, zaczynając od nowego, pustego arkusza kalkulacyjnego. Parametr zapytania ValueInputOption jest wymagany i określa, czy zapisywane wartości są analizowane (np. czy ciąg znaków został przekształcony w datę).

Treść żądania to obiekt ValueRange opisujący wartości zakresów do zapisania. Pole majorDimension wskazuje, że tablice są listami wartości uporządkowanych według wierszy. Istniejące wartości w zakresie docelowym zostaną zastąpione.

Protokół żądania jest pokazany 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, np. z tego:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:D5",
  "updatedRows": 5,
  "updatedColumns": 4,
  "updatedCells": 20,
}

Wynikowy arkusz wygląda tak:

	O	B	C	D
1	Element	Koszt	Zaopatrzone	Data wysyłki
2	Diabelski młyn	20,50 USD	4	1.03.2016 r.
3	Drzwi	$15	2	15.03.2016 r.
4	Wyszukiwarka	100 HKD	1	20.03.2016 r.
5	Sumy	$135.5	7	20.03.2016 r.

Pisz wybiórczo w zakresie

Podczas zapisywania wartości w zakresie można uniknąć zmiany niektórych istniejących komórek, ustawiając odpowiednie elementy tablicy na null. Możesz też wyczyścić komórkę, wpisując w niej pusty ciąg ("").

Począwszy od arkusza zawierającego te same dane, co w przykładzie powyżej, poniżej przykładowy kod spreadsheets.values.update pokazuje, jak zapisać wartości w zakresie B1:D4, selektywnie pozostawiając niektóre komórki bez zmian, a pozostałe czyszcząc. Parametr zapytania ValueInputOption jest wymagany i określa, czy zapisywane wartości są analizowane (np. czy ciąg znaków został przekształcony w datę).

Treść żądania to obiekt ValueRange opisujący wartości zakresów do zapisania. Pole majorDimension wskazuje, że tablice są listami wartości uporządkowanych według kolumny.

Protokół żądania jest pokazany 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", ""]
  ]
}

Pole values zawiera listę zmian wprowadzonych w poszczególnych kolumnach w zakresie. Pierwsza tablica wskazuje, że B1 ma pozostać bez zmian (ze względu na element tablicy null), a B4 – do wyczyszczenia (pusty ciąg znaków). Wartości B2 i B3 zostały zaktualizowane. Trzecia tablica wykonuje te same operacje na kolumnie D, a druga pusta tablica wskazuje, że kolumna C pozostanie bez zmian.

Odpowiedź składa się z obiektu UpdateValuesResponse, np. z tego:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!B1:D5",
  "updatedRows": 3,
  "updatedColumns": 2,
  "updatedCells": 6,
}

Wynikowy arkusz wygląda tak:

	O	B	C	D
1	Element	Koszt	Zaopatrzone	Data wysyłki
2	Diabelski młyn	$1.00	4	1.04.2016 r.
3	Drzwi	$2	2	4/15/2016
4	Wyszukiwarka		1
5	Sumy	$3.00	7	4/15/2016

Zwróć uwagę, że wiersz „Sumy” nie zmienia się bezpośrednio przez to żądanie, ponieważ zawiera formuły zależne od zmodyfikowanych komórek.

Zapisz w wielu zakresach

Zaczynając od pustego arkusza, poniżej przykładowy kod spreadsheets.values.batchUpdate pokazuje, jak zapisywać wartości w zakresach Sheet1!A1:A4 i Sheet1!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 z tablicy obiektów ValueRange odpowiadającej każdemu zapisanemu zakresowi. Pole majorDimension określa, czy uwzględnione tablice są interpretowane jako tablice kolumn lub wierszy.

Protokół żądania jest pokazany 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 zaktualizowane statystyki komórek i 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,
    }
  ],
}

Wynikowy arkusz wygląda tak:

	O	B	C	D
1	Element	Koszt	Zaopatrzone	Data wysyłki
2	Diabelski młyn	20,50 USD	4	1.03.2016 r.
3	Drzwi
4	Wyszukiwarka
5

Zapisz wartości bez analizy

Począwszy od pustego arkusza, poniższy przykładowy kod spreadsheets.values.update pokazuje, jak zapisać wartości w zakresie Arkusz1!A1:E1, ale korzysta z parametru zapytania RAW ValueInputOption, aby zapobiec analizowaniu zapisanych ciągów jako formuł, wartości logicznych lub liczb. Pojawiają się one jako ciągi znaków, a wyrównanie tekstu jest wyrównane w arkuszu.

Protokół żądania jest pokazany 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ź składa się z obiektu UpdateValuesResponse, np. z tego:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:E1",
  "updatedRows": 1,
  "updatedColumns": 5,
  "updatedCells": 5,
}

Wynikowy arkusz wygląda tak:

	O	B	C	D	E
1	Dane	123.45	TRUE	=MAX(D2:D4)	10
2

Zwróć uwagę, że „PRAWDA” jest wyśrodkowany i jest wartością logiczną, natomiast „123.45” jest uzasadnione, ponieważ jest liczbą, a „10” – to ciąg znaków. Formuła nie jest analizowana i wyświetla się też jako ciąg znaków.

Dołącz wartości

Zacznij od arkusza podobnego do tej tabeli:

	O	B	C	D
1	Element	Koszt	Zaopatrzone	Data wysyłki
2	Diabelski młyn	20,50 USD	4	1.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 zapisywane wartości są analizowane (np. czy ciąg znaków został przekształcony w datę).

Treść żądania to obiekt ValueRange opisujący wartości zakresów do zapisania. Pole majorDimension wskazuje, że tablice są listami wartości uporządkowanych według wierszy.

Protokół żądania jest pokazany 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, np. z tego:

{
  "spreadsheetId": SPREADSHEET_ID,
  "tableRange": "Sheet1!A1:D2",
  "updates": {
    "spreadsheetId": SPREADSHEET_ID,
    "updatedRange": "Sheet1!A3:D4",
    "updatedRows": 2,
    "updatedColumns": 4,
    "updatedCells": 8,
  }
}

Wynikowy arkusz wygląda tak:

	O	B	C	D
1	Element	Koszt	Zaopatrzone	Data wysyłki
2	Diabelski młyn	20,50 USD	4	1.03.2016 r.
3	Drzwi	$15	2	15.03.2016 r.
4	Wyszukiwarka	100 HKD	1	20.03.2016 r.
5