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

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

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

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

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