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

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