Alan maskeleri, API çağrılarının bir isteğin döndürmesi veya güncellenmesi gereken alanları listelemesi için kullanılan bir yöntemdir. FieldMask kullanılması, API'nin gereksiz işlerden kaçınmasını sağlar ve performansı artırır. Alan maskesi, Google Slaytlar API'deki hem okuma hem de güncelleme yöntemleri için kullanılır.
Alan maskesiyle oku
Sunular büyük olabilir ve genellikle bir okuma isteği tarafından döndürülen Presentation kaynağının her bölümüne ihtiyacınız olmaz. fields URL parametresini kullanarak Slaytlar API yanıtında döndürülen içeriği sınırlandırabilirsiniz. En iyi performans için yanıtta yalnızca ihtiyacınız olan alanları açıkça listeleyin.
Alanlar parametresinin biçimi, FieldMask'in JSON kodlamasıyla aynıdır. Kısaca belirtmek gerekirse birden fazla farklı alan virgülle, alt alanlar noktayla ayrılır. Alan adları, camelCase veya individual_by_underscores ile belirtilebilir. Kolaylık sağlaması açısından, aynı türde birden çok alt alan parantez içinde listelenebilir.
Aşağıdaki presentations.get istek örneğinde, sunudaki tüm slaytlardaki bir pageElement nesnesinin yalnızca nesne kimliğini (Size) ve dönüştürme
öğesini getirmek 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 nesnesi olur:
{
"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üncelle
Bazen bir nesnedeki belirli alanları güncellerken diğer alanları değiştirmeden bırakmanız gerekir. presentations.batchUpdate işlemi içindeki 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ı yok sayarak geçerli değerlerinde kalır.
Bir alanı, güncellenen iletide belirtmeyip maskeye ekleyerek de kaldırabilirsiniz. Bu sayede, ilgili alanın önceden sahip olduğu değer temizlenir.
Güncelleme alanı maskelerinin söz dizimi, okuma alanı maskeleriyle aynıdır.
Aşağıdaki örnekte, bir şeklin renk dolgusunu DARK1 tema rengiyle değiştirmek ve şeklin dış çizgisini kaldırmak için UpdateShapePropertiesRequest simgesi 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"
}
}
]
}