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

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