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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
  "title": "TITLE",
  "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
   },
  "revisionId": "REVISION_ID",
  "suggestionsViewMode": "SUGGESTIONS_INLINE",
  "documentId": "DOCUMENT_ID"
}