این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

برای مقایسه مواردی که در بدنه پاسخ پس از استفاده از ماسک فیلد در مقابل زمانی که استفاده نمی کنید، به کار با منابع جزئی مراجعه کنید.

با ماسک میدانی بخوانید

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

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

{
  "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 بگوید کدام فیلدها در حال تغییر هستند. درخواست به‌روزرسانی، فیلدی‌هایی را که در فیلد ماسک مشخص نشده‌اند نادیده می‌گیرد و مقادیر فعلی‌شان را باقی می‌گذارد.

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

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

ماسک فیلد * مانند یک علامت عام رفتار می شود و برای مشخص کردن هر فیلد در یک پیام کوتاه است. اگر API در آینده به‌روزرسانی شود، دستور عام می‌تواند نتایج ناخواسته‌ای ایجاد کند، زیرا فیلدهای فقط خواندنی و فیلدهای تازه اضافه شده ممکن است باعث خطا شوند. برای برنامه های تولید، همیشه فیلدهای خاصی را که به روز می شوند در ماسک های فیلد فهرست کنید و از استفاده از علامت * خودداری کنید.

مثال زیر از متد UpdateShapePropertiesRequest برای تغییر پر رنگ شکل به رنگ تم 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"
      }
    }
  ]
}

با ماسک میدانی بخوانید

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

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

{
  "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"
          }
        }
     ]
    }
  ]
}

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

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

مثال زیر از متد UpdateShapePropertiesRequest برای تغییر پر رنگ شکل به رنگ تم 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"
      }
    }
  ]
}

با ماسک میدانی بخوانید

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

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

{
  "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"
          }
        }
     ]
    }
  ]
}

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

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

مثال زیر از متد UpdateShapePropertiesRequest برای تغییر پر رنگ شکل به رنگ تم 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"
      }
    }
  ]
}

با ماسک میدانی بخوانید

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

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

{
  "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"
          }
        }
     ]
    }
  ]
}

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

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

مثال زیر از متد UpdateShapePropertiesRequest برای تغییر پر رنگ شکل به رنگ تم 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"
      }
    }
  ]
}