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

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

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

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

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