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