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

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

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

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

يكون تنسيق مَعلمة الحقول هو نفسه ترميز JSON لحقل FieldMask. بعبارة موجزة، يتم فصل الحقول المختلفة المتعددة بفواصل، ويتم فصل الحقول الفرعية بنقاط. يمكن تحديد أسماء الحقول بالتنسيق camelCase أو separated_by_underscores. لتسهيل الأمر، يمكن إدراج حقول فرعية متعددة من النوع نفسه بين قوسين.

يستخدم مثال طلب presentations.get التالي قناع حقل slides.pageElements(objectId,size,transform) لجلب رقم تعريف العنصر Size و التحويل للكائن pageElement في جميع الشرائح في عرض تقديمي:

GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)

الاستجابة لاستدعاء هذه الطريقة هي كائن Presentation يحتوي على المكوّنات المطلوبة في قناع الحقل:

{
  "slides": [
    {
      "pageElements": [
        {
          "objectId": "OBJECT_ID",
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1
            "translateX": 311708,
            "translateY": 744575,
            "unit": "EMU"
          }
        },
        {
          "objectId": "OBJECT_ID",
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1
            "translateX": 311700,
            "translateY": 2834125,
            "unit": "EMU"
          }
        }
     ]
    }
  ]
}

تعديل باستخدام قناع حقل

في بعض الأحيان، تحتاج إلى تعديل حقول معيّنة فقط في عنصر مع ترك الحقول الأخرى بدون تغيير. تستخدم طلبات التعديل ضمن عملية presentations.batchUpdate أقنعة الحقول لإعلام واجهة برمجة التطبيقات بالحقول التي يتم تغييرها. يتجاهل طلب التعدُّل أي حقول غير محدّدة في قناع الحقول، ويتركها مع قيمها الحالية.

يمكنك أيضًا إلغاء ضبط حقل عن طريق عدم تحديده في الرسالة المعدَّلة، ولكن بإضافة الحقل إلى القناع. يؤدي ذلك إلى محو أي قيمة كان الحقل يحتوي عليها سابقًا.

تكون بنية أقنعة حقول التعديل مماثلة لبنية أقنعة حقول القراءة.

يُعامل قناع الحقل * كعنصر نائب وهو اختصار لتحديد كل حقل في رسالة. يمكن أن تؤدي بنية العنصر النائب إلى ظهور نتائج غير مرغوب فيها في حال تم تحديث واجهة برمجة التطبيقات في المستقبل، لأنّ الحقول التي يمكن قراءتها فقط والحقول التي تمت إضافتها حديثًا قد تؤدي إلى حدوث أخطاء. بالنسبة إلى التطبيقات العلنية، احرص دائمًا على إدراج الحقول المحدّدة التي يتم تعديلها في أقنعة الحقول وتجنَّب استخدام * العناصر النائبة.

يستخدم المثال التالي الرمز UpdateShapePropertiesRequest لتغيير لون تعبئة شكل إلى لون المظهر DARK1 وإلغاء ضبط ملفه الشخصي:

POST https://slides.googleapis.com/v1/presentations/presentationId:batchUpdate

{
  "requests": [
    {
      "updateShapeProperties": {
        "objectId": OBJECT_ID,
        "shapeProperties": {
          "shapeBackgroundFill": {
            "solidFill": {
              "color": {
                "themeColor": "DARK1"
              }
            }
          }
        },
        "fields": "shapeBackgroundFill.solidFill.color,outline"
      }
    }
  ]
}