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

تتيح أقنعة الحقول لمستخدمي واجهة برمجة التطبيقات إدراج الحقول التي يجب أن يعرضها الطلب أو يعدّلها. يسمح استخدام 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"
      }
    }
  ]
}