באמצעות Google Sheets API אפשר ליצור ולעדכן תרשימים בתוך גיליונות אלקטרוניים לפי הצורך. הדוגמאות בדף הזה ממחישות איך אפשר לבצע פעולות תרשימים נפוצות באמצעות Sheets API.
הדוגמאות האלה מוצגות בצורת בקשות HTTP כשהשפה היא ניטרלית. במאמר עדכון גיליונות אלקטרוניים מוסבר איך מטמיעים עדכון בכמות גדולה בשפות שונות באמצעות ספריות הלקוח של Google API.
בדוגמאות האלה, ה-placeholders SPREADSHEET_ID ו-SHEET_ID מציינים איפה תציינו את המזהים האלה. המזהה של הגיליון האלקטרוני מופיע בכתובת ה-URL של הגיליון האלקטרוני. כדי לאתר את מזהה הגיליון אפשר להשתמש בשיטה spreadsheets.get. הטווחים מוגדרים באמצעות סימון A1. טווח לדוגמה הוא Sheet1!A1:D5.
בנוסף, ה-placeholder CHART_ID מציין את המזהה של תרשים נתון. תוכלו להגדיר את המזהה הזה כשיוצרים תרשים באמצעות ה-API של Sheets, או לאפשר ל-Sheets API ליצור בשבילכם את המזהה. אפשר לקבל את המזהים של תרשימים קיימים באמצעות method spreadsheets.get.
לסיום, ה-placeholder SOURCE_SHEET_ID מציין את הגיליון עם נתוני המקור. בדוגמאות האלה, זו הטבלה שמופיעה בקטע Chart source data.
נתוני המקור של התרשים
בדוגמאות האלה, נניח שהגיליון האלקטרוני שבו אתם משתמשים כולל את נתוני המקור הבאים בגיליון הראשון ("גיליון1"). המחרוזות בשורה הראשונה הן תוויות של העמודות הנפרדות. כדי לראות דוגמאות לקריאה מגיליונות אחרים בגיליון האלקטרוני, ראו סימון A1.
| A | B | C | D | E | |
| 1 | מספר הדגם | מכירות - ינואר | מכירות - פברואר | מכירות - מרץ | סה"כ מכירות |
| 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 |
הוספת תרשים עמודות אנכי
דוגמת הקוד הבאה של spreadsheets.batchUpdate מראה איך להשתמש בתרשים AddChartRequest כדי ליצור תרשים עמודות אנכי מנתוני המקור, ולהציב אותו בגיליון חדש. הבקשה מבצעת את הפעולות הבאות כדי להגדיר את התרשים:
- מגדיר את סוג התרשים כתרשים עמודות אנכי.
- הוספת מקרא בתחתית התרשים.
- הגדרת הכותרות של התרשים והצירים.
- מגדירה 3 סדרות נתונים, שמייצגות מכירות במשך 3 חודשים שונים, תוך שימוש בפורמט ובצבעים שמוגדרים כברירת מחדל.
פרוטוקול הבקשה מוצג למטה.
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
}
}
}
}
]
}
הבקשה יוצרת תרשים בגיליון חדש, באופן הבא:
הוספה של תרשים עוגה
דוגמת הקוד הבאה של spreadsheets.batchUpdate מראה איך להשתמש ב-AddChartRequest כדי ליצור תרשים עוגה תלת-ממדי מנתוני המקור. הבקשה מבצעת את הפעולות הבאות כדי להגדיר את התרשים:
- מגדיר את כותרת התרשים.
- הוספת מקרא מימין לתרשים.
- מגדיר את התרשים כתרשים עוגה תלת-ממדי. שימו לב שבתרשימי עוגה תלת-ממדיים לא יכול להיות "חור טבעת" במרכז כמו בתרשימי עוגה שטוחים.
- מגדיר את סדרת הנתונים של התרשים כמספר המכירות הכולל לכל דגם.
- הפונקציה מעוגנת את התרשים בתא C3 של הגיליון שצוין ב-SHEET_ID, עם היסט של 50 פיקסלים גם בכיוון ה-X וגם בכיוון Y.
פרוטוקול הבקשה מוצג למטה.
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
}
}
}
}
}
]
}
הבקשה יוצרת תרשים כזה:
לחלופין, אפשר גם לעדכן את ערך מקרא המיקום מ-RIGHT_LEGEND ל-LABELED_LEGEND בתוך הבקשה, כך שהערכי המקרא יהיו מחוברים לפרוסות של תרשים העוגה.
'legendPosition': 'LABELED_LEGEND',
בבקשה המעודכנת נוצר תרשים כזה:
הוספת תרשים קו שמכיל כמה טווחים לא סמוכים
דוגמת הקוד הבאה של spreadsheets.batchUpdate מראה איך להשתמש בתרשים AddChartRequest כדי ליצור תרשים קו מנתוני המקור, ולהציב אותו בגיליון המקור.
אפשר להשתמש בטווחים לא סמוכים כדי להחריג שורות מהטווח ChartSourceRange.
הבקשה מבצעת את הפעולות הבאות כדי להגדיר את התרשים:
- מגדיר את סוג התרשים כתרשים קו.
- מגדיר את הכותרת של ציר ה-X האופקי.
- מגדירה סדרת נתונים שמייצגת מכירות. היא מגדירה את A1:A3 ואת A6:A7 כ-
domain, ואת B1:B3 ו-B6:B7 כ-series, תוך שימוש בעיצוב ובצבעים שמוגדרים כברירת מחדל. הטווחים מצוינים באמצעות סימון A1 בכתובת ה-URL של הבקשה. - הפונקציה מעוגנת את התרשים בתא H8 בגיליון שצוין ב-SHEET_ID.
פרוטוקול הבקשה מוצג למטה.
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
}
}
}
}
}
}
]
}
הבקשה יוצרת תרשים בגיליון חדש, באופן הבא:
מחיקת תרשים
דוגמת הקוד הבאה של spreadsheets.batchUpdate מראה איך להשתמש ב-DeleteEmbeddedObjectRequest כדי למחוק תרשים שצוין באמצעות CHART_ID.
פרוטוקול הבקשה מוצג למטה.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"deleteEmbeddedObject": {
"objectId": CHART_ID
}
}
]
}
עריכת המאפיינים של תרשים
דוגמת הקוד הבאה של spreadsheets.batchUpdate ממחישה איך להשתמש ב-UpdateChartSpecRequest כדי לערוך את התרשים שנוצר במתכון, Add a columns chart, ולשנות את הנתונים, הסוג והמראה שלו. אי אפשר לשנות בנפרד קבוצות משנה של מאפייני תרשים. כדי לבצע עריכות, צריך לספק את כל השדה spec עם UpdateChartSpecRequest. בעיקרון, כדי לערוך מפרט של תרשים צריך להחליף אותו במפרט חדש.
הבקשה הבאה מעדכנת את התרשים המקורי (מצוין על ידי CHART_ID):
- הגדרת סוג התרשים ל-
BAR. - העברת המקרא לימין התרשים.
- היפוך הצירים כך ש-Sales (מכירות) יהיה בציר התחתון ו-Model Numbers (מספרי דגם) יהיה בציר השמאלי.
- הגדרת הפורמט של כותרת הציר לגופן 24 נקודות, מודגש ונטוי.
- מסירה את נתוני W-24 מהתרשים (שורה 7 בנתוני מקור התרשים).
פרוטוקול הבקשה מוצג למטה.
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
}
}
}
}
]
}
לאחר הבקשה, התרשים ייראה כך:
הזזה או שינוי הגודל של תרשים
דוגמת הקוד הבאה של spreadsheets.batchUpdate מראה איך להשתמש ב-UpdateEmbeddedObjectPositionRequest כדי להזיז תרשים ולשנות את הגודל שלו. אחרי הבקשה, התרשים שצוין באמצעות CHART_ID הוא:
- מעוגנת לתא A5 של הגיליון המקורי.
- הסטה בכיוון ה-X ב-100 פיקסלים.
- שיניתם את הגודל ל-1,200 על 742 פיקסלים (גודל ברירת המחדל לתרשים הוא 600 על 371 פיקסלים).
הבקשה משנה רק את המאפיינים שצוינו עם הפרמטר fields.
נכסים אחרים (כמו offsetYPixels) שומרים על הערכים המקוריים שלהם.
פרוטוקול הבקשה מוצג למטה.
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"
}
}
]
}
קריאת נתוני התרשים
דוגמת הקוד הבאה של spreadsheets.get ממחישה איך לאחזר נתוני תרשים מגיליון אלקטרוני. פרמטר השאילתה fields מציין שצריך להחזיר רק את נתוני התרשים.
התגובה לקריאה ל-method הזו היא אובייקט spreadsheet שמכיל מערך של אובייקטים מה-sheet. כל תרשימים שקיימים בגיליון מיוצגים באובייקט sheet. אם שדה תשובה מוגדר לערך ברירת המחדל, הוא לא יופיע בתשובה.
בדוגמה הזו, בגיליון הראשון (SOURCE_SHEET_ID) אין תרשימים, ולכן מוחזר זוג ריק של סוגריים מסולסלים. בגיליון השני יש את התרשים שנוצר על ידי Add a columns chart, ולא שום דבר נוסף.
פרוטוקול הבקשה מוצג למטה.
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",
},
}
]
}
]
}