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

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

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

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

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

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

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

.

בדוגמה הבאה נשתמש ב-UpdateTextStyleRequest כדי להגדיר את המילים Google Docs API במסמך כמודגשות בתוך range 5–20:

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