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

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

يتم تقديم هذه الأمثلة في شكل طلبات 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"
      }
    }
  ]
}