Google Sheets API מאפשר ליצור ולעדכן תרשימים בתוך גיליונות אלקטרוניים, לפי הצורך. הדוגמאות בדף הזה ממחישות איך אפשר לבצע פעולות נפוצות בתרשים באמצעות Sheets API.
הדוגמאות האלה מוצגות בפורמט של בקשות HTTP ניטרליות מבחינת שפה. על מנת ללמוד כיצד ליישם עדכון ברצף בשפות שונות באמצעות ספריות הלקוח של Google API, קראו את המאמר עדכון גיליונות אלקטרוניים.
בדוגמאות האלה, ערכי ה-placeholder SPREADSHEET_ID ו-SHEET_ID מציינים איפה הייתם מספקים את המזהים האלה. המזהה של הגיליון האלקטרוני מופיע בכתובת ה-URL של הגיליון האלקטרוני. אפשר לאתר את מזהה הגיליון באמצעות השיטה spreadsheets.get. הטווחים מצוינים באמצעות סימון A1. טווח לדוגמה הוא Sheet1!A1:D5.
בנוסף, ה-placeholder CHART_ID מציין את המזהה של תרשים נתון. תוכלו להגדיר את המזהה הזה כשאתם יוצרים תרשים באמצעות Sheets API, או לאפשר ל-Sheets API ליצור תרשים בשבילכם. אפשר לקבל את המזהים של תרשימים קיימים באמצעות השיטה spreadsheets.get.
לבסוף, ה-placeholder הזה SOURCE_SHEET_ID מציין את הגיליון עם נתוני המקור. בדוגמאות האלה זו הטבלה שמופיעה בקטע Chart source data.
נתוני המקור של התרשים
לצורך הדוגמאות האלה, נניח שהגיליון הראשון שבו נעשה שימוש כולל את נתוני המקור הבאים בגיליון הראשון (Sheet1). המחרוזות בשורה הראשונה הן תוויות של העמודות הנפרדות. לצפייה בדוגמאות של קריאה מגיליונות אחרים בגיליון האלקטרוני, קראו את הקטע סימון A1.
| A | B | C | D | ה. | |
| 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
}
}
}
}
}
]
}
הבקשה יוצרת תרשים כזה:
לחלופין, ניתן גם לעדכן בבקשה את ערך ה-Legends מ-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 column 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 column 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",
},
}
]
}
]
}