تتيح لك Google Sheets API إنشاء المخططات وتحديثها داخل جداول البيانات حسب الحاجة. توضح الأمثلة في هذه الصفحة كيف يمكنك تحقيق بعض عمليات المخططات الشائعة باستخدام 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.
| جيم | 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.
ينفذ الطلب ما يلي لضبط الرسم البياني:
- لضبط نوع الرسم البياني كرسم بياني خطي.
- لتعيين عنوان المحور 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
لتعديل الرسم البياني الذي تم إنشاؤه في وصفة إضافة رسم بياني عمودي،
وتعديل بياناته ونوعه ومظهره. لا يمكن تغيير المجموعات الفرعية لخصائص الرسم
البياني بشكل فردي. لإجراء تعديلات، عليك إضافة السمة UpdateChartSpecRequest إلى الحقل spec بالكامل. بشكل أساسي، يتطلب تحرير مواصفات
المخطط استبدالها بمواصفات جديدة.
يعدّل الطلب التالي الرسم البياني الأصلي (تم تحديده من خلال "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",
},
}
]
}
]
}