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

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

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

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

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

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

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

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