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