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

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

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

يمكن أن تكون العروض التقديمية كبيرة، وغالبًا لا تحتاج إلى كل جزء من Presentation تم إرجاعه بواسطة طلب قراءة. يمكنك تحديد ما يتم إرجاعه في استجابة من واجهة برمجة التطبيقات في "العروض التقديمية من Google"، باستخدام معلمة عنوان URL fields. للأفضل والأداء إدراج الحقول التي تحتاجها فقط بشكل صريح في الرد.

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

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

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