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 za pomocą zasobu spreadsheets.values interfejsu Arkuszy Google można wykonać niektóre typowe operacje zapisu.

Pamiętaj, że wartości komórek możesz też zapisywać za pomocą metody spreadsheet.batchUpdate, co może być przydatne, jeśli chcesz jednocześnie zaktualizować 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órki, 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.

Przykłady te mają postać żądań HTTP, które nie wpływają na język. Aby dowiedzieć się, jak implementować zapisy w różnych językach za pomocą bibliotek klienta interfejsu API Google, przeczytaj artykuł Odczyt i zapis wartości w komórkach.

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 kalkulacyjnego. Zakresy zapisu określa się w notacji A1. Przykładowy zakres to Arkusz1!A1:D5.

Wpisz jeden zakres

Z poniższego przykładowego kodu spreadsheets.values.update dowiesz się, jak zapisywać wartości w zakresie, zaczynając od nowego, pustego arkusza kalkulacyjnego. Parametr zapytania ValueInputOption jest wymagany. Określa, czy zapisane wartości są analizowane (np. czy ciąg znaków jest 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 wierszy. Istniejące wartości w zakresie docelowym zostaną zastąpione.

Protokół żądania jest widoczny 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. tego:

{
  "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	1	20.03.2016 r.
5	Sumy	135,50 PLN	7	20.03.2016 r.

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

Począwszy od arkusza zawierającego te same dane, które wygenerowano w przykładzie powyżej, ten przykładowy kod spreadsheets.values.update pokazuje, jak zapisać wartości do zakresu B1:D4, wybiórczo pozostawiać niektóre komórki bez zmian i wyczyścić inne. Parametr zapytania ValueInputOption jest wymagany. Określa, czy zapisane wartości są analizowane (np. czy ciąg znaków jest 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 jest widoczny 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 znajduje się lista zmian wprowadzonych w każdej kolumnie w zakresie. Pierwsza tablica wskazuje, że wartość B1 nie ulegnie zmianie (z powodu elementu tablicy null), a B4 – zostanie wyczyszczona (pusty ciąg znaków). Wartości dla B2 i B3 zostały zaktualizowane. Trzecia tablica wykonuje te same operacje na kolumnie D, a druga pusta tablica wskazuje, że kolumna C powinna pozostać bez zmian.

Odpowiedź składa się z obiektu UpdateValuesResponse, na przykład tego:

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

Wynikowy arkusz będzie wyglądał tak:

	A	B	C	D
1	Element	Koszt	W magazynie	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 został bezpośrednio zmieniony przez to żądanie, ale zmienia się, ponieważ jego komórki zawierają formuły zależne od zmienionych komórek.

Zapisz w wielu zakresach

Począwszy od pustego arkusza, ten przykładowy kod spreadsheets.values.batchUpdate 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 tablicy obiektów ValueRange odpowiadających każdemu zapisanym zakresom. Pole majorDimension określa, czy uwzględnione tablice są interpretowane jako tablice kolumn czy wierszy.

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

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
4	Silnik
5

Zapisuj wartości bez ich analizowania

Począwszy od pustego arkusza, ten przykładowy kod spreadsheets.values.update pokazuje, jak zapisywać wartości w zakresie Sheet1!A1:E1, ale korzysta z parametru zapytania RAW ValueInputOption, by zapobiec przeanalizowaniu zapisanych ciągów znaków jako formuł, wartości logicznych lub liczb. Pojawiają się jako ciągi tekstowe, a wyrównanie tekstu w arkuszu jest dokładnie określone.

Protokół żądania jest widoczny 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, na przykład tego:

{
  "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	TRUE	=MAX(D2:D4)	10
2

Zwróć uwagę, że „PRAWDA” jest wyśrodkowana i jest wartością logiczną, natomiast „123,45” – prawidłowa, bo jest liczbą, i „10” – wyjustowane, bo jest ciągiem. Formuła nie jest analizowana i wyświetla się jako ciąg znaków.

Dołącz 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

Z przykładowego kodu spreadsheets.values.append dowiesz się, jak dodać 2 nowe wiersze wartości zaczynających się od wiersza 3. Parametr zapytania ValueInputOption jest wymagany. Określa, czy zapisane wartości są analizowane (np. czy ciąg znaków jest 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 wierszy.

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

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	1	20.03.2016 r.
5