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

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

קריאה באמצעות התממה של שדות

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

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