Alan maskeleri kullanma

Alan maskeleri, API çağıranları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 Sheets API'deki hem okuma hem de güncelleme yöntemleri için kullanılır.

Alan maskesiyle okuma

E-tablolar büyük olabilir ve genellikle okuma isteğiyle döndürülen kaynağın her bölümüne ihtiyacınız olmaz.Spreadsheet fields URL parametresini kullanarak bir 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.

Alanlar parametresinin biçimi, FieldMask'ın JSON kodlaması ile aynıdır. Kısaca belirtmek gerekirse, birden fazla farklı alan virgülle ayrılır ve alt alanlar nokta ile 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, yalnızca e-tablo kimliğini, başlığını, SheetType, ve GridProperties bir e-tablodaki tüm sayfalarda bulunan SheetProperties nesnesini getirmek için sheets.properties(sheetId,title,sheetType,gridProperties) alan maskesi kullanılır:

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties(sheetId,title,sheetType,gridProperties)

Bu yöntem çağrısına verilen yanıt, alan maskesinde istenen bileşenleri içeren bir Spreadsheet nesnesidir. Unutmayın: sheetType=OBJECT, gridProperties değerini içermiyor:

{
  "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üncelleme

Bazen bir nesnedeki yalnızca belirli alanları güncellemeniz, diğer alanları ise değiştirmemeniz 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 alanları yok sayarak mevcut değerleriyle bırakır.

Güncellenen iletide belirtmeyerek ancak alanı maskeye ekleyerek de bir alanın ayarını 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.

Aşağıdaki örnekte, AddSheetRequest kullanılarak Grid türünde yeni bir sayfa ekleniyor, ilk satır donduruluyor ve yeni sayfanın sekmesi kırmızı renkte gösteriliyor:

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
            }
          }
        }
      }
    }
  ]
}