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

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

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

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

ההתייחסות למסכת שדות של * תהיה כמו תו כללי לחיפוש, והיא משמשת כקיצור לציון כל שדה בהודעה. התחביר של התווים הכלליים לחיפוש יכול להפיק תוצאות לא רצויות אם ה-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"
      }
    }
  ]
}