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

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

این مثال‌ها به صورت درخواست‌های HTTP ارائه شده‌اند تا از نظر زبانی بی‌طرف باشند. برای یادگیری نحوه پیاده‌سازی به‌روزرسانی دسته‌ای در زبان‌های مختلف با استفاده از کتابخانه‌های کلاینت 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 زیر نحوه استفاده از دو شیء درخواست را نشان می‌دهد. اولی از AddNamedRangeRequest برای اختصاص نام "Counts" به محدوده 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 از یک فراخوانی 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 زیر نحوه استفاده از ۲ شیء درخواست را نشان می‌دهد. اولین مورد از 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"
      }
    }
  ]
}