Alan maskeleri, API arayanlarını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. Alan maskesi, Google Docs API'nin hem okuma hem de güncelleme yöntemleri için kullanılır.
Alan maskesiyle okuma
Belgeler büyük olabilir ve genellikle okuma isteği tarafından döndürülen Document kaynağının tüm bölümlerine ihtiyacınız yoktur. fields URL parametresini kullanarak Dokümanlar API'sı yanıtında döndürülecekleri sınırlayabilirsiniz. En iyi performans için yanıtta yalnızca ihtiyacınız olan alanları açıkça listeleyin.
Domains parametresinin biçimi, FieldMask'in JSON kodlamasıyla aynıdır. Özetle, birden fazla farklı alan virgülle ve alt alanlar ise noktalarla ayrılır. Alan adları, camelCase veya sold_by_underscores ile belirtilebilir. Kolaylık sağlaması açısından, aynı türden birden fazla alt alan parantez içinde listelenebilir.
Aşağıdaki documents.get istek örneğinde belgenin title, bir Body nesnesinin Paragraph ve doküman içindeki revisionId öğesi için title,body.content(paragraph),revisionId alan maskesi kullanılmaktadır:
GET https://docs.googleapis.com/v1/documents/documentId?fields=title,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",
"body": {
"content": [
{},
{
"paragraph": {
"elements": [
{
"startIndex": 1,
"endIndex": 59,
"textRun": {
"content": ""CONTENT",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
}
]
},
"revisionId": "REVISION_ID"
}
Alan maskesiyle güncelle
Bazen bir nesnedeki yalnızca belirli alanları güncellemeniz gerekir. Diğer alanları ise değiştirmeden bırakırsınız. Bir documents.batchUpdate işlemi içindeki güncelleme istekleri, API'ye hangi alanların değiştirildiğini bildirmek için alan maskelerini kullanır. Güncelleme isteği, alan maskesinde belirtilmeyen tüm alanları yok sayar ve mevcut değerleriyle kalır.
Bir alanı, güncellenen mesajda belirtmeden alanı maskeye ekleyerek de ayarı kaldırabilirsiniz. Bu, alanın önceden sahip olduğu değeri temizler.
Güncelleme alan maskelerinin söz dizimi, okunan alan maskeleriyle aynıdır.
Aşağıdaki örnekte, belgedeki "Google Docs API" kelimelerinin range 5–20 içinde kalın harflerle biçimlendirilmesi için UpdateTextStyleRequest kullanılmıştır:
POST https://docs.googleapis.com/v1/documents/documentId:batchUpdate
{
"title": "TITLE",
"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
},
"revisionId": "REVISION_ID",
"suggestionsViewMode": "SUGGESTIONS_INLINE",
"documentId": "DOCUMENT_ID"
}