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

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

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

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

בנוסף, משתמשי placeholder‏ 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"
      }
    }
  ]
}