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

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

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

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

قالب پارامتر fields مشابه کدگذاری JSON یک FieldMask است. به طور خلاصه، چندین فیلد مختلف با کاما از هم جدا می‌شوند و زیرفیلدها با نقطه از هم جدا می‌شوند. نام فیلدها را می‌توان با camelCase یا separate_by_underscores مشخص کرد. برای راحتی، می‌توان چندین زیرفیلد از یک نوع را درون پرانتز فهرست کرد.

مثال درخواست spreadsheets.get زیر از یک ماسک فیلد sheets.properties(sheetId,title,sheetType,gridProperties) برای دریافت فقط شناسه برگه، عنوان، SheetType و GridProperties از یک شیء SheetProperties در تمام برگه‌های یک صفحه گسترده استفاده می‌کند:

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties(sheetId,title,sheetType,gridProperties)

پاسخ به این فراخوانی متد، یک شیء Spreadsheet است که شامل اجزای درخواست شده در field mask می‌باشد. توجه داشته باشید که sheetType=OBJECT شامل gridProperties نمی‌شود:

{
  "sheets": [
    {
      "properties": {
        "sheetId": SHEET_ID,
        "title": "TITLE",
        "sheetType": "GRID",
        "gridProperties": {
          "rowCount": 1000,
          "columnCount": 25
        }
      }
    },
    {
      "properties": {
        "sheetId": SHEET_ID,
        "title": "TITLE",
        "sheetType": "OBJECT"
      }
    }
  ]
}

به‌روزرسانی با ماسک میدانی

گاهی اوقات نیاز دارید که فقط فیلدهای خاصی را در یک شیء به‌روزرسانی کنید و سایر فیلدها را بدون تغییر باقی بگذارید. درخواست‌های به‌روزرسانی درون عملیات spreadsheets.batchUpdate از ماسک‌های فیلد برای اطلاع‌رسانی به API در مورد فیلدهایی که تغییر می‌کنند، استفاده می‌کنند. درخواست به‌روزرسانی، فیلدهایی را که در ماسک فیلد مشخص نشده‌اند، نادیده می‌گیرد و مقادیر فعلی آنها را باقی می‌گذارد.

همچنین می‌توانید با مشخص نکردن فیلد در پیام به‌روزرسانی‌شده، و اضافه کردن آن به ماسک، مقدار آن را از مقدار اولیه خارج کنید. این کار هر مقداری را که فیلد قبلاً داشته است، پاک می‌کند.

سینتکس مربوط به ماسک‌های فیلد به‌روزرسانی مشابه ماسک‌های فیلد خواندن است.

مثال زیر از AddSheetRequest برای اضافه کردن یک برگه جدید از نوع Grid ، ثابت کردن ردیف اول و رنگ قرمز به تب برگه جدید استفاده می‌کند:

POST https://sheets.googleapis.com/v1/spreadsheets/spreadsheetId:batchUpdate

{
  "spreadsheetId": "SPREADSHEET_ID",
  "replies": [
    {
      "addSheet": {
        "properties": {
          "sheetId": SHEET_ID,
          "title": "TITLE",
          "index": 6,
          "sheetType": "GRID",
          "gridProperties": {
            "rowCount": 1000,
            "columnCount": 26,
            "frozenRowCount": 1
          },
          "tabColor": {
            "red": 0.003921569
          },
          "tabColorStyle": {
            "rgbColor": {
              "red": 0.003921569
            }
          }
        }
      }
    }
  ]
}