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

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

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

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

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

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