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

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

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

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

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