טווחים מוגנים בעלי שם

באמצעות Google Sheets API אפשר ליצור, לשנות ולמחוק טווחים עם שם או טווחים מוגנים. בדוגמאות שבדף הזה מוסבר איך לבצע פעולות נפוצות ב-Sheets באמצעות Sheets API.

הדוגמאות האלה מוצגות כבקשות HTTP כדי שיהיו ניטרליות מבחינת שפה. במאמר עדכון גיליונות אלקטרוניים מוסבר איך מטמיעים עדכון באצווה בשפות שונות באמצעות ספריות הלקוח של Google API.

בדוגמאות האלה, התוויות SPREADSHEET_ID ו-SHEET_ID מצביעות על המקומות שבהם צריך לספק את המזהים האלה. המזהה של הגיליון האלקטרוני מופיע בכתובת ה-URL של הגיליון האלקטרוני. אפשר לקבל את מזהה הגיליון באמצעות ה-method‏ spreadsheets.get. טווחי הנתונים מצוינים באמצעות סימון A1. דוגמה לטווח היא Sheet1!A1:D5.

בנוסף, התוויות האלה מספקות את המזהים של טווחי השמות והטווחים המוגנים.NAMED_RANGE_IDPROTECTED_RANGE_ID משתמשים ב-namedRangeId וב-protectedRangeId כששולחים בקשות לעדכון או למחיקה של הטווחים המשויכים. המזהה מוחזר בתגובה לבקשה של Sheets API שנוצרת בה טווח בעל שם או מוגן. אפשר לקבל את המזהים של טווחים קיימים באמצעות ה-method‏ spreadsheets.get, בגוף התגובה Spreadsheet.

הוספת טווחים מוגנים או טווחים עם שם

בדוגמת הקוד הבאה של spreadsheets.batchUpdate מוסבר איך להשתמש בשני אובייקטי בקשה. בקוד הראשון נעשה שימוש ב-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 מוסבר איך להשתמש בשני אובייקטי בקשה. בקריאה הראשונה נעשה שימוש ב-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"
      }
    }
  ]
}