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

מסיכות שדות מאפשרות לקריאות ל-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
            }
          }
        }
      }
    }
  ]
}