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

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

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

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

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