تتيح لك Google Sheets API إنشاء نطاقات مُسَمّاة أو محمية وتعديلها وحذفها. توضح الأمثلة في هذه الصفحة كيف يمكنك تحقيق بعض عمليات جداول البيانات الشائعة باستخدام Sheets API.
يتم تقديم هذه الأمثلة في شكل طلبات HTTP لتكون محايدة اللغة. لمعرفة كيفية تنفيذ تعديل مجمّع بلغات مختلفة باستخدام مكتبات برامج واجهة Google API، يمكنك الاطّلاع على مقالة تحديث جداول البيانات.
في هذه الأمثلة، يشير العنصران النائبان SPREADSHEET_ID
وSHEET_ID
إلى مكان تقديم هذين المعرّفَين. يمكنك العثور على رقم تعريف
جدول البيانات في عنوان URL لجدول البيانات. يمكنك الحصول على معرّف ورقة البيانات باستخدام الطريقة spreadsheets.get
. يتم تحديد النطاقات باستخدام ترميز A1. مثال على النطاق
Sheet1!A1:D5.
بالإضافة إلى ذلك، يوفِّر العنصران النائبان NAMED_RANGE_ID
وPROTECTED_RANGE_ID
المعرِّفات للنطاقات المُعنوَنة والمحمية. يتم استخدام namedRangeId
وprotectedRangeId
عند تقديم طلبات لتعديل
النطاقات المرتبطة أو حذفها. يتم عرض رقم التعريف في الرد على طلب Sheets API
الذي ينشئ نطاقًا مُعنوَنًا أو محميًا. يمكنك الحصول على أرقام تعريف النطاقات
الحالية باستخدام
طريقة spreadsheets.get
، في
نص الردّ
Spreadsheet
.
إضافة نطاقات مُعنوَنة أو محمية
يوضح نموذج الرمز البرمجي
spreadsheets.batchUpdate
التالي كيفية استخدام كائنَين للطلب. يستخدم العنصر الأول الرمز
AddNamedRangeRequest
لتحديد النطاق A1:E3 باسم "العدد". والثاني يستخدم
AddProtectedRangeRequest
لإرفاق حماية على مستوى التحذير بالنطاق A4:E4. تظل حماية المستوى هذه
تسمح بتعديل الخلايا داخل النطاق، ولكنها تطلب تحذيرًا قبل
إجراء التغيير.
تعرض هذه الطلبات رمزَي AddNamedRangeResponse
وAddProtectedRangeResponse
يتضمّنان معرّفات النطاقات والسمات.
في ما يلي بروتوكول الطلب.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
:batchUpdate
{ "requests": [ { "addNamedRange": { "namedRange": { "name": "Counts", "range": { "sheetId":SHEET_ID
, "startRowIndex": 0, "endRowIndex": 3, "startColumnIndex": 0, "endColumnIndex": 5, }, } } }, { "addProtectedRange": { "protectedRange": { "range": { "sheetId":SHEET_ID
, "startRowIndex": 3, "endRowIndex": 4, "startColumnIndex": 0, "endColumnIndex": 5, }, "description": "Protecting total row", "warningOnly": true } } } ] }
حذف النطاقات المُعنونة أو المحمية
يوضح نموذج الرمز البرمجي
spreadsheets.batchUpdate
التالي كيفية استخدام كائنَين للطلب. يستخدم العنصر الأول DeleteNamedRangeRequest
لحذف نطاق مُعنوَن حالي، وذلك باستخدام NAMED_RANGE_ID
من طلب بيانات سابق من واجهة برمجة التطبيقات. أمّا الطريقة الثانية، فتستخدم
DeleteProtectedRangeRequest
لحذف حماية نطاق حالية، وذلك باستخدام PROTECTED_RANGE_ID
من طلب بيانات سابق من واجهة برمجة التطبيقات.
في ما يلي بروتوكول الطلب.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
:batchUpdate
{ "requests": [ { "deleteNamedRange": { "namedRangeId": "NAMED_RANGE_ID
", } }, { "deleteProtectedRange": { "protectedRangeId":PROTECTED_RANGE_ID
, } } ] }
تعديل النطاقات المُعنونة أو المحمية
يوضح نموذج الرمز البرمجي
spreadsheets.batchUpdate
التالي كيفية استخدام كائنَين للطلب. يستخدم النوع الأول الرمز
UpdateNamedRangeRequest
لتعديل اسم نطاق مُعنوَن حالي إلى "InitialCounts"، باستخدام NAMED_RANGE_ID
من طلب بيانات سابق من واجهة برمجة التطبيقات. والثاني يستخدم UpdateProtectedRangeRequest
لتعديل نطاق محمي حالي، لكي يحمي الآن النطاق المُعنوَن نفسه. تسمح طريقة
Editors
للمستخدمين المدرَجين فقط بتعديل هذه الخلايا. يستخدم هذا الطلب NAMED_RANGE_ID
وPROTECTED_RANGE_ID
من طلبات البيانات السابقة من واجهة برمجة التطبيقات.
في ما يلي بروتوكول الطلب.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
:batchUpdate
{ "requests": [ { "updateNamedRange": { "namedRange": { "namedRangeId":NAMED_RANGE_ID
, "name": "InitialCounts", }, "fields": "name", } }, { "updateProtectedRange": { "protectedRange": { "protectedRangeId":PROTECTED_RANGE_ID
, "namedRangeId":NAMED_RANGE_ID
, "warningOnly": false, "editors": { "users": [ "charlie@example.com", "sasha@example.com" ] } }, "fields": "namedRangeId,warningOnly,editors" } } ] }