Czytanie podstawowe

Interfejs Google Sheets API umożliwia odczytywanie wartości z komórek, zakresów, zbiorów zakresów i całych arkuszy. Przykłady na tej stronie pokazują typowe operacje odczytu zasobu spreadsheets.values. Wartości komórek możesz też odczytać za pomocą metody spreadsheets.get, ale zazwyczaj łatwiej jest użyć metody spreadsheets.values.get lub spreadsheets.values.batchGet.

Przykłady te są przedstawione w formie żądań HTTP, aby były neutralne językowo. Aby dowiedzieć się, jak stosować odczyty 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 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 do odczytu są określone za pomocą notacji A1 w adresie URL żądania. Przykładowy zakres to Arkusz1!A1:D5.

Dane źródłowe

W tych przykładach zakładamy, że odczytywany arkusz kalkulacyjny zawiera te dane źródłowe w pierwszym arkuszu („Sheet1”). Ciągi w pierwszym wierszu to etykiety poszczególnych kolumn. Przykłady odczytu z innych arkuszy w arkuszu kalkulacyjnym znajdziesz w artykule Notacja A1.

	A	B	C	D
1	Element	Koszt	Zasoby	Data wysyłki
2	Diabelski młyn	20,50 zł	4	01.03.2016
3	Drzwi	15	2	15.03.2016 r.
4	Silnik	100 zł	1	20.03.2016
5	Sumy	135,5 PLN	7	20.03.2016

Czytanie pojedynczego zakresu

Ten przykładowy kod spreadsheets.values.get pokazuje, jak odczytać wartości z zakresu Arkusz1!A1:D5 i zwrócić je w odpowiedzi. Pustych końcowych wierszy i kolumn nie uwzględnia się.

Tutaj możesz zobaczyć protokół żądania.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5

Odpowiedź zawiera obiekt ValueRange, który opisuje wartości zakresu. Pole majorDimension wskazuje, że tablice to listy wartości uporządkowane według wierszy.

{
  "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", "30/20/2016"],
    ["Totals", "$135.5", "7", "3/20/2016"]
  ],
}

Odczytywanie pojedynczego zakresu pogrupowanego według kolumny

Ten przykładowy kod spreadsheets.values.get pokazuje, jak odczytać wartości z zakresu Arkusz1!A1:D3 i zwrócić je w odpowiedzi, ale pogrupowane według kolumny. Puste końcowe wiersze i kolumny są pomijane.

Tutaj możesz zobaczyć protokół żądania.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D3?majorDimension=COLUMNS

Odpowiedź zawiera obiekt ValueRange, który opisuje wartości zakresu. Pole majorDimension wskazuje, że tablice to listy wartości uporządkowane według kolumn.

{
  "range": "Sheet1!A1:D3",
  "majorDimension": "COLUMNS",
  "values": [
    ["Item", "Wheel", "Door"],
    ["Cost", "$20.50", "$15"],
    ["Stocked", "4", "2"],
    ["Ship Date", "3/1/2016", "3/15/2016"]
  ],
}

Czytanie pojedynczego zakresu z opcjami renderowania

Ten przykładowy kod spreadsheets.values.get pokazuje, jak odczytać wartości z zakresu Arkusz1!A1:D5 i zwrócić je w odpowiedzi, ale używa opcji renderowania, aby zarządzać sposobem zwracania tych informacji. Ustawienie FORMULA w ValueRenderOption oznacza, że zamiast obliczonej wartości mają być zwracane formuły, a ustawienie SERIAL_NUMBER w DateTimeRenderOption oznacza, że daty mają być zwracane jako liczby. Dostępne są też inne ustawienia. Puste końcowe wiersze i kolumny są pomijane.

Tutaj możesz zobaczyć protokół żądania.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5?
            valueRenderOption=FORMULA&dateTimeRenderOption=SERIAL_NUMBER

Odpowiedź zawiera obiekt ValueRange, który opisuje wartości zakresu. Pole majorDimension wskazuje, że tablice to listy wartości uporządkowane według wierszy.

{
  "range": "Sheet1!A1:D5",
  "majorDimension": "ROWS",
  "values": [
    ["Item", "Cost", "Stocked", "Ship Date"],
    ["Wheel", "$20.50", "4", "42430"],
    ["Door", "$15", "2", "42444"],
    ["Engine", "$100", "1", "42449"],
    ["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"]
  ],
}

Czytanie wielu zakresów

Ten przykładowy kod spreadsheets.values.batchGet pokazuje, jak odczytać wartości z zakresów Arkusz1!B:B i Arkusz1!D:D oraz zwrócić je w odpowiedzi. Ustawienie UNFORMATTED_VALUE ValueRenderOption wskazuje, że wartości są obliczane, ale nie są formatowane w odpowiedzi. Pustych końcowych wierszy i kolumn nie uwzględnia się.

Tutaj możesz zobaczyć protokół żądania.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet?
            ranges=Sheet1!B:B&ranges=Sheet1!D:D&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS

Odpowiedź na to wywołanie metody składa się z obiektu z identyfikatorem arkusza kalkulacyjnego oraz tablicy obiektów ValueRange odpowiadających każdemu żądanemu zakresowi, posortowanych według kolejności ich żądania. Pole majorDimension wskazuje, że tablice to listy wartości uporządkowane według kolumn. Na przykład:

{
  "spreadsheetId": SPREADSHEET_ID,
  "valueRanges": [
    {
      "range": "Sheet1!B1:B1000",
      "majorDimension": "COLUMNS",
      "values": [
        ["Cost",20.5,15,100,135.5]
      ]
    },
    {
      "range": "Sheet1!D1:D1000",
      "majorDimension": "COLUMNS",
      "values": [
        ["Ship Date",42430,42444,42449,42449]
      ]s
    }
  ]
}

Czytanie wielu zakresów w wielu arkuszach

Poniższy przykładowy kod spreadsheets.values.batchGet pokazuje, jak odczytywać wartości z zakresów w arkuszach Sheet1!A1:D5, Products!D1:D100 i Sales!E4:F6 oraz zwracać je w odpowiedzi. Ustawienie UNFORMATTED_VALUE ValueRenderOption wskazuje, że wartości są obliczane, ale nie są formatowane w odpowiedzi. Pustych końcowych wierszy i kolumn nie uwzględnia się.

Tutaj możesz zobaczyć protokół żądania.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet?
            ranges=Sheet1!A1:D5&ranges=Products!D1:D100&ranges=Sales!E4:F6&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS

Odpowiedź na to wywołanie metody składa się z obiektu z identyfikatorem arkusza kalkulacyjnego oraz tablicy obiektów ValueRange odpowiadających każdemu żądanemu zakresowi, posortowanych według kolejności ich żądania. Pole majorDimension wskazuje, że tablice to listy wartości uporządkowane według kolumn. Na przykład:

{
  "spreadsheetId": SPREADSHEET_ID,
  "valueRanges": [
    {
      "range": "Sheet1!A1:D5",
      "majorDimension": "COLUMNS",
      "values": [
        [...],
        [...]
      ]
    },
    {
      "range": "Products!D1:D100",
      "majorDimension": "COLUMNS",
      "values": [
        [...]
      ]
    },
    {
      "range": "Sales!E4:F6",
      "majorDimension": "COLUMNS",
      "values": [
        [...],
        [...]
      ]
    }
  ]
}