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