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

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

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

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

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

התגובה לקריאה הזו של השיטה היא אובייקט 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"
      }
    }
  ]
}