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

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

קריאה עם מסכת שדה

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

הפורמט של הפרמטר fields זהה לקידוד JSON של FieldMask. אם מציינים את השם לזמן קצר, כמה שדות שונים מופרדים בפסיקים ושדות משנה מופרדים באמצעות נקודות. אפשר לציין את שמות השדות בפורמט camelCase או בפורמט separated_by_underscores. לנוחות, אפשר לציין כמה שדות משנה מאותו סוג בסוגריים.

בדוגמה הבאה לבקשה של documents.get נעשה שימוש במסכת שדה של title,tabs(documentTab(body.content(paragraph))),revisionId כדי לאחזר את title של המסמך, את Paragraph של אובייקט Body (מכל הכרטיסיות) ואת revisionId של המסמך בתוך המסמך:

GET https://docs.googleapis.com/v1/documents/documentId?fields=title,tabs(documentTab(body.content(paragraph))),revisionId

התגובה לקריאה של השיטה הזו היא אובייקט Document שמכיל את הרכיבים שביקשת במסכת השדה:

{
  "title": "TITLE",
  "revisionId": "REVISION_ID",
  "tabs": [
    {
      "documentTab": {
        "body": {
          "content": [
            {},
            {
              "paragraph": {
                "elements": [
                  {
                    "startIndex": 1,
                    "endIndex": 59,
                    "textRun": {
                      "content": "CONTENT",
                      "textStyle": {}
                    }
                  }
                ],
                "paragraphStyle": {
                  "namedStyleType": "NORMAL_TEXT",
                  "direction": "LEFT_TO_RIGHT"
                }
              }
            }
          ]
        }
      }
    }
  ]
}

עדכון באמצעות מסכת שדה

לפעמים צריך לעדכן רק שדות מסוימים באובייקט, בלי לשנות את השדות האחרים. בקשות עדכון בתוך פעולות ב-documents.batchUpdate משתמשות במסכות של שדות כדי לציין ל-API אילו שדות משתנים. בקשת העדכון מתעלמת משדות שלא צוינו במסכת השדות, ומשאירה אותם עם הערכים הנוכחיים שלהם.

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

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

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

הדוגמה הבאה משתמשת ב-UpdateTextStyleRequest כדי לעצב את המילים Google Docs API במסמך כמודגשות בטווח 5-20 של range:

POST https://docs.googleapis.com/v1/documents/documentId:batchUpdate

{
  "title": "TITLE",
  "revisionId": "REVISION_ID",
  "suggestionsViewMode": "SUGGESTIONS_INLINE",
  "documentId": "DOCUMENT_ID",
  "tabs": [
    {
      "documentTab": {
        "body": {
          "content": [
            {
              "endIndex": 1,
              "sectionBreak": {
                "sectionStyle": {
                  "columnSeparatorStyle": "NONE",
                  "contentDirection": "LEFT_TO_RIGHT",
                  "sectionType": "CONTINUOUS"
                }
              }
            },
            {
              "startIndex": 1,
              "endIndex": 59,
              "paragraph": {
                "elements": [
                  {
                    "startIndex": 1,
                    "endIndex": 5,
                    "textRun": {
                      "content": "CONTENT",
                      "textStyle": {}
                    }
                  },
                  {
                    "startIndex": 5,
                    "endIndex": 20,
                    "textRun": {
                      "content": "CONTENT",
                      "textStyle": {
                        "bold": true
                      }
                    }
                  },
                  {
                    "startIndex": 20,
                    "endIndex": 59,
                    "textRun": {
                      "content": "CONTENT",
                      "textStyle": {}
                    }
                  }
                ],
                "paragraphStyle": {
                  "namedStyleType": "NORMAL_TEXT",
                  "direction": "LEFT_TO_RIGHT"
                }
              }
            }
          ]
        },
        {
          ... // style details
        },
      }
    }
  ],
}