Alan maskeleri kullanma

Alan maskeleri, API çağırıcılarının bir isteğin döndürmesi veya güncellemesi gereken alanları listelemesi için bir yoldur. FieldMask kullanmak, API'nin gereksiz çalışmalardan kaçınmasına olanak tanır ve performansı artırır. Alan maskesi, Google Dokümanlar API'sindeki 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 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.

fields parametresinin biçimi, FieldMask'in JSON kodlamasıyla aynıdır. Kısaca belirtmek gerekirse, birden fazla farklı alan virgülle, alt alanlar ise 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 maskesi ile güncelleme

Bazen bir nesnenin yalnızca belirli alanlarını güncellemeniz, diğer alanları ise değiştirmemeniz gerekir. documents.batchUpdate işlemi içindeki güncelleme isteklerinde, API'ye hangi alanların değiştirildiğini bildirmek için alan maskeleri kullanılır. Güncelleme isteği, alan maskesinde belirtilmeyen alanları yoksayıp mevcut değerlerinde bırakı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
        },
      }
    }
  ],
}