از ماسک های میدانی استفاده کنید، از ماسک های میدانی استفاده کنید
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
فیلد ماسک راهی برای تماس‌گیرندگان API برای فهرست کردن فیلدهایی است که درخواست باید برگرداند یا به‌روزرسانی کند. استفاده از FieldMask به API اجازه می دهد تا از کارهای غیر ضروری جلوگیری کند و عملکرد را بهبود بخشد. یک فیلد ماسک برای هر دو روش خواندن و به‌روزرسانی در Google Sheets API استفاده می‌شود.
با ماسک میدانی بخوانید
صفحه‌گسترده‌ها می‌توانند بزرگ باشند، و اغلب شما نیازی ندارید که همه بخش‌های منبع Spreadsheet با درخواست خواندن بازگردانده شود. می‌توانید با استفاده از پارامتر URL fields ، آنچه را که در پاسخ Sheets API بازگردانده می‌شود، محدود کنید. برای بهترین عملکرد، فقط فیلدهایی را که در پاسخ نیاز دارید به صراحت فهرست کنید .
فرمت پارامتر فیلدها مانند رمزگذاری JSON یک FieldMask است. به طور خلاصه، چندین فیلد مختلف با کاما و زیر فیلدها با نقطه جدا می شوند. نام فیلدها را می توان در camelCase یا جداگانه_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 حاوی اجزای درخواست شده در فیلد ماسک است. توجه داشته باشید که sheetType=OBJECT حاوی gridProperties نیست:
گاهی اوقات شما نیاز دارید که فقط فیلدهای خاصی را در یک شی به روز کنید در حالی که فیلدهای دیگر را بدون تغییر رها کنید. درخواست‌های به‌روزرسانی در یک عملیات spreadsheets.batchUpdate از ماسک‌های فیلد استفاده می‌کند تا به API بگوید کدام فیلدها در حال تغییر هستند. درخواست به‌روزرسانی، فیلدی‌هایی را که در فیلد ماسک مشخص نشده‌اند نادیده می‌گیرد و مقادیر فعلی‌شان را باقی می‌گذارد.
همچنین می‌توانید یک فیلد را با مشخص نکردن آن در پیام به‌روزرسانی شده، اما افزودن فیلد به ماسک، لغو تنظیم کنید. این هر مقداری را که فیلد قبلاً داشته است پاک می کند.
سینتکس ماسک های فیلد به روز رسانی مانند ماسک های فیلد خواندنی است.
مثال زیر از AddSheetRequest برای اضافه کردن یک برگه جدید از نوع Grid ، ثابت کردن ردیف اول و رنگ قرمز برگه برگه جدید استفاده می کند:
POST https://sheets.googleapis.com/v1/spreadsheets/spreadsheetId:batchUpdate
تاریخ آخرین به‌روزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین به‌روزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی."],[],[],null,["# Use field masks\n\nField masks are a way for API callers to list the fields that a request should\nreturn or update. Using a\n[FieldMask](https://protobuf.dev/reference/protobuf/google.protobuf/#field-mask)\nallows the API to avoid unnecessary work and improves performance. A field mask\nis used for both the read and update methods in the Google Sheets API.\n\nRead with a field mask\n----------------------\n\nSpreadsheets can be large, and often you don't need every part of the\n[`Spreadsheet`](/workspace/sheets/api/reference/rest/v4/spreadsheets#resource:-spreadsheet)\nresource returned by a read request. You can limit what's returned in a\nSheets API response, using the `fields` URL parameter. For best\nperformance, [explicitly list only the fields you\nneed](/workspace/sheets/api/guides/performance#partial-response) in the reply.\n\nThe format of the fields parameter is the same as the [JSON encoding of a\nFieldMask](https://protobuf.dev/reference/protobuf/google.protobuf/#json-encoding-field-masks).\nStated briefly, multiple different fields are comma-separated and subfields are\ndot-separated. Field names can be specified in **camelCase** or\n**separated_by_underscores**. For convenience, multiple subfields from the same\ntype can be listed within parentheses.\n\nThe following\n[`spreadsheets.get`](/workspace/sheets/api/reference/rest/v4/spreadsheets/get)\nrequest example uses a field mask of\n`sheets.properties(sheetId,title,sheetType,gridProperties)` to fetch only the\nsheet ID, title,\n[`SheetType`](/workspace/sheets/api/reference/rest/v4/spreadsheets/sheets#SheetType),\nand\n[`GridProperties`](/workspace/sheets/api/reference/rest/v4/spreadsheets/sheets#GridProperties)\nof a\n[`SheetProperties`](/workspace/sheets/api/reference/rest/v4/spreadsheets/sheets#SheetProperties)\nobject on all sheets in a spreadsheet: \n\n```\nGET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties(sheetId,title,sheetType,gridProperties)\n```\n\nThe response to this method call is a\n[`Spreadsheet`](/workspace/sheets/api/reference/rest/v4/spreadsheets#resource:-spreadsheet)\nobject containing the components requested in the field mask. Note that\n`sheetType=OBJECT` doesn't contain `gridProperties`: \n\n {\n \"sheets\": [\n {\n \"properties\": {\n \"sheetId\": \u003cvar translate=\"no\"\u003eSHEET_ID\u003c/var\u003e,\n \"title\": \"\u003cvar translate=\"no\"\u003eTITLE\u003c/var\u003e\",\n \"sheetType\": \"GRID\",\n \"gridProperties\": {\n \"rowCount\": 1000,\n \"columnCount\": 25\n }\n }\n },\n {\n \"properties\": {\n \"sheetId\": \u003cvar translate=\"no\"\u003eSHEET_ID\u003c/var\u003e,\n \"title\": \"\u003cvar translate=\"no\"\u003eTITLE\u003c/var\u003e\",\n \"sheetType\": \"OBJECT\"\n }\n }\n ]\n }\n\nUpdate with a field mask\n------------------------\n\nSometimes you need to update only certain fields in an object while leaving the\nother fields unchanged. Update requests inside a\n[`spreadsheets.batchUpdate`](/workspace/sheets/api/reference/rest/v4/spreadsheets/batchUpdate)\noperation use field masks to tell the API which fields are being changed. The\nupdate request ignores any fields that aren't specified in the field mask,\nleaving them with their current values.\n\nYou can also unset a field by not specifying it in the updated message, but\nadding the field to the mask. This clears whatever value the field previously\nhad.\n\nThe syntax for update field masks is the same as read field masks.\n| A field mask of `*` is treated like a wildcard and is shorthand for specifying every field in a message. The wildcard syntax can produce unwanted results if the API is updated in the future, as read-only fields and newly added fields may cause errors. For production applications, always list the specific fields being updated in field masks and avoid using `*` wildcards.\n\nThe following example uses the\n[`AddSheetRequest`](/workspace/sheets/api/reference/rest/v4/spreadsheets/request#addsheetrequest)\nto add a new sheet of type `Grid`, freeze the first row, and color the new\nsheet's tab red: \n\n```\nPOST https://sheets.googleapis.com/v1/spreadsheets/spreadsheetId:batchUpdate\n``` \n\n {\n \"spreadsheetId\": \"\u003cvar translate=\"no\"\u003eSPREADSHEET_ID\u003c/var\u003e\",\n \"replies\": [\n {\n \"addSheet\": {\n \"properties\": {\n \"sheetId\": \u003cvar translate=\"no\"\u003eSHEET_ID\u003c/var\u003e,\n \"title\": \"\u003cvar translate=\"no\"\u003eTITLE\u003c/var\u003e\",\n \"index\": 6,\n \"sheetType\": \"GRID\",\n \"gridProperties\": {\n \"rowCount\": 1000,\n \"columnCount\": 26,\n \"frozenRowCount\": 1\n },\n \"tabColor\": {\n \"red\": 0.003921569\n },\n \"tabColorStyle\": {\n \"rgbColor\": {\n \"red\": 0.003921569\n }\n }\n }\n }\n }\n ]\n }"]]
