Pisanie podstawowe

Interfejs Google Sheets API 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 Sheets API można wykonać niektóre typowe operacje zapisu.

Warto pamiętać, że 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órek lub inne właściwości, na które nie ma wpływu zasób spreadsheets.values. Jeśli na przykład chcesz skopiować zakres komórek z jednego arkusza do drugiego, zastępując zarówno formułę komórki, jak i formatowanie komórki, możesz użyć metody UpdateCellsRequest z spreadsheet.batchUpdate.

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

Przykłady te są przedstawione w formie żądań HTTP, aby były niezależne od języka. Aby dowiedzieć się, jak implementować 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 SPREADSHEET_ID oznacza miejsce, w którym należy podać identyfikator arkusza kalkulacyjnego. Można go znaleźć w adresie URL arkusza. Zakresy, do których mają być zapisywane dane, są określane za pomocą notacji A1. Przykładowy zakres to Arkusz1!A1:D5.

Zapisywanie pojedynczego zakresu

Poniższy 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 jest konwertowany na datę).

Treść żądania to obiekt ValueRange, który opisuje wartości zakresu do zapisania. Pole majorDimension wskazuje, że tablice są listami wartości uporządkowanymi 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, takiego jak ten:

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

Wynikowy arkusz będzie wyglądać tak:

Selektywne zapisywanie 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 znaków ("").

Zaczynając od arkusza zawierającego te same dane, które zostały wygenerowane w przykładzie powyżej, poniższy 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 inne czyszcząc. Parametr zapytania ValueInputOption jest wymagany i określa, czy zapisywane wartości są analizowane (np. czy ciąg znaków jest konwertowany na datę).

Treść żądania to obiekt ValueRange, który opisuje wartości zakresu do zapisania. Pole majorDimension oznacza, że tablice są listami wartości uporządkowanymi 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", ""]
  ]
}

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

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

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

Wynikowy arkusz będzie wyglądać tak:

Pamiętaj, że wiersz „Sumy”, mimo że nie został bezpośrednio zmieniony przez tę prośbę, ulegnie zmianie, ponieważ jego komórki zawierają formuły, które zależą od zmienionych komórek.

Zapisywanie w wielu zakresach

Poniższy przykładowy kod spreadsheets.values.batchUpdate pokazuje, jak zapisać wartości w zakresach Arkusz1!A1:A4 i Arkusz1!B1:D2, zaczynając od pustego arkusza. 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ących każdemu zapisanemu zakresowi. Pole majorDimension określa, czy tablice mają być 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, który zawiera 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:

Zapisywanie wartości bez analizowania

Poniższy przykładowy kod, który zaczyna się od pustego arkusza, pokazuje, jak zapisać 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.spreadsheets.values.update Pojawiają się one w arkuszu jako ciągi znaków, a tekst jest wyrównany do lewej.

Treść żądania to obiekt ValueRange, który opisuje wartości zakresu do zapisania. Pole majorDimension wskazuje, że tablice są listami wartości uporządkowanymi 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: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 ten:

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

Wynikowy arkusz będzie wyglądać tak:

Zwróć uwagę, że „TRUE” jest wyśrodkowane i jest wartością logiczną, natomiast „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 jest wyświetlana jako ciąg znaków.

Dołączanie wartości

Zacznij od arkusza podobnego do tabeli poniżej:

Poniższy przykładowy kodspreadsheets.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 jest konwertowany na datę).

Treść żądania to obiekt ValueRange, który opisuje wartości zakresu do zapisania. Pole majorDimension wskazuje, że tablice są listami wartości uporządkowanymi 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, takiego jak ten:

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