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

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