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

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

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

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

يكون تنسيق المَعلمة fields مطابقًا لترميز JSON لحقل FieldMask. بعبارة موجزة، يتم فصل الحقول المختلفة المتعددة بفواصل، ويتم فصل الحقول الفرعية بنقاط. يمكن تحديد أسماء الحقول بالتنسيق camelCase أو separated_by_underscores. لتسهيل الأمر، يمكن إدراج حقول فرعية متعددة من النوع نفسه بين قوسين.

في المثال التالي spreadsheets.get لطلب ، يتم استخدام قناع حقل sheets.properties(sheetId,title,sheetType,gridProperties) ل retrieving فقط معرّف الورقة والعنوان 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
            }
          }
        }
      }
    }
  ]
}