از ماسک های میدانی استفاده کنید، از ماسک های میدانی استفاده کنید

ماسک‌های فیلد راهی برای فراخوانی‌کنندگان API هستند تا فیلدهایی را که یک درخواست باید برگرداند یا به‌روزرسانی کند، فهرست کنند. استفاده از ماسک فیلد به API اجازه می‌دهد تا از کار غیرضروری جلوگیری کند و عملکرد را بهبود بخشد. ماسک فیلد برای هر دو روش خواندن و به‌روزرسانی در API Google Docs استفاده می‌شود.

با ماسک صحرایی بخوانید

اسناد می‌توانند بزرگ باشند، و اغلب شما به هر بخش از منبع Document که توسط یک درخواست خواندن برگردانده می‌شود، نیاز ندارید. می‌توانید با استفاده از پارامتر URL fields ، آنچه را که در پاسخ API Docs برگردانده می‌شود، محدود کنید. برای بهترین عملکرد، به صراحت فقط فیلدهایی را که در پاسخ نیاز دارید فهرست کنید .

قالب پارامتر fields مشابه کدگذاری JSON یک FieldMask است. به طور خلاصه، چندین فیلد مختلف با کاما از هم جدا می‌شوند و زیرفیلدها با نقطه از هم جدا می‌شوند. نام فیلدها را می‌توان با camelCase یا separate_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 است که شامل اجزای درخواست شده در فیلد mask می‌باشد:

{
  "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 ۵ تا ۲۰ استفاده می‌کند:

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