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

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