Alan maskeleri, API çağrılarının bir isteğin döndürmesi veya güncellenmesi gereken alanları listelemesi için kullanılan bir yöntemdir. FieldMask kullanılması, API'nin gereksiz işlerden kaçınmasını sağlar ve performansı artırır. Alan maskesi, Google Sheets API'de hem okuma hem de güncelleme yöntemleri için kullanılır.
Alan maskesiyle oku
E-tablolar büyük olabilir ve genellikle bir okuma isteği tarafından döndürülen Spreadsheet kaynağının her bir parçasına ihtiyacınız olmaz. fields URL parametresini kullanarak E-Tablolar API yanıtında döndürülen verileri sınırlandırabilirsiniz. En iyi performans için yanıtta yalnızca ihtiyacınız olan alanları açıkça listeleyin.
Alanlar 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 individual_by_underscores ile belirtilebilir. Kolaylık sağlaması açısından, aynı türde birden çok alt alan parantez içinde listelenebilir.
Aşağıdaki spreadsheets.get istek örneğinde, e-tablodaki tüm sayfalarda bir SheetProperties nesnesinin yalnızca sayfa kimliğini, başlığını, SheetType
ve GridProperties
nesnesini 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 nesnesidir. 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 maskesiyle güncelle
Bazen bir nesnedeki belirli alanları güncellerken diğer alanları değiştirmeden bırakmanız gerekir. spreadsheets.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ı, güncellenen iletide belirtmeyip maskeye ekleyerek de kaldırabilirsiniz. Bu sayede, ilgili alanın önceden sahip olduğu değer temizlenir.
Güncelleme alanı maskelerinin söz dizimi, okuma alanı maskeleriyle aynıdır.
Aşağıdaki örnekte Grid türünde yeni bir sayfa eklemek, ilk satırı dondurmak ve yeni sayfanın sekmesini kırmızı renklendirmek için AddSheetRequest 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
}
}
}
}
}
]
}