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

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

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

في هذه الأمثلة، العنصران النائبان SPREADSHEET_ID وSHEET_ID يشير إلى مكان تقديم أرقام التعريف هذه. يمكنك العثور على جدول البيانات 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"
      }
    }
  ]
}