Alan maskeleri, API çağırıcılarının bir isteğin döndürmesi veya güncellemesi gereken alanları listelemesi için bir yoldur. FieldMask kullanmak, API'nin gereksiz çalışmalardan kaçınmasına olanak tanır 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 ile okuma
Sunular büyük olabilir ve genellikle bir okuma isteğiyle döndürülen Presentation kaynağının her bölümüne ihtiyacınız yoktur. fields URL parametresini kullanarak, Slaytlar 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.
fields parametresinin biçimi, FieldMask'in JSON kodlamasıyla aynıdır. Kısaca belirtmek gerekirse, birden fazla farklı alan virgülle, alt alanlar ise noktayla 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 istek örneğinde, bir pageElement nesnesinin yalnızca nesne kimliğini (Size) ve dönüşümünü almak için slides.pageElements(objectId,size,transform) alan maskesi kullanılmaktadır:
GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)
Bu yöntem çağrısının yanıtı, alan maskesinde istenen bileşenleri içeren bir Presentation 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 maskesi ile güncelleme
Bazen bir nesnenin yalnızca belirli alanlarını güncellemeniz, diğer alanları ise değiştirmemeniz gerekir. presentations.batchUpdate işlemi içindeki güncelleme isteklerinde, API'ye hangi alanların değiştirildiğini bildirmek için alan maskeleri kullanılır. Güncelleme isteği, alan maskesinde belirtilmeyen alanları yoksayıp mevcut değerlerinde bırakır.
Bir alanın değerini, güncellenen mesajda belirtmeyerek ancak alana maskeye ekleyerek de 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.
kullanmaktan kaçının.Aşağıdaki örnekte, bir şeklin renk doluluğunu DARK1 tema rengine değiştirmek ve şeklin dış çizgisini kaldırmak için UpdateShapePropertiesRequest 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"
}
}
]
}