Alan maskeleri, API çağırıcılarının bir isteğin döndürmesi veya güncellemesi gereken alanları listelemesi için kullanılan bir yöntemdir. FieldMask kullanmak, API'nin gereksiz çalışmalardan kaçınmasına olanak tanır ve performansı artırır. Alan maskesi, Google Docs API'deki hem okuma hem de güncelleme yöntemleri için kullanılır.
Alan maskesi ile okuma
Dokümanlar büyük olabilir ve genellikle bir okuma isteğiyle döndürülen Document kaynağının her bölümüne ihtiyacınız yoktur. fields URL parametresini kullanarak Dokümanlar API yanıtında döndürülen içeriği 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 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 documents.get istek örneğinde, bir belgenin title, Body nesnesinin Paragraph (tüm sekmelerden) ve bir belgedeki revisionId alanını 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ının 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üncelle
Bazen bir nesnedeki belirli alanları güncellerken diğer alanları değiştirmeden bırakmanız 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 tüm alanları yok sayarak geçerli değerlerinde kalır.
Bir alanın değerini, güncellenen mesajda belirtmeyerek ancak 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, dokümanda "Google Dokümanlar API" kelimelerinin stilini range 5-20 arasında kalın olarak ayarlamak için UpdateTextStyleRequest kullanılmaktadır:
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
},
}
}
],
}