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 E-Tablolar API'sindeki hem okuma hem de güncelleme yöntemleri için kullanılır.
Alan maskesi ile okuma
E-tablolar büyük olabilir ve genellikle bir okuma isteğiyle döndürülen Spreadsheet kaynakta her parçaya ihtiyacınız yoktur. fields URL parametresini kullanarak E-Tablolar 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 spreadsheets.get istek örneğinde, bir e-tablodaki tüm sayfalardaki SheetProperties öğesinin yalnızca sayfa kimliğini, başlığını, SheetType ve GridProperties alanını getirmek için sheets.properties(sheetId,title,sheetType,gridProperties) alan maskesi kullanılmaktadır:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties(sheetId,title,sheetType,gridProperties)
Bu yöntem çağrısının yanıtı, alan maskesinde istenen bileşenleri içeren bir Spreadsheet nesnesi olur. sheetType=OBJECT, gridProperties değerini içermez:
{
"sheets": [
{
"properties": {
"sheetId": SHEET_ID,
"title": "TITLE",
"sheetType": "GRID",
"gridProperties": {
"rowCount": 1000,
"columnCount": 25
}
}
},
{
"properties": {
"sheetId": SHEET_ID,
"title": "TITLE",
"sheetType": "OBJECT"
}
}
]
}
Alan maskesi ile güncelleme
Bazen bir nesnenin yalnızca belirli alanlarını güncellemeniz, diğer alanları ise değiştirmemeniz gerekir. spreadsheets.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 alana 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, Grid türüne sahip yeni bir sayfa eklemek, ilk satırı dondurmak ve yeni sayfanın sekmesini kırmızı renkte yapmak için AddSheetRequest işlevi kullanılmaktadır:
POST https://sheets.googleapis.com/v1/spreadsheets/spreadsheetId:batchUpdate
{
"spreadsheetId": "SPREADSHEET_ID",
"replies": [
{
"addSheet": {
"properties": {
"sheetId": SHEET_ID,
"title": "TITLE",
"index": 6,
"sheetType": "GRID",
"gridProperties": {
"rowCount": 1000,
"columnCount": 26,
"frozenRowCount": 1
},
"tabColor": {
"red": 0.003921569
},
"tabColorStyle": {
"rgbColor": {
"red": 0.003921569
}
}
}
}
}
]
}