استخدام أقنعة الحقول

أقنعة الحقول هي وسيلة يستخدمها المتصلون بواجهة برمجة التطبيقات لسرد الحقول التي يجب على الطلب الرجوع أو التحديث. استخدام 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
            }
          }
        }
      }
    }
  ]
}