Czytanie podstawowe

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

Przykłady te są przedstawione w postaci żądań HTTP, aby były niezależne od języka. Aby dowiedzieć się, jak implementować odczyty 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 miejsce, w którym należy podać identyfikator arkusza kalkulacyjnego, który można znaleźć w adresie URL arkusza. Zakresy do odczytu są określane 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 zawiera w pierwszym arkuszu („Arkusz1”) te dane źródłowe: Ciągi znaków w pierwszym wierszu są etykietami poszczególnych kolumn. Aby zobaczyć przykłady odczytywania danych z innych arkuszy w arkuszu kalkulacyjnym, zapoznaj się z notacją A1.

	A	B	C	D
1	Element	Koszt	W magazynie	Data wysyłki
2	Diabelski młyn	20,50 USD	4	1.03.2016
3	Drzwi	15 USD	2	15.03.2016
4	Silnik	100 USD	1	20.03.2016
5	Sumy	135,5 USD	7	20.03.2016

Odczytywanie pojedynczego zakresu

Poniższy spreadsheets.values.get przykładowy kod pokazuje, jak odczytać wartości z zakresu Arkusz1!A1:D5 i zwrócić je w odpowiedzi. Puste wiersze i kolumny na końcu są pomijane.

Tutaj pokazany jest protokół żądania.

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

Odpowiedź składa się z ValueRange obiektu, który opisuje wartości zakresu. Pole majorDimensionwskazuje, że tablice są listami wartości uporządkowanymi 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

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

Tutaj pokazany jest protokół żądania.

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

Odpowiedź składa się z ValueRange obiektu, który opisuje wartości zakresu. Pole majorDimension wskazuje, że tablice są listami wartości uporządkowanymi 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"]
  ],
}

Odczytywanie pojedynczego zakresu z opcjami renderowania

Poniższy spreadsheets.values.get przykładowy kod 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 ValueRenderOption FORMULA oznacza, że zamiast obliczonej wartości mają być zwracane formuły, a DateTimeRenderOption ustawienie SERIAL_NUMBER oznacza, że daty mają być zwracane jako liczby. Możliwe są też inne ustawienia. Puste wiersze i kolumny na końcu są pomijane.

Tutaj pokazany jest protokół żądania.

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

Odpowiedź składa się z ValueRange obiektu, który opisuje wartości zakresu. Pole majorDimensionwskazuje, że tablice są listami wartości uporządkowanymi 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)"]
  ],
}

Odczytywanie wielu zakresów

Poniższy spreadsheets.values.batchGet przykładowy kod pokazuje, jak odczytać wartości z zakresów Arkusz1!B:B i Arkusz1!D:D i zwrócić je w odpowiedzi. Ustawienie ValueRenderOption UNFORMATTED_VALUE oznacza, że wartości są obliczane, ale nie są formatowane w odpowiedzi. Puste wiersze i kolumny na końcu są pomijane.

Tutaj pokazany jest 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 i tablicy ValueRange obiektów odpowiadających każdemu żądanemu zakresowi, wymienionych w kolejności, w jakiej zostały zażądane. Pole majorDimension wskazuje, że tablice są listami wartości uporządkowanymi 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
    }
  ]
}

Odczytywanie wielu zakresów w kilku arkuszach

Poniższy spreadsheets.values.batchGet przykładowy kod pokazuje, jak odczytać wartości z zakresów w arkuszach Arkusz1!A1:D5, Produkty!D1:D100 i Sprzedaż!E4:F6 i zwrócić je w odpowiedzi. Ustawienie ValueRenderOption UNFORMATTED_VALUE oznacza, że wartości są obliczane, ale nie są formatowane w odpowiedzi. Puste wiersze i kolumny na końcu są pomijane.

Tutaj pokazany jest 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 i tablicy ValueRange obiektów odpowiadających każdemu żądanemu zakresowi, wymienionych w kolejności, w jakiej zostały zażądane. Pole majorDimension wskazuje, że tablice są listami wartości uporządkowanymi 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": [
        [...],
        [...]
      ]
    }
  ]
}