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

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

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

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

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

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

الاستجابة لاستدعاء هذه الطريقة هي كائن 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"
      }
    }
  ]
}