Interfejs API Arkuszy Google umożliwia odczyt wartości z komórek, zakresów, zestawów zakresów i całych arkuszy. Przykłady na tej stronie ilustrują niektóre typowe operacje odczytu zasobu spreadsheets.values. Wartości komórek możesz też odczytywać za pomocą metody spreadsheets.get, ale jest to zwykle łatwiejsze niż spreadsheets.values.get lub spreadsheets.values.batchGet.
Przykłady te mają postać żądań HTTP, które nie wpływają na język. Aby dowiedzieć się, jak implementować odczyty w różnych językach za pomocą bibliotek klienta interfejsu API Google, przeczytaj artykuł Odczyt i zapis 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źć w adresie URL arkusza kalkulacyjnego. Zakresy, z których ma być odczytywane, określa się w notacji A1 w adresie URL żądania. Przykładowy zakres to Arkusz1!A1:D5.
Dane źródłowe
W tych przykładach załóżmy, że odczytywany arkusz kalkulacyjny ma w swoim pierwszym arkuszu („Arkusz1”) podane niżej dane źródłowe. Ciągi w pierwszym wierszu są etykietami poszczególnych kolumn. Przykłady odczytywania innych arkuszy w arkuszu kalkulacyjnym znajdziesz w sekcji Zapis A1.
| A | B | C | D | |
| 1 | Element | Koszt | W magazynie | Data wysyłki |
| 2 | Diabelski młyn | 20,50 PLN | 4 | 01.03.2016 r. |
| 3 | Drzwi | 15 | 2 | 15.03.2016 r. |
| 4 | Silnik | 100 | 1 | 20.03.2016 r. |
| 5 | Sumy | 135,50 PLN | 7 | 20.03.2016 r. |
Odczytaj pojedynczy zakres
Z przykładowego kodu spreadsheets.values.get dowiesz się, jak odczytywać wartości z zakresu Sheet1!A1:D5 i zwracać je w odpowiedzi. Puste końcowe wiersze i kolumny są pomijane.
Tutaj jest widoczny protokół żądania.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5
Odpowiedź składa się z obiektu ValueRange, który opisuje 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"]
],
}
Odczytaj pojedynczy zakres pogrupowany według kolumny
Z przykładowego kodu spreadsheets.values.get dowiesz się, 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 jest widoczny protokół żądania.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D3?majorDimension=COLUMNS
Odpowiedź składa się z obiektu ValueRange, który opisuje 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"]
],
}
Odczytywanie pojedynczego zakresu z opcjami renderowania
Poniższy przykładowy kod spreadsheets.values.get pokazuje, jak odczytywać wartości z zakresu Sheet1!A1:D5 i zwracać je w odpowiedzi, ale używa opcji renderowania, by zarządzać sposobem zwracania tych informacji. Ustawienie ValueRenderOption FORMULA wskazuje, że zamiast obliczonej wartości mają być zwracane formuły, a ustawienie DateTimeRenderOption 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 jest widoczny 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, który opisuje 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)"]
],
}
Odczytuj wiele zakresów
Poniższy przykładowy kod spreadsheets.values.batchGet pokazuje, jak odczytywać wartości z zakresów Sheet1!B:B i Sheet1!D:D oraz zwracać je w odpowiedzi. Ustawienie ValueRenderOption UNFORMATTED_VALUE wskazuje, że wartości są obliczane, ale nie sformatowane w odpowiedzi. Puste końcowe wiersze i kolumny są pomijane.
Tutaj jest widoczny 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 wywołanie metody składa się z obiektu z identyfikatorem arkusza kalkulacyjnego i tablicy obiektów ValueRange odpowiadających poszczególnym żądanym zakresom (w kolejności, w jakiej zostały one żą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
Ten 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 ValueRenderOption UNFORMATTED_VALUE wskazuje, że wartości są obliczane, ale nie sformatowane w odpowiedzi. Puste końcowe wiersze i kolumny są pomijane.
Tutaj jest widoczny 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 wywołanie metody składa się z obiektu z identyfikatorem arkusza kalkulacyjnego i tablicy obiektów ValueRange odpowiadających poszczególnym żądanym zakresom (w kolejności, w jakiej zostały one żą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": [
[...],
[...]
]
}
]
}