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

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