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

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

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

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

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

הפורמט של הפרמטר fields זהה לקידוד JSON של FieldMask. בקצרה, כמה שדות שונים מופרדים בפסיקים, ושדות משנה מופרדים בנקודות. אפשר לציין את שמות השדות בפורמט camelCase או בפורמט separated_by_underscores. לנוחות, אפשר לציין כמה שדות משנה מאותו סוג בסוגריים.

בדוגמה הבאה לבקשת שיטת presentations.get נעשה שימוש במסכת שדה של slides.pageElements(objectId,size,transform) כדי לאחזר רק את מזהה האובייקט, Size, ואת הטרנספורמציה של אובייקט pageElement בכל השקופיות במצגת:

GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)

התגובה לקריאה לשיטה הזו היא אובייקט presentations שמכיל את הרכיבים שביקשת במסכת השדה:

{
  "slides": [
    {
      "pageElements": [
        {
          "objectId": "OBJECT_ID",
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1
            "translateX": 311708,
            "translateY": 744575,
            "unit": "EMU"
          }
        },
        {
          "objectId": "OBJECT_ID",
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1
            "translateX": 311700,
            "translateY": 2834125,
            "unit": "EMU"
          }
        }
     ]
    }
  ]
}

עדכון באמצעות מסכת שדה

לפעמים צריך לעדכן רק שדות מסוימים באובייקט, בלי לשנות את השדות האחרים. בקשות עדכון בתוך method‏ presentations.batchUpdate משתמשות במסכות שדות כדי להודיע ל-API אילו שדות משתנים. בקשת העדכון מתעלמת משדות שלא צוינו במסכת השדות, ומשאירה אותם עם הערכים הנוכחיים שלהם.

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

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

בדוגמה הבאה נעשה שימוש ב-method‏ UpdateShapePropertiesRequest כדי לשנות את מילוי הצבע של צורה לצבע העיצוב DARK1 ולבטל את ההגדרה של קווי המתאר של הצורה:

POST https://slides.googleapis.com/v1/presentations/presentationId:batchUpdate
 
{
  "requests": [
    {
      "updateShapeProperties": {
        "objectId": OBJECT_ID,
        "shapeProperties": {
          "shapeBackgroundFill": {
            "solidFill": {
              "color": {
                "themeColor": "DARK1"
              }
            }
          }
        },
        "fields": "shapeBackgroundFill.solidFill.color,outline"
      }
    }
  ]
}