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

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

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

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

התגובה לקריאה ל-method היא אובייקט Presentation שמכיל את הרכיבים שביקשת במסכת השדות:

{
  "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"
          }
        }
     ]
    }
  ]
}

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

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

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

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

בדוגמה הבאה נעשה שימוש ב-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"
      }
    }
  ]
}