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

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

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

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

يكون تنسيق المَعلمة 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"
      }
    }
  ]
}