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

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

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

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

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