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": [ [...], [...] ] } ] }