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

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

קריאה באמצעות התממה של שדות

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

הפורמט של הפרמטר בשדות זהה לקידוד JSON של FieldMask. אם מציינים את השם לזמן קצר, כמה שדות שונים מופרדים בפסיקים ושדות משנה מופרדים באמצעות נקודות. אפשר לציין שמות של שדות ב-camelCase או ב-פריד_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"
      }
    }
  ]
}