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

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

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

في هذه الأمثلة، يشير العنصران النائبان SPREADSHEET_ID وSHEET_ID إلى المكان الذي يجب فيه تقديم أرقام التعريف هذه. يمكنك العثور على رقم تعريف جدول البيانات في عنوان URL الخاص بجدول البيانات. يمكنك الحصول على معرّف جدول البيانات باستخدام الطريقة spreadsheets.get. يتم تحديد النطاقات باستخدام ترميز A1. مثال على النطاق: الورقة1!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"
      }
    }
  ]
}