النطاقات المُعنوَنة والمحمية

تتيح لك 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"
      }
    }
  ]
}