با نام & محدوده های محافظت شده

Google Sheets API به شما امکان می‌دهد محدوده‌های نام‌گذاری‌شده یا محافظت‌شده را ایجاد، اصلاح و حذف کنید. مثال‌های موجود در این صفحه نشان می‌دهند که چگونه می‌توانید به برخی از عملیات رایج Sheets با Sheets API دست پیدا کنید.

این نمونه ها در قالب درخواست های HTTP برای خنثی بودن زبان ارائه شده اند. برای یادگیری نحوه اجرای یک به‌روزرسانی دسته‌ای به زبان‌های مختلف با استفاده از کتابخانه‌های سرویس گیرنده Google API، به به‌روزرسانی صفحات گسترده مراجعه کنید.

در این مثال‌ها، متغیرهای SPREADSHEET_ID و SHEET_ID نشان می‌دهند که کجا آن شناسه‌ها را ارائه می‌کنید. می‌توانید شناسه صفحه‌گسترده را در URL صفحه‌گسترده پیدا کنید. با استفاده از روش spreadsheets.get می توانید شناسه برگه را دریافت کنید. محدوده ها با استفاده از نماد A1 مشخص می شوند. محدوده نمونه Sheet1!A1:D5 است.

علاوه بر این، متغیرهای NAMED_RANGE_ID و PROTECTED_RANGE_ID شناسه‌های محدوده‌های نام‌گذاری‌شده و محافظت‌شده را ارائه می‌کنند. namedRangeId و protectedRangeId هنگام درخواست برای به روز رسانی یا حذف محدوده های مرتبط استفاده می شود. شناسه در پاسخ به درخواست Sheets API که یک محدوده نامگذاری شده یا محافظت شده ایجاد می کند، بازگردانده می شود. می‌توانید شناسه‌های محدوده‌های موجود را با روش spreadsheets.get در بدنه پاسخ Spreadsheet دریافت کنید.

محدوده های نامگذاری شده یا محافظت شده را اضافه کنید

نمونه کد spreadsheets.batchUpdate زیر نحوه استفاده از 2 شی درخواست را نشان می دهد. اولین مورد از AddNamedRangeRequest استفاده می کند تا محدوده A1:E3 را با نام "Counts" اختصاص دهد. دومی از 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 زیر نحوه استفاده از 2 شی درخواست را نشان می دهد. اولین مورد از DeleteNamedRangeRequest برای حذف یک محدوده با نام موجود با استفاده از NAMED_RANGE_ID از یک تماس API قبلی استفاده می کند. دومی از DeleteProtectedRangeRequest برای حذف حفاظت محدوده موجود با استفاده از PROTECTED_RANGE_ID از یک تماس API قبلی استفاده می کند.

پروتکل درخواست در زیر نشان داده شده است. 

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "deleteNamedRange": {
          "namedRangeId": "NAMED_RANGE_ID",
      }
    },
    {
      "deleteProtectedRange": {
        "protectedRangeId": PROTECTED_RANGE_ID,
      }
    }
  ]
}

محدوده های نامگذاری شده یا محافظت شده را به روز کنید

نمونه کد spreadsheets.batchUpdate زیر نحوه استفاده از 2 شی درخواست را نشان می دهد. اولین مورد از UpdateNamedRangeRequest برای به روز رسانی نام یک محدوده نامگذاری شده موجود به "InitialCounts" استفاده می کند، با استفاده از NAMED_RANGE_ID از یک تماس API قبلی. دومی از UpdateProtectedRangeRequest برای به روز رسانی یک محدوده حفاظت شده موجود استفاده می کند به طوری که اکنون از همان محدوده نامگذاری شده محافظت می کند. روش Editors فقط به کاربران لیست شده اجازه می دهد تا آن سلول ها را ویرایش کنند. این درخواست از NAMED_RANGE_ID و PROTECTED_RANGE_ID تماس‌های API قبلی استفاده می‌کند.

پروتکل درخواست در زیر نشان داده شده است. 

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"
      }
    }
  ]
}