أقنعة الحقول هي وسيلة يستخدمها المتصلون بواجهة برمجة التطبيقات لسرد الحقول التي يجب على الطلب الرجوع أو التحديث. استخدام FieldMask تسمح لواجهة برمجة التطبيقات بتجنب العمل غير الضروري وتحسين الأداء. قناع الحقل يُستخدم لكل من طريقتي القراءة والتحديث في Google Sheets API.
القراءة باستخدام قناع الحقل
يمكن أن تكون جداول البيانات كبيرة، وغالبًا لا تحتاج إلى كل جزء من
Spreadsheet
تم إرجاعه بواسطة طلب قراءة. يمكنك تحديد ما يتم إرجاعه في
استجابة من Google Sheets API، باستخدام معلَمة عنوان URL fields
. للأفضل
والأداء
إدراج الحقول التي تحتاجها فقط بشكل صريح
في الرد.
يكون تنسيق معلمة الحقول هو نفسه ترميز JSON لـ "قناع الحقل" وباختصار، يتم فصل عدة حقول مختلفة بفواصل ويتم فصل الحقول الفرعية بنقطة. يمكن تحديد أسماء الحقول بـ camelCase أو separated_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
:
{ "sheets": [ { "properties": { "sheetId":SHEET_ID
, "title": "TITLE
", "sheetType": "GRID", "gridProperties": { "rowCount": 1000, "columnCount": 25 } } }, { "properties": { "sheetId":SHEET_ID
, "title": "TITLE
", "sheetType": "OBJECT" } } ] }
التعديل باستخدام قناع حقل
تحتاج أحيانًا إلى تحديث حقول معينة فقط في الكائن مع ترك
الحقول الأخرى بدون تغيير. تعديل الطلبات داخل
spreadsheets.batchUpdate
استخدام أقنعة الحقول لإعلام واجهة برمجة التطبيقات بالحقول التي يتم تغييرها. تشير رسالة الأشكال البيانية
طلب التحديث يتجاهل أي حقول لم يتم تحديدها في قناع الحقل،
وتركها مع قيمها الحالية.
يمكنك أيضًا إلغاء ضبط حقل من خلال عدم تحديده في الرسالة المعدّلة، ولكن إضافة الحقل إلى القناع. يؤدي هذا إلى محو أي قيمة كان الحقل
بناء الجملة لأقنعة حقل التحديث هي نفس بنية أقنعة حقل القراءة.
يستخدم المثال التالي دالة
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 } } } } } ] }