Interfejs API Arkuszy Google umożliwia odczytywanie wartości z komórek, zakresów, zestawów zakresów i całych arkuszy. Przykłady na tej stronie pokazują niektóre typowe operacje odczytu z wykorzystaniem zasobu spreadsheets.values. Wartości komórek możesz też odczytywać za pomocą metody spreadsheets.get, ale zwykle łatwiej jest użyć spreadsheets.values.get lub spreadsheets.values.batchGet.
Mają one postać żądań HTTP, które mają być neutralne pod względem języka. Aby dowiedzieć się, jak wdrożyć odczyty w różnych językach przy użyciu bibliotek klienta interfejsu API Google, przeczytaj artykuł Odczytywanie i zapisywanie wartości komórek.
W tych przykładach symbol zastępczy SPREADSHEET_ID wskazuje, gdzie należy podać identyfikator arkusza kalkulacyjnego, który można znaleźć po adresie URL arkusza kalkulacyjnego. Zakresy, z których mają być odczytywane dane, są określane za pomocą notacji A1 w adresie URL żądania. Przykładowy zakres to Arkusz1!A1:D5.
Dane źródłowe
Załóżmy, że w pierwszym arkuszu „Arkusz1” odczytywany arkusz kalkulacyjny zawiera podane niżej dane źródłowe. Ciągi w pierwszym wierszu to etykiety poszczególnych kolumn. Przykłady odczytów z innych arkuszy w arkuszu kalkulacyjnym znajdziesz w sekcji notacja A1.
| O | B | C | D | |
| 1 | Element | Koszt | Zapasy | Data wysyłki |
| 2 | Diabelski młyn | 20,50 USD | 4 | 1.03.2016 r. |
| 3 | Drzwi | 15 HKD | 2 | 15.03.2016 r. |
| 4 | Silnik | 100 HKD | 1 | 20.03.2016 r. |
| 5 | Sumy | 135,50 NZD | 7 | 20.03.2016 r. |
Odczytaj pojedynczy zakres
Poniższy przykładowy kod spreadsheets.values.get pokazuje, jak odczytywać wartości z zakresu Sheet1!A1:D5 i zwracać je w odpowiedzi. Puste końcowe wiersze i kolumny są pomijane.
Tutaj wyświetlany jest protokół żądania.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5
Odpowiedź składa się z obiektu ValueRange opisującego wartości zakresu. Pole majorDimension wskazuje, że tablice są listami wartości uporządkowanych 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"]
],
}
Przeczytaj pojedynczy zakres pogrupowany według kolumny
Poniższy przykładowy kod spreadsheets.values.get pokazuje, jak odczytywać wartości z zakresu Sheet1!A1:D3 i zwracać je w odpowiedzi, ale pogrupowane według kolumny. Puste końcowe wiersze i kolumny są pomijane.
Tutaj wyświetlany jest protokół żądania.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D3?majorDimension=COLUMNS
Odpowiedź składa się z obiektu ValueRange opisującego wartości zakresu. Pole majorDimension wskazuje, że tablice są listami wartości uporządkowanych 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"]
],
}
Odczyt pojedynczego zakresu z opcjami renderowania
Poniższy przykładowy kod spreadsheets.values.get pokazuje, jak odczytywać wartości z zakresu Arkusz1!A1:D5 i zwracać je w odpowiedzi, ale używają opcji renderowania do zarządzania sposobem zwracania tych informacji. Ustawienie ValueRenderOption parametru FORMULA wskazuje, że zamiast obliczonej wartości powinny być zwracane formuły, a ustawienie DateTimeRenderOption z SERIAL_NUMBER wskazuje, że daty mają być zwracane w postaci liczb.
Dostępne są też inne ustawienia. Puste końcowe wiersze i kolumny są pomijane.
Tutaj wyświetlany 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 obiektu ValueRange opisującego wartości zakresu. Pole majorDimension wskazuje, że tablice są listami wartości uporządkowanych 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)"]
],
}
Odczytaj wiele zakresów
Poniższy przykładowy kod spreadsheets.values.batchGet pokazuje, jak odczytywać wartości z zakresów Sheet1!B:B oraz Sheet1!D:D i zwracać je w odpowiedzi. Ustawienie ValueRenderOption parametru UNFORMATTED_VALUE wskazuje, że wartości są obliczane, ale nie sformatowane w odpowiedzi. Puste końcowe wiersze i kolumny są pomijane.
Tutaj wyświetlany 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 o identyfikatorze arkusza kalkulacyjnego i tablicy obiektów ValueRange odpowiadających każdemu żądanemu zakresowi, ułożonego w kolejności, w jakiej zostały zażądane. Pole majorDimension wskazuje, że tablice są listami wartości uporządkowanych 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
}
]
}
Odczytuj dane z 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 i zwraca je w odpowiedzi. Ustawienie ValueRenderOption parametru UNFORMATTED_VALUE wskazuje, że wartości są obliczane, ale nie sformatowane w odpowiedzi. Puste końcowe wiersze i kolumny są pomijane.
Tutaj wyświetlany 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 o identyfikatorze arkusza kalkulacyjnego i tablicy obiektów ValueRange odpowiadających każdemu żądanemu zakresowi, ułożonego w kolejności, w jakiej zostały zażądane. Pole majorDimension wskazuje, że tablice są listami wartości uporządkowanych 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": [
[...],
[...]
]
}
]
}