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

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

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

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

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"
      }
    }
  ]
}