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