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

أقنعة الحقول هي طريقة لمستخدمي واجهة برمجة التطبيقات يمكنهم من خلالها إدراج الحقول التي يجب أن يعرضها الطلب أو يعدّلها. يسمح استخدام FieldMask لواجهة برمجة التطبيقات بتجنب العمل غير الضروري وتحسين الأداء. يتم استخدام قناع الحقل لكل من طريقتي القراءة والتحديث في واجهة برمجة تطبيقات Google Sheets.

القراءة باستخدام قناع الحقل

يمكن أن تكون جداول البيانات كبيرة، ولا تحتاج غالبًا إلى كل جزء من المرجع Spreadsheet الذي يعرضه طلب القراءة. يمكنك الحدّ من ما يتم عرضه في استجابة واجهة برمجة تطبيقات "جداول بيانات Google" باستخدام مَعلمة عنوان URL fields. لتحقيق أفضل أداء، أدرِج الحقول التي تحتاجها فقط في الرد.

يكون تنسيق مَعلمة الحقول هو نفسه ترميز JSON لـ FieldMask. تم توضيحها باختصار، يتم فصل العديد من الحقول المختلفة بفواصل والحقول الفرعية مفصولة بنقاط. يمكن تحديد أسماء الحقول باستخدام camelCase أو Separate_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
            }
          }
        }
      }
    }
  ]
}