Interfejs API Arkuszy Google umożliwia tworzenie i aktualizowanie wykresów w arkuszach kalkulacyjnych. Przykłady na tej stronie pokazują, jak za pomocą interfejsu Arkuszy API można wykonywać niektóre typowe operacje na wykresach.
Przykłady te mają postać żądań HTTP, które nie wpływają na język. Aby dowiedzieć się, jak wdrożyć aktualizację zbiorczą w różnych językach za pomocą bibliotek klienta interfejsu API Google, przeczytaj artykuł o aktualizowaniu arkuszy kalkulacyjnych.
W tych przykładach obiekty zastępcze SPREADSHEET_ID i SHEET_ID wskazują, gdzie należy podać te identyfikatory. Ten identyfikator arkusza kalkulacyjnego znajdziesz w adresie URL arkusza kalkulacyjnego. Identyfikator arkusza możesz uzyskać za pomocą metody spreadsheets.get. Zakresy określa się w notacji A1. Przykładowy zakres to Arkusz1!A1:D5.
Dodatkowo obiekt zastępczy CHART_ID wskazuje identyfikator danego wykresu. Możesz ustawić ten identyfikator podczas tworzenia wykresu za pomocą interfejsu Arkuszy API lub zezwolić na jego wygenerowanie. Identyfikatory istniejących wykresów możesz uzyskać za pomocą metody spreadsheets.get.
Obiekt zastępczy SOURCE_SHEET_ID wskazuje arkusz z danymi źródłowymi. W przykładach jest to tabela w sekcji Dane źródłowe wykresu.
Dane źródłowe wykresu
W tych przykładach załóżmy, że używany 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 | E | |
| 1 | Numer modelu | Dział sprzedaży – styczeń | Sprzedaż – luty | Dział sprzedaży – marzec | Łączna sprzedaż |
| 2 | D-01X | 68 | 74 | 60 | 202 |
| 3 | FR-0B1 | 97 | 76 | 88 | 261 |
| 4 | P-034 | 27 | 49 | 32 | 108 |
| 5 | P-105 | 46 | 44 | 67 | 157 |
| 6 | W-11 | 75 | 68 | 87 | 230 |
| 7 | W-24 | 74 | 52 | 62 | 188 |
Dodaj wykres kolumnowy
Z przykładowego kodu spreadsheets.batchUpdate dowiesz się, jak za pomocą kodu AddChartRequest utworzyć wykres kolumnowy na podstawie danych źródłowych i umieścić go w nowym arkuszu. Aby skonfigurować wykres, żądanie wykonuje te działania:
- Ustawia typ wykresu jako wykres kolumnowy.
- Dodaje legendę na dole wykresu.
- Określa tytuły wykresu i osi.
- Konfiguruje 3 serie danych reprezentujące sprzedaż w 3 różnych miesiącach z użyciem domyślnego formatowania i kolorów.
Protokół żądania jest widoczny poniżej.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"addChart": {
"chart": {
"spec": {
"title": "Model Q1 Sales",
"basicChart": {
"chartType": "COLUMN",
"legendPosition": "BOTTOM_LEGEND",
"axis": [
{
"position": "BOTTOM_AXIS",
"title": "Model Numbers"
},
{
"position": "LEFT_AXIS",
"title": "Sales"
}
],
"domains": [
{
"domain": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 7,
"startColumnIndex": 0,
"endColumnIndex": 1
}
]
}
}
}
],
"series": [
{
"series": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 7,
"startColumnIndex": 1,
"endColumnIndex": 2
}
]
}
},
"targetAxis": "LEFT_AXIS"
},
{
"series": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 7,
"startColumnIndex": 2,
"endColumnIndex": 3
}
]
}
},
"targetAxis": "LEFT_AXIS"
},
{
"series": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 7,
"startColumnIndex": 3,
"endColumnIndex": 4
}
]
}
},
"targetAxis": "LEFT_AXIS"
}
],
"headerCount": 1
}
},
"position": {
"newSheet": true
}
}
}
}
]
}
Żądanie tworzy w nowym arkuszu wykres podobny do tego:
Dodawanie wykresu kołowego
Poniższy przykładowy kod spreadsheets.batchUpdate pokazuje, jak użyć kodu AddChartRequest do utworzenia wykresu kołowego 3D na podstawie danych źródłowych. Żądanie wykonuje te działania, aby skonfigurować wykres:
- Określa tytuł wykresu.
- Dodaje legendę po prawej stronie wykresu.
- Ustawia wykres jako wykres kołowy 3D. Pamiętaj, że wykresy kołowe 3D nie mogą mieć otworu w pierścieniu na środku, tak jak w przypadku płaskich wykresów kołowych.
- Ustawia serię danych na wykresie jako łączną sprzedaż dla każdego numeru modelu.
- Zakotwicza wykres w komórce C3 arkusza określonego przez SHEET_ID z przesunięciem o 50 pikseli w kierunkach X i Y.
Protokół żądania jest widoczny poniżej.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"addChart": {
"chart": {
"spec": {
"title": "Model Q1 Total Sales",
"pieChart": {
"legendPosition": "RIGHT_LEGEND",
"threeDimensional": true,
"domain": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 7,
"startColumnIndex": 0,
"endColumnIndex": 1
}
]
}
},
"series": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 7,
"startColumnIndex": 4,
"endColumnIndex": 5
}
]
}
},
}
},
"position": {
"overlayPosition": {
"anchorCell": {
"sheetId": SHEET_ID,
"rowIndex": 2,
"columnIndex": 2
},
"offsetXPixels": 50,
"offsetYPixels": 50
}
}
}
}
}
]
}
Żądanie tworzy wykres podobny do tego:
Możesz też w żądaniu zmienić wartość legendPositionjącą z RIGHT_LEGEND na LABELED_LEGEND, by połączyć wartości legendy z wycinkami wykresu kołowego.
'legendPosition': 'LABELED_LEGEND',
Zaktualizowane żądanie utworzy wykres podobny do tego:
Dodaj wykres liniowy, używając wielu zakresów, które nie sąsiadują ze sobą
Z przykładowego kodu spreadsheets.batchUpdate dowiesz się, jak za pomocą kodu AddChartRequest utworzyć wykres liniowy na podstawie danych źródłowych i umieścić go w arkuszu źródłowym.
Zaznaczenie zakresów, które nie przylegają do siebie, może posłużyć do wykluczenia wierszy z ChartSourceRange.
Żądanie wykonuje te działania, aby skonfigurować wykres:
- Ustawia typ wykresu jako wykres liniowy.
- Określa tytuł poziomej osi X.
- Konfiguruje serię danych reprezentującą sprzedaż. Ustawia komórki A1:A3 i A6:A7 jako
domain, a B1:B3 i B6:B7 jakoseriesz użyciem domyślnego formatowania i kolorów. Zakresy określa się za pomocą notacji A1 w adresie URL żądania. - Zakotwicza wykres w komórce H8 arkusza określonego przez funkcję SHEET_ID.
Protokół żądania jest widoczny poniżej.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"addChart": {
"chart": {
"spec": {
"basicChart": {
"chartType": "LINE",
"domains": [
{
"domain": {
"sourceRange": {
"sources": [
{
"startRowIndex": 0,
"endRowIndex": 3,
"startColumnIndex": 0,
"endColumnIndex": 1,
"sheetId": SOURCE_SHEET_ID
},
{
"startRowIndex": 5,
"endRowIndex": 7,
"startColumnIndex": 0,
"endColumnIndex": 1,
"sheetId": SOURCE_SHEET_ID
}
]
}
}
}
],
"series": [
{
"series": {
"sourceRange": {
"sources": [
{
"startRowIndex": 0,
"endRowIndex": 3,
"startColumnIndex": 1,
"endColumnIndex": 2,
"sheetId": SOURCE_SHEET_ID
},
{
"startRowIndex": 5,
"endRowIndex": 7,
"startColumnIndex": 1,
"endColumnIndex": 2,
"sheetId": SOURCE_SHEET_ID
}
]
}
}
}
]
}
},
"position": {
"overlayPosition": {
"anchorCell": {
"sheetId": SOURCE_SHEET_ID,
"rowIndex": 8,
"columnIndex": 8
}
}
}
}
}
}
]
}
Żądanie tworzy w nowym arkuszu wykres podobny do tego:
Usuwanie wykresu
Poniższy przykładowy kod spreadsheets.batchUpdate pokazuje, jak za pomocą DeleteEmbeddedObjectRequest usunąć wykres określony przez CHART_ID.
Protokół żądania jest widoczny poniżej.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"deleteEmbeddedObject": {
"objectId": CHART_ID
}
}
]
}
Edytowanie właściwości wykresu
Z przykładowego kodu spreadsheets.batchUpdate dowiesz się, jak za pomocą kodu UpdateChartSpecRequest edytować wykres utworzony w przepisie Dodaj wykres kolumnowy oraz zmienić jego dane, typ i wygląd. Podzbiorów właściwości wykresu nie można zmieniać pojedynczo. Aby wprowadzić zmiany, musisz nadać całe pole spec parametr UpdateChartSpecRequest. Ogólnie rzecz biorąc, edytowanie specyfikacji wykresu wymaga
zastąpienia jej nowym.
To żądanie aktualizuje pierwotny wykres (określony przez CHART_ID):
- Ustawia typ wykresu na
BAR. - Przenosi legendę na prawo od wykresu.
- Odwraca osie tak, że „Sprzedaż” znajduje się na dolnej osi, a „Numery modeli” na lewej.
- Określa format tytułu osi: 24-punktowa, pogrubienie i kursywa.
- Usuwa z wykresu dane „W-24” (wiersz 7 w danych źródłowych wykresu).
Protokół żądania jest widoczny poniżej.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"updateChartSpec": {
"chartId": CHART_ID,
"spec": {
"title": "Model Q1 Sales",
"basicChart": {
"chartType": "BAR",
"legendPosition": "RIGHT_LEGEND",
"axis": [
{
"format": {
"bold": true,
"italic": true,
"fontSize": 24
},
"position": "BOTTOM_AXIS",
"title": "Sales"
},
{
"format": {
"bold": true,
"italic": true,
"fontSize": 24
},
"position": "LEFT_AXIS",
"title": "Model Numbers"
}
],
"domains": [
{
"domain": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 6,
"startColumnIndex": 0,
"endColumnIndex": 1
}
]
}
}
}
],
"series": [
{
"series": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 6,
"startColumnIndex": 1,
"endColumnIndex": 2
}
]
}
},
"targetAxis": "BOTTOM_AXIS"
},
{
"series": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 6,
"startColumnIndex": 2,
"endColumnIndex": 3
}
]
}
},
"targetAxis": "BOTTOM_AXIS"
},
{
"series": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 6,
"startColumnIndex": 3,
"endColumnIndex": 4
}
]
}
},
"targetAxis": "BOTTOM_AXIS"
}
],
"headerCount": 1
}
}
}
}
]
}
Po przesłaniu prośby wykres będzie wyglądał tak:
Przenoszenie wykresu lub zmiana jego rozmiaru
Z przykładowego kodu spreadsheets.batchUpdate dowiesz się, jak za pomocą UpdateEmbeddedObjectPositionRequest przenosić wykres i zmieniać jego rozmiar. Po przesłaniu żądania wykres określony przez CHART_ID wygląda tak:
- Zakotwiczony do komórki A5 oryginalnego arkusza.
- Przesunięcie w kierunku X o 100 pikseli.
- Zmieniono rozmiar do 1200 x 742 piksele (domyślny rozmiar wykresu to 600 x 371 pikseli).
W żądaniu zmienia się tylko właściwości określone za pomocą parametru fields.
Inne właściwości (np. offsetYPixels) zachowują oryginalne wartości.
Protokół żądania jest widoczny poniżej.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"updateEmbeddedObjectPosition": {
"objectId": CHART_ID,
"newPosition": {
"overlayPosition": {
"anchorCell": {
"rowIndex": 4,
"columnIndex": 0
},
"offsetXPixels": 100,
"widthPixels": 1200,
"heightPixels": 742
}
},
"fields": "anchorCell(rowIndex,columnIndex),offsetXPixels,widthPixels,heightPixels"
}
}
]
}
Odczytywanie danych z wykresu
Poniższy przykładowy kod spreadsheets.get pokazuje, jak pobrać dane wykresu z arkusza kalkulacyjnego. Parametr zapytania fields określa, że powinny być zwracane tylko dane z wykresu.
Odpowiedź na to wywołanie metody to obiekt spreadsheet, który zawiera tablicę obiektów sheet. Wszystkie wykresy dostępne w arkuszu są reprezentowane w obiekcie sheet. Jeśli pole odpowiedzi ma wartość domyślną, jest ono pomijane w odpowiedzi.
W tym przykładzie pierwszy arkusz (SOURCE_SHEET_ID) nie zawiera żadnych wykresów, więc zwracana jest pusta para nawiasów klamrowych. Drugi arkusz zawiera wykres utworzony przez opcję Dodaj wykres kolumnowy i nic więcej.
Protokół żądania jest widoczny poniżej.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?fields=sheets(charts)
{
"sheets": [
{},
{
"charts": [
{
"chartId": CHART_ID,
"position": {
"sheetId": SHEET_ID
},
"spec": {
"basicChart": {
"axis": [
{
"format": {
"bold": false,
"italic": false
},
"position": "BOTTOM_AXIS",
"title": "Model Numbers"
},
{
"format": {
"bold": false,
"italic": false
},
"position": "LEFT_AXIS",
"title": "Sales"
}
],
"chartType": "COLUMN",
"domains": [
{
"domain": {
"sourceRange": {
"sources": [
{
"endColumnIndex": 1
"endRowIndex": 7,
"sheetId": SOURCE_SHEET_ID,
"startColumnIndex": 0,
"startRowIndex": 0,
}
]
}
}
}
],
"legendPosition": "BOTTOM_LEGEND",
"series": [
{
"series": {
"sourceRange": {
"sources": [
{
"endColumnIndex": 2,
"endRowIndex": 7,
"sheetId": SOURCE_SHEET_ID,
"startColumnIndex": 1,
"startRowIndex": 0,
}
]
}
},
"targetAxis": "LEFT_AXIS"
},
{
"series": {
"sourceRange": {
"sources": [
{
"endColumnIndex": 3,
"endRowIndex": 7,
"sheetId": SOURCE_SHEET_ID,
"startColumnIndex": 2,
"startRowIndex": 0,
}
]
}
},
"targetAxis": "LEFT_AXIS"
},
{
"series": {
"sourceRange": {
"sources": [
{
"endColumnIndex": 4,
"endRowIndex": 7,
"sheetId": SOURCE_SHEET_ID,
"startColumnIndex": 3,
"startRowIndex": 0,
}
]
}
},
"targetAxis": "LEFT_AXIS"
}
]
},
"hiddenDimensionStrategy": "SKIP_HIDDEN_ROWS_AND_COLUMNS",
"title": "Model Q1 Sales",
},
}
]
}
]
}