שימוש במסיכות שדה

מסכות שדות הן דרך שמאפשרת למפעילי ה-API לרשום את השדות שהבקשה אמורה להחזיר או לעדכן. שימוש ב-FieldMask מאפשר ל-API להימנע מעבודה מיותרת ולשפר את הביצועים. מסכת שדה משמשת גם בשיטות הקריאה וגם בשיטות העדכון ב-Google Sheets API.

קריאה עם מסכת שדה

גיליונות אלקטרוניים יכולים להיות גדולים, ולרוב לא צריך את כל החלקים של המשאב Spreadsheet שמוחזר על ידי בקשת קריאה. אפשר להגביל את מה שמוחזר בתגובה של API של Sheets באמצעות פרמטר כתובת ה-URL fields. כדי לשפר את הביצועים, מומלץ לציין במפורש רק את השדות הנחוצים בתשובה.

הפורמט של הפרמטר fields זהה לקידוד 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 אילו שדות משתנים. בקשת העדכון מתעלמת משדות שלא צוינו במסכת השדות, ומשאירה אותם עם הערכים הנוכחיים שלהם.

אפשר גם לבטל את ההגדרה של שדה מסוים על ידי אי ציון שלו בהודעה המעודכנת, אבל הוספת השדה לתבנית. הפעולה הזו מנקה את הערך הקודם שהיה בשדה.

התחביר של אנונימיזציה של שדות לעדכון זהה לזה של אנונימיזציה של שדות לקריאה.

מסכת שדה של * נחשבת כתו כללי לחיפוש, והיא קיצור דרך לציון כל השדות בהודעה. תחביר התו הכללי יכול להניב תוצאות לא רצויות אם ה-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
            }
          }
        }
      }
    }
  ]
}