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

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

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

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

בנוסף, placeholders NAMED_RANGE_ID ו-PROTECTED_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"
      }
    }
  ]
}