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

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

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

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

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

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

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

.

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