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. Google Dokümanlar API'sindeki hem okuma hem de güncelleme yöntemleri için alan maskesi kullanılır.
Alan maskesiyle okuma
Dokümanlar büyük olabilir ve genellikle okuma isteğiyle döndürülen Document kaynağın her bölümüne ihtiyacınız olmaz. fields URL parametresini kullanarak Docs 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 documents.get istek örneğinde, dokümanın title, Body nesnesinin (tüm sekmelerden) Paragraph ve dokümandaki revisionId değerini getirmek için title,tabs(documentTab(body.content(paragraph))),revisionId alan maskesi kullanılmaktadır:
GET https://docs.googleapis.com/v1/documents/documentId?fields=title,tabs(documentTab(body.content(paragraph))),revisionId
Bu yöntem çağrısına verilen yanıt, alan maskesinde istenen bileşenleri içeren bir Document nesnesidir:
{
"title": "TITLE",
"revisionId": "REVISION_ID",
"tabs": [
{
"documentTab": {
"body": {
"content": [
{},
{
"paragraph": {
"elements": [
{
"startIndex": 1,
"endIndex": 59,
"textRun": {
"content": "CONTENT",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
}
]
}
}
}
]
}Alan maskesiyle güncelleme
Bazen bir nesnedeki yalnızca belirli alanları güncellemeniz, diğer alanları ise değiştirmemeniz gerekir. documents.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 alanları yok sayarak 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, UpdateTextStyleRequest kullanılarak range 5-20 içindeki "Google Dokümanlar API'si" kelimeleri kalın olarak biçimlendiriliyor:
POST https://docs.googleapis.com/v1/documents/documentId:batchUpdate
{
"title": "TITLE",
"revisionId": "REVISION_ID",
"suggestionsViewMode": "SUGGESTIONS_INLINE",
"documentId": "DOCUMENT_ID",
"tabs": [
{
"documentTab": {
"body": {
"content": [
{
"endIndex": 1,
"sectionBreak": {
"sectionStyle": {
"columnSeparatorStyle": "NONE",
"contentDirection": "LEFT_TO_RIGHT",
"sectionType": "CONTINUOUS"
}
}
},
{
"startIndex": 1,
"endIndex": 59,
"paragraph": {
"elements": [
{
"startIndex": 1,
"endIndex": 5,
"textRun": {
"content": "CONTENT",
"textStyle": {}
}
},
{
"startIndex": 5,
"endIndex": 20,
"textRun": {
"content": "CONTENT",
"textStyle": {
"bold": true
}
}
},
{
"startIndex": 20,
"endIndex": 59,
"textRun": {
"content": "CONTENT",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
}
]
},
{
... // style details
},
}
}
],
}