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

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

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

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

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

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

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

בדוגמה הבאה נעשה שימוש ב-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
        },
      }
    }
  ],
}