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

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

لإجراء مقارنة بين ما يتم عرضه في نص الاستجابة عند عدم استخدام قناع حقل وعند استخدامه، يُرجى الاطّلاع على مقالة استخدام الموارد الجزئية.

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

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

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

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

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

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

{
  "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"
      }
    }
  ]
}