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

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

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

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

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