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

تتيح لك Google Sheets API إنشاء نطاقات مُسَمّاة أو محمية وتعديلها وحذفها. توضّح الأمثلة الواردة في هذه الصفحة كيفية تنفيذ بعض العمليات الشائعة في "جداول بيانات Google" باستخدام واجهة برمجة التطبيقات Sheets API.

يتم تقديم هذه الأمثلة في شكل طلبات HTTP لتكون متعافِية من اللغة. للتعرّف على كيفية تنفيذ تعديل مجمّع بلغات مختلفة باستخدام مكتبات برامج Google API، اطّلِع على مقالة تعديل جداول بيانات Google.

في هذه الأمثلة، يشير العنصران النائبان SPREADSHEET_ID وSHEET_ID إلى مكان تقديم هذين المعرّفَين. يمكنك العثور على رقم تعريف جدول البيانات في عنوان URL لجدول البيانات. يمكنك الحصول على معرّف جدول البيانات باستخدام الأسلوب spreadsheets.get. يتم تحديد النطاقات باستخدام ترميز A1. أحد مثالي النطاق هو الورقة1!A1:D5.

بالإضافة إلى ذلك، يوفِّر العنصران النائبان NAMED_RANGE_ID وPROTECTED_RANGE_ID المعرِّفات للنطاقات المُعنوَنة والمحمية. يتم استخدام namedRangeId و protectedRangeId عند تقديم طلبات لتعديل النطاقات المرتبطة أو حذفها. يتم عرض رقم التعريف في الاستجابة لطلب واجهة برمجة التطبيقات لخدمة "جداول بيانات Google" الذي ينشئ نطاقًا مُسمّى أو محميًا. يمكنك الحصول على أرقام تعريف النطاقات الحالية باستخدام طريقة 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 لتعديل اسم نطاق حالي يحمل اسم "القيم_الأولية" إلى "القيم_الأولية"، وذلك باستخدام 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"
      }
    }
  ]
}