מסיכות שדות מאפשרות לקריאות ל-API לרשום את השדות שהבקשה צריכה להחזיר או לעדכן. באמצעות FieldMask מאפשר ל-API להימנע מעבודה מיותרת ומשפר את הביצועים. אנונימיזציה של שדות משמשת גם לשיטות הקריאה והעדכון ב-Google Sheets API.
קריאה באמצעות התממה של שדות
גיליונות אלקטרוניים יכולים להיות גדולים, ובחלק גדול מהמקרים לא צריך את כל החלקים
Spreadsheet
משאב שהוחזר בעקבות בקשת קריאה. אפשר להגביל את מה שמחזיר
תגובת Sheets מ-API באמצעות הפרמטר fields
של כתובת ה-URL. לטוב ביותר
ביצועים,
לציין במפורש רק את השדות שנחוצים לכם.
בתשובה.
הפורמט של הפרמטר בשדות זהה לפורמט של הפרמטר קידוד JSON של FieldMask. מצוין לזמן קצר, שדות שונים מופרדים בפסיקים ושדות משנה מופרדת באמצעות נקודות. אפשר לציין שמות של שדות ב-camelCase או separated_by_underscores. לנוחיותכם, ניתן להשתמש בכמה שדות משנה מאותה נקודה יכול להופיע בתוך סוגריים.
הבאים
בקשת spreadsheets.get
הדוגמה משתמשת באנונימיזציה של השדות sheets.properties(sheetId,title,sheetType,gridProperties)
כדי
אחזר רק את מזהה הגיליון, הכותרת
SheetType
, וגם
GridProperties
של
SheetProperties
בכל הגיליונות בגיליון האלקטרוני:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties(sheetId,title,sheetType,gridProperties)
התגובה לקריאת ה-method הזו היא
Spreadsheet
שמכיל את הרכיבים שהתבקשו במסכת השדות. שימו לב
sheetType=OBJECT
לא מכיל gridProperties
:
{ "sheets": [ { "properties": { "sheetId":SHEET_ID
, "title": "TITLE
", "sheetType": "GRID", "gridProperties": { "rowCount": 1000, "columnCount": 25 } } }, { "properties": { "sheetId":SHEET_ID
, "title": "TITLE
", "sheetType": "OBJECT" } } ] }
עדכון באמצעות מסכת שדות
לפעמים תצטרכו לעדכן רק שדות מסוימים באובייקט תוך השארת
ושאר השדות ללא שינוי. בקשות עדכון בתוך
spreadsheets.batchUpdate
פעולה זו משתמשת במסכות של שדות כדי לציין ל-API אילו שדות משתנים.
בקשת עדכון מתעלמת משדות שלא צוינו במסכת השדות,
ולהשאיר אותם עם הערכים הנוכחיים שלהם.
ניתן גם לבטל את ההגדרה של שדה אם לא מציינים אותו בהודעה המעודכנת, אבל כשמוסיפים את השדה למסכה. הפעולה הזו מנקה את הערך הקודם בשדה היה.
התחביר של עדכון מסכות של שדות זהה לתחביר של מסכות קריאה של שדות.
הדוגמה הבאה משתמשת
AddSheetRequest
להוספת גיליון חדש מסוג Grid
, להקפיא את השורה הראשונה ולצבע את הגיליון החדש
אדום בלשונית בגיליון:
POST https://sheets.googleapis.com/v1/spreadsheets/spreadsheetId:batchUpdate
{ "spreadsheetId": "SPREADSHEET_ID
", "replies": [ { "addSheet": { "properties": { "sheetId":SHEET_ID
, "title": "TITLE
", "index": 6, "sheetType": "GRID", "gridProperties": { "rowCount": 1000, "columnCount": 26, "frozenRowCount": 1 }, "tabColor": { "red": 0.003921569 }, "tabColorStyle": { "rgbColor": { "red": 0.003921569 } } } } } ] }