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

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