Interfejs Google Sheets API umożliwia odczytywanie wartości z komórek, zakresów, zbiorów zakresów oraz 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 zwykle ł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 | Zasób | 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 ValueRenderOption wartości FORMULA oznacza, że zamiast obliczonej wartości mają być zwracane formuły, a ustawienie DateTimeRenderOption wartości SERIAL_NUMBER oznacza, że daty mają być zwracane jako liczby.
Możliwe 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 ten 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": [
[...],
[...]
]
}
]
}