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

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

קריאה עם אנונימיזציה של השדה

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

הפורמט של הפרמטר 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)

התגובה לקריאה של השיטה הזו היא אובייקט 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
            }
          }
        }
      }
    }
  ]
}