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

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

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

يمكن أن تكون جداول البيانات كبيرة، وغالبًا ما لا تحتاج إلى كل جزء من Spreadsheet المورد الذي يعرضه طلب القراءة. يمكنك الحد من البيانات التي يتم عرضها في استجابة واجهة برمجة التطبيقات Sheets API، وذلك باستخدام مَعلمة عنوان URL 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
            }
          }
        }
      }
    }
  ]
}