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, jednocześnie zastępując zarówno formułę komórki, jak i formatowanie komórek, możesz użyć metody UpdateCellsRequest z spreadsheet.batchUpdate.

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

Mają one postać żądań HTTP, które mają być neutralne pod względem języka. 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 symbol zastępczy SPREADSHEET_ID wskazuje, gdzie należy podać identyfikator arkusza kalkulacyjnego, który można znaleźć po 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.

Napisz jeden zakres

Ten przykładowy kod spreadsheets.values.update pokazuje, jak zapisać 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 zostanie przekonwertowany 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 wierszy. Dotychczasowe 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, na przykład:

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

Arkusz wynikowy będzie wyglądał tak:

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

Zapisuj 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. Komórkę można też wyczyścić, wpisując w niej pusty ciąg ("").

Począwszy od arkusza, który zawiera te same dane co w przykładzie powyżej, przykładowy kod spreadsheets.values.update poniżej pokazuje, jak zapisać wartości w zakresie B1:D4, selektywnie pozostawiając niektóre komórki bez zmian i czyszcząc inne. Parametr zapytania ValueInputOption jest wymagany i określa, czy zapisywane wartości są analizowane (np. czy ciąg znaków zostanie przekonwertowany 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 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 tabela B1 pozostaje niezmieniona (ze względu na element tablicy null), a B4 musi zostać wyczyszczona (pusty ciąg znaków). Wartości B2 i B3 zostały zaktualizowane. Trzecia tablica wykonuje te same operacje w kolumnie D, a druga pusta tablica wskazuje, że kolumna C ma zostać niezmieniona.

Odpowiedź składa się z obiektu UpdateValuesResponse, takiego jak:

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

Arkusz wynikowy będzie wyglądał tak:

	O	B	C	D
1	Element	Koszt	Zapasy	Data wysyłki
2	Diabelski młyn	4 PLN	4	01.04.2016 r.
3	Drzwi	2 PLN	2	15.04.2016 r.
4	Silnik		1
5	Sumy	12 PLN	7	15.04.2016 r.

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

Zapisz w wielu zakresach

Ten przykładowy kod spreadsheets.values.batchUpdate, zaczynając od pustego arkusza, pokazuje, jak zapisywać wartości w zakresach Sheet1!A1:A4 i Sheet1!B1:D2. Dotychczasowe 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 czy 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órki oraz tablicy obiektów UpdateValuesResponse, po 1 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,
    }
  ],
}

Arkusz wynikowy będzie wyglądał tak:

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

Zapisywanie wartości bez analizy

Ten przykładowy kod spreadsheets.values.update zaczyna od pustego arkusza i pokazuje, jak zapisywać 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ę 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, takiego jak:

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

Arkusz wynikowy będzie wyglądał tak:

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

Zauważ, że „PRAWDA” jest wyśrodkowany i jest wartością logiczną, podczas gdy „123.45” jest liczbą po prawej stronie, ponieważ jest liczbą, a „10” – jest 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	Zapasy	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 zostanie przekonwertowany 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 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, takiego jak:

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

Arkusz wynikowy będzie wyglądał tak:

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