Google Sheets API מאפשר ליצור, לשנות ולמחוק טווחים בעלי שם או מוגנים. הדוגמאות בדף הזה ממחישות איך אפשר לבצע פעולות נפוצות ב-Sheets באמצעות ה-API של Sheets.
הדוגמאות האלה מוצגות בפורמט של בקשות HTTP ניטרליות מבחינת שפה. על מנת ללמוד כיצד ליישם עדכון ברצף בשפות שונות באמצעות ספריות הלקוח של Google API, קראו את המאמר עדכון גיליונות אלקטרוניים.
בדוגמאות האלה, ערכי ה-placeholder SPREADSHEET_ID ו-SHEET_ID מציינים איפה הייתם מספקים את המזהים האלה. המזהה של הגיליון האלקטרוני מופיע בכתובת ה-URL של הגיליון האלקטרוני. אפשר לאתר את מזהה הגיליון באמצעות השיטה spreadsheets.get. הטווחים מצוינים באמצעות סימון A1. טווח לדוגמה הוא Sheet1!A1:D5.
בנוסף, ה-placeholders NAMED_RANGE_ID ו-PROTECTED_RANGE_ID מספקים את המזהים לטווחים בעלי שם ולטווחים המוגנים. כששולחים בקשות לעדכון או למחיקה של הטווחים המשויכים, נעשה שימוש ב-namedRangeId וב-protectedRangeId. המזהה מוחזר בתגובה לבקשת API של Sheets שיוצרת טווח תאים בעל שם או טווח מוגן. אפשר לקבל את המזהים של טווחים קיימים באמצעות השיטה 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"
}
}
]
}