Google Sheets API מאפשר ליצור ולעדכן תרשימים בתוך גיליונות אלקטרוניים הדרושים. הדוגמאות בדף הזה ממחישות איך אפשר להשיג תרשים פעולות באמצעות ה-API של Sheets.
הדוגמאות האלה מוצגות בצורה של בקשות HTTP ניטרלי. כדי ללמוד איך להטמיע עדכון בכמות גדולה בשפות שונות באמצעות על ספריות הלקוח של Google API, ראו עדכון גיליונות אלקטרוניים.
בדוגמאות האלה, ערכי ה-placeholders SPREADSHEET_ID ו-SHEET_ID
מציין איפה תציינו את המזהים האלה. הגיליון האלקטרוני נמצא
ID בכתובת ה-URL של הגיליון האלקטרוני. אפשר לקבל
את מזהה הגיליון באמצעות
spreadsheets.get.
מציינים טווחים באמצעות סימון A1.
הטווח לדוגמה הוא Sheet1!A1:D5.
בנוסף, ה-placeholder CHART_ID מציין את המזהה של נתון
תרשים. אפשר להגדיר את המזהה הזה כשיוצרים תרשים באמצעות Sheets API,
או לאפשר ל-Sheets API ליצור בשבילכם נכס כזה. אפשר לקבל את המזהים של
תרשימים קיימים עם
spreadsheets.get.
לבסוף, ה-placeholder SOURCE_SHEET_ID מציין שהגיליון שלכם מכיל בנתוני המקור. בדוגמאות האלו, זו הטבלה שמופיעה בקטע מקור התרשים .
נתוני המקור של התרשים
בדוגמאות האלה, נניח שהגיליון האלקטרוני שבו אתם משתמשים כולל את המקור הבא בגיליון הראשון ("גיליון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
כדי ליצור תרשים עוגה תלת-ממדי מנתוני המקור. הבקשה מבצעת את הפעולות הבאות כדי
להגדיר את התרשים:
- מגדיר את כותרת התרשים.
- הוספת מקרא מימין לתרשים.
- מגדיר את התרשים כתרשים עוגה תלת-ממדי. הערה: בתרשימי עוגה תלת-ממדיים לא יכולים להיות ' donut hole' במרכז, כמו שתרשימי עוגה שטוחים יכולים להופיע.
- מגדיר את סדרת הנתונים של התרשים כמספר המכירות הכולל לכל דגם.
- הפונקציה מעוגנת את התרשים בתא 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:B7series, תוך שימוש בעיצוב ובצבעים שמוגדרים כברירת מחדל. הטווחים מצוינים באמצעות 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
כדי לערוך את התרשים שנוצר במתכון של הוספת תרשים עמודות,
ולשנות את הנתונים, הסוג והמראה שלו. קבוצות משנה של מאפייני תרשים לא יכולות
השתנה בנפרד. כדי לערוך, עליך לספק את כל השדה של spec
עם UpdateChartSpecRequest. למעשה, עריכת מפרט של תרשים
דורש להחליף אותו במכשיר חדש.
הבקשה הבאה מעדכנת את התרשים המקורי (מצוין על ידי CHART_ID):
- הגדרת סוג התרשים ל-
BAR. - העברת המקרא לימין התרשים.
- היפוך הצירים כך ש-"Sales" נמצאת בציר התחתון ובקטע 'מספרי המודל'. נמצאת על הציר השמאלי.
- הגדרת הפורמט של כותרת הציר לגופן 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) אין של סוגריים מסולסלים, כך שיוחזרו זוג סוגריים מסולסלים ריקים. בגיליון השני יש את שנוצר באמצעות השילוב הוספת תרשים עמודות אנכי, ולא שום דבר נוסף.
פרוטוקול הבקשה מוצג למטה.
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",
},
}
]
}
]
}