تتيح لك Google Sheets API إنشاء المخططات وتحديثها داخل جداول البيانات احتاجت. توضح الأمثلة في هذه الصفحة كيف يمكنك تحقيق بعض الأشياء الشائعة وعمليات المخططات باستخدام Sheets API.
يتم تقديم هذه الأمثلة في شكل طلبات HTTP لتكون اللغة محايدة. لمعرفة كيفية تنفيذ تحديث مجمّع بلغات مختلفة باستخدام مكتبات عملاء واجهة Google API، راجع تحديث جداول البيانات.
في هذه الأمثلة، العنصران النائبان SPREADSHEET_ID وSHEET_ID
يشير إلى مكان تقديم أرقام التعريف هذه. يمكنك العثور على جدول البيانات
ID في عنوان URL لجدول البيانات. يمكنك الحصول على
معرّف الورقة باستخدام
spreadsheets.get تشير رسالة الأشكال البيانية
يتم تحديد النطاقات باستخدام ترميز A1. إنّ
مثال النطاق هو Sheet1!A1:D5.
بالإضافة إلى ذلك، يشير العنصر النائب CHART_ID إلى معرّف
المخطط. يمكنك ضبط هذا المعرّف عند إنشاء رسم بياني باستخدام Sheets API،
أو السماح لـ Sheets API بإنشاء حساب لك. يمكنك الحصول على معرفات
المخططات الحالية مع
spreadsheets.get.
أخيرًا، يشير العنصر النائب SOURCE_SHEET_ID إلى الورقة باستخدام بيانات المصدر. في هذه الأمثلة، هذا هو الجدول المدرج ضمن مصدر الرسم البياني .
بيانات مصدر الرسم البياني
بالنسبة إلى هذه الأمثلة، لنفترض أنّ جدول البيانات المُستخدَم يحتوي على المصدر التالي البيانات في الورقة الأولى ("Sheet1"). السلاسل الموجودة في الصف الأول هي تسميات الأعمدة الفردية. لعرض أمثلة حول كيفية القراءة من الأوراق الأخرى في جدول البيانات، راجِع تدوين A1.
| A | ب | 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
}
}
}
}
}
]
}
ينشئ الطلب مخططًا مثل هذا:
بدلاً من ذلك، يمكنك أيضًا تعديل قيمة hotelPosition (وضع الإيضاح) من 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
لتعديل المخطط الذي تم إنشاؤه في وصفة إضافة رسم بياني عمودي،
تعديل بياناته ونوعه ومظهره. لا يمكن تنفيذ مجموعات فرعية من سمات الرسم البياني
كل تغيير على حدة. لإجراء تعديلات، يجب توفير الحقل spec بالكامل.
من خلال UpdateChartSpecRequest. بشكل أساسي، يعد تحرير مواصفات المخطط
تتطلب استبدالها بأخرى جديدة.
يقوم الطلب التالي بتحديث المخطط الأصلي (محدد بواسطة CHART_ID):
- تضبط نوع الرسم البياني على
BAR. - لنقل وسيلة الإيضاح إلى يسار الرسم البياني.
- يُقلب المحاور بحيث تكون "المبيعات" موجودة على المحور السفلي و"أرقام الطراز" على المحور الأيسر.
- ضبط تنسيق عنوان المحور ليكون بخط مكوَّن من 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 من ورقة البيانات الأصلية.
- إزاحة في الاتجاه س بمقدار 100 بكسل.
- تم تغيير الحجم إلى 1200 × 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
أنه يجب عرض بيانات المخطط فقط.
الاستجابة لاستدعاء هذه الطريقة هي
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",
},
}
]
}
]
}