تتيح لك Google Sheets API إنشاء نطاقات مُعنوَنة أو محمية وتعديلها وحذفها. توضح الأمثلة الموجودة في هذه الصفحة كيف يمكنك تحقيق بعض العمليات الشائعة في "جداول بيانات Google" باستخدام 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 إلى الاسم "Counts". يستخدم الترميز الثاني
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
لتعديل اسم نطاق مُعنوَن حالي إلى "FirstCounts"، وذلك باستخدام 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" } } ] }