Alan maskeleri kullanma

Alan maskeleri, API çağıranların bir isteğin döndürmesi veya güncellemesi gereken alanları listelemesinin bir yoludur. FieldMask kullanmak, API'nin gereksiz işlerden kaçınmasını sağlar ve performansı artırır. Alan maskesi, Google Slaytlar API'sindeki hem okuma hem de güncelleme yöntemleri için kullanılır.

Alan maskesi kullanmadığınızda ve kullandığınızda yanıt gövdesinde döndürülenlerin karşılaştırması için Kısmi kaynaklarla çalışma başlıklı makaleye bakın.

Alan maskesiyle okuma

Sunular büyük olabilir ve genellikle bir okuma isteği tarafından döndürülen presentations kaynağının her bölümüne ihtiyacınız olmaz. fields URL parametresini kullanarak Slides API yanıtında döndürülenleri sınırlayabilirsiniz. En iyi performans için yanıtta yalnızca ihtiyacınız olan alanları açıkça listeleyin.

Alanlar parametresinin biçimi, FieldMask'ın JSON kodlaması ile aynıdır. Kısaca belirtmek gerekirse, birden fazla farklı alan virgülle ayrılır ve alt alanlar nokta ile ayrılır. Alan adları camelCase veya separated_by_underscores olarak belirtilebilir. Kolaylık sağlamak amacıyla, aynı türden birden fazla alt alan parantez içinde listelenebilir.

Aşağıdaki presentations.get yöntem isteği örneğinde, yalnızca nesne kimliğini, slides.pageElements(objectId,size,transform), ve Size bir sunudaki tüm slaytlarda transform bir pageElement> nesnesini getirmek için alan maskesi kullanılır:

GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)

Bu yöntem çağrısına verilen yanıt, alan maskesinde istenen bileşenleri içeren bir presentations nesnesidir:

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

Alan maskesiyle güncelleme

Bazen bir nesnedeki yalnızca belirli alanları güncellemeniz, diğer alanları ise değiştirmemeniz gerekir. presentations.batchUpdate yöntemindeki güncelleme istekleri, hangi alanların değiştirildiğini API'ye bildirmek için alan maskelerini kullanır. Güncelleme isteği, alan maskesinde belirtilmeyen tüm alanları yoksayar ve bu alanları mevcut değerleriyle bırakır.

Güncellenen iletide belirtmeyerek ancak alanı maskeye ekleyerek de bir alanın ayarını kaldırabilirsiniz. Bu işlem, alanın daha önce sahip olduğu değeri temizler.

Güncelleme alan maskelerinin söz dizimi, okuma alan maskeleriyle aynıdır.

Aşağıdaki örnekte, şeklin renk dolgusunu DARK1 tema rengine değiştirmek ve şeklin ana hattını kaldırmak için UpdateShapePropertiesRequest yöntemi kullanılmaktadır:

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