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

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

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

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

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