Pisanie podstawowe

Interfejs API Arkuszy Google umożliwia zapisywanie wartości i formuł w komórkach, zakresach, zbiorach 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,
}

Wygenerowany arkusz będzie wyglądał tak:

Zapisz selektywnie 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ż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, który opisuje wartości zakresu do zapisania. Pole majorDimension wskazuje, że tablice to listy wartości uporządkowane według kolumny.

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:

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:

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,
}

Wygenerowany arkusz będzie wyglądał tak:

Zwróć uwagę, że „PRAWDA” jest wyśrodkowana i jest to wartość logiczna, a „123.45” jest wyrównana do prawej, ponieważ jest liczbą, a „10” jest wyrównana 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 tabeli poniżej:

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ź zawiera obiekt AppendValuesResponse, na przykład:

{
  "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: