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

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

برای مقایسه آنچه در بدنه پاسخ، زمانی که از ماسک فیلد استفاده نمی‌کنید و زمانی که از آن استفاده می‌کنید، بازگردانده می‌شود، به بخش «کار با منابع جزئی» مراجعه کنید.

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

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

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

مثال درخواست متد presentations.get زیر از یک ماسک فیلد به نام slides.pageElements(objectId,size,transform) برای دریافت فقط شناسه شیء، Size و تبدیل یک شیء pageElement در تمام اسلایدهای یک ارائه استفاده می‌کند:

GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)

پاسخ به این فراخوانی متد، یک شیء presentations است که شامل اجزای درخواست شده در فیلد mask می‌باشد:

{
  "slides": [
    {
      "pageElements": [
        {
          "objectId": "OBJECT_ID",
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1
            "translateX": 311708,
            "translateY": 744575,
            "unit": "EMU"
          }
        },
        {
          "objectId": "OBJECT_ID",
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1
            "translateX": 311700,
            "translateY": 2834125,
            "unit": "EMU"
          }
        }
     ]
    }
  ]
}

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

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

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

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

مثال زیر از متد UpdateShapePropertiesRequest برای تغییر رنگ fill یک شکل به رنگ تم DARK1 و غیرفعال کردن خطوط بیرونی شکل استفاده می‌کند:

POST https://slides.googleapis.com/v1/presentations/presentationId:batchUpdate

{
  "requests": [
    {
      "updateShapeProperties": {
        "objectId": OBJECT_ID,
        "shapeProperties": {
          "shapeBackgroundFill": {
            "solidFill": {
              "color": {
                "themeColor": "DARK1"
              }
            }
          }
        },
        "fields": "shapeBackgroundFill.solidFill.color,outline"
      }
    }
  ]
}