API گوگل شیت به شما امکان میدهد نمودارها را در صفحات گسترده ایجاد و در صورت نیاز بهروزرسانی کنید. مثالهای این صفحه نشان میدهد که چگونه میتوانید با استفاده از API شیت، برخی از عملیات رایج روی نمودارها را انجام دهید.
این مثالها به صورت درخواستهای HTTP ارائه شدهاند تا از نظر زبانی بیطرف باشند. برای یادگیری نحوه پیادهسازی بهروزرسانی دستهای در زبانهای مختلف با استفاده از کتابخانههای کلاینت API گوگل، به صفحات گسترده بهروزرسانی مراجعه کنید.
در این مثالها، متغیرهای SPREADSHEET_ID و SHEET_ID
نشان میدهد که این شناسهها را کجا باید ارائه دهید. میتوانید شناسه صفحهگسترده را در URL صفحهگسترده پیدا کنید. میتوانید شناسه صفحه را با استفاده از متد spreadsheets.get دریافت کنید. محدودهها با استفاده از نمادگذاری A1 مشخص شدهاند. یک محدوده به عنوان مثال Sheet1!A1:D5 است.
علاوه بر این، متغیر CHART_ID شناسه نمودار داده شده را نشان میدهد. میتوانید این شناسه را هنگام ایجاد نمودار با Sheets API تنظیم کنید، یا به Sheets API اجازه دهید یکی برای شما ایجاد کند. میتوانید شناسه نمودارهای موجود را با متد spreadsheets.get دریافت کنید.
در نهایت، عبارت SOURCE_SHEET_ID نشان دهندهی شیت شما با دادههای منبع است. در این مثالها، این جدولی است که در زیر Chart source data فهرست شده است.
دادههای منبع نمودار
برای این مثالها، فرض کنید صفحهگسترده مورد استفاده، دادههای منبع زیر را در اولین برگه خود ("Sheet1") دارد. رشتههای موجود در ردیف اول، برچسبهایی برای ستونهای منفرد هستند. برای مشاهده مثالهایی از نحوه خواندن از سایر برگههای صفحهگسترده خود، به نمادگذاری A1 مراجعه کنید.
| الف | ب | سی | دی | ای | |
| ۱ | شماره مدل | فروش - ژانویه | فروش - فوریه | فروش - مارس | کل فروش |
| ۲ | D-01X | ۶۸ | ۷۴ | ۶۰ | ۲۰۲ |
| ۳ | FR-0B1 | ۹۷ | ۷۶ | ۸۸ | ۲۶۱ |
| ۴ | پ-034 | ۲۷ | ۴۹ | ۳۲ | ۱۰۸ |
| ۵ | پ-۱۰۵ | ۴۶ | ۴۴ | ۶۷ | ۱۵۷ |
| ۶ | W-11 | ۷۵ | ۶۸ | ۸۷ | ۲۳۰ |
| ۷ | W-24 | ۷۴ | ۵۲ | ۶۲ | ۱۸۸ |
اضافه کردن نمودار ستونی
نمونه کد spreadsheets.batchUpdate زیر نحوه استفاده از AddChartRequest برای ایجاد نمودار ستونی از دادههای منبع و قرار دادن آن در یک برگه جدید را نشان میدهد. این درخواست برای پیکربندی نمودار، اقدامات زیر را انجام میدهد:
- نوع نمودار را به صورت نمودار ستونی تنظیم میکند.
- یک راهنما به پایین نمودار اضافه میکند.
- عنوان نمودار و محورها را تنظیم میکند.
- ۳ سری داده را پیکربندی میکند که نشاندهنده فروش برای ۳ ماه مختلف است و از قالببندی و رنگهای پیشفرض استفاده میکند.
پروتکل درخواست در زیر نشان داده شده است.
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 ، با آفست ۵۰ پیکسل در هر دو جهت 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 } } } } } ] }
این درخواست، نموداری مانند زیر ایجاد میکند:
به عنوان یک روش جایگزین، میتوانید مقدار legendPosition را از RIGHT_LEGEND به LABELED_LEGEND در داخل درخواست بهروزرسانی کنید تا مقادیر 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 را برای ویرایش نمودار ایجاد شده در دستور العمل افزودن نمودار ستونی ، تغییر دادهها، نوع و ظاهر آن نشان میدهد. زیرمجموعههای ویژگیهای نمودار را نمیتوان به صورت جداگانه تغییر داد. برای انجام ویرایشها، باید کل فیلد spec را با UpdateChartSpecRequest ارائه دهید. اساساً، ویرایش مشخصات نمودار مستلزم جایگزینی آن با یک مورد جدید است.
درخواست زیر نمودار اصلی (مشخص شده توسط CHART_ID ) را بهروزرسانی میکند:
- نوع نمودار را روی
BARتنظیم میکند. - راهنما را به سمت راست نمودار منتقل میکند.
- محورها را معکوس میکند به طوری که «فروش» در محور پایین و «شماره مدل» در محور چپ قرار گیرد.
- قالب عنوان محور را روی فونت ۲۴ نقطهای، پررنگ و ایتالیک تنظیم میکند.
- دادههای "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 به اندازه ۱۰۰ پیکسل جابجا میشود.
- به ابعاد ۱۲۰۰ در ۷۴۲ پیکسل تغییر اندازه داده شد (اندازه پیشفرض برای نمودار ۶۰۰ در ۳۷۱ پیکسل است).
این درخواست فقط ویژگیهایی را که با پارامتر 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 زیر نحوه دریافت دادههای نمودار از یک صفحه گسترده را نشان میدهد. پارامتر query fields مشخص میکند که فقط دادههای نمودار باید بازگردانده شوند.
پاسخ به این فراخوانی متد، یک شیء 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", }, } ] } ] }