באמצעות 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" } } ] }