Bağlı Sayfaları kullanma

Bağlı sayfalar, BigQuery ve Looker verilerini doğrudan E-Tablolar'da analiz etmenizi sağlayan bir Google E-Tablolar özelliğidir. E-tablo hizmetiyle Bağlı Sayfalar'a programatik olarak erişme

Sık kullanılan Bağlı Sayfalar işlemleri

BigQuery veya Looker'a bağlanmak ve verileri analiz etmek için DataSource sınıfları ve nesneleri kullanın. Aşağıdaki tabloda en yaygın DataSource işlemleri ve bunları Google Apps Komut Dosyası'nda nasıl oluşturacağınız listelenmiştir:

İşlem	Apps Komut Dosyası sınıfı	Kullanım yöntemi
Bir sayfayı desteklenen bir veri kaynağına bağlama	`DataSourceSpec`	`SpreadsheetApp.newDataSourceSpec()`
Veri kaynağını seçin	`DataSource`	`Spreadsheet.insertDataSourceSheet().getDataSource()`
Veri kaynağı sayfası ekleme	`DataSourceSheet`	`Spreadsheet.insertDataSourceSheet()`
Pivot tablo ekleme	`DataSourcePivotTable`	`Range.insertDataSourcePivotTable()`
Ayıklama işlemine veri alma	`DataSourceTable`	`Range.insertDataSourceTable()`
Formül kullanma	`DataSourceFormula`	`Range.setFormula()`
Grafik ekleyin	`DataSourceChart`	`Sheet.insertDataSourceChart()`

Gerekli yetkilendirme kapsamlarını ekleme

BigQuery verilerine erişmek için Apps Komut Dosyası kodunuza enableBigQueryExecution() yöntemini ekleyin. Bu yöntem, Apps Komut Dosyası projenize gerekli bigquery.readonly OAuth kapsamını ekler.

Aşağıdaki örnekte, bir işlev içinde çağrılan SpreadsheetApp.enableBigQueryExecution() yöntemi gösterilmektedir:

function addDataSource() {
  SpreadsheetApp.enableBigQueryExecution();
  var spreadsheet = SpreadsheetApp.getActive();
  }

Looker verilerine erişmek için Apps Komut Dosyası kodunuza enableLookerExecution() yöntemini ekleyin. Apps Komut Dosyası'nda Looker'a erişirken mevcut Google Hesabı-Looker bağlantınız yeniden kullanılır.

Aşağıdaki örnekte, bir işlev içinde çağrılan SpreadsheetApp.enableLookerExecution() yöntemi gösterilmektedir:

function addDataSource() {
  SpreadsheetApp.enableLookerExecution();
  var spreadsheet = SpreadsheetApp.getActive();
  }

Manifest dosyasına ek OAuth kapsamları ekleme

BigQuery'ye bağlanırken, kodunuzda kullanılan işlevlere bağlı olarak çoğu OAuth kapsamı manifest dosyasına otomatik olarak eklenir. Belirli BigQuery verilerine erişmek için ek kapsamlar gerekiyorsa açık kapsamlar ayarlayabilirsiniz.

Örneğin, Google Drive'da barındırılan BigQuery verilerine sorgu göndermek için manifest dosyanıza bir Drive OAuth kapsamı eklemeniz gerekir.

Aşağıdaki örnekte bir manifest dosyasının oauthScopes bölümü gösterilmektedir. Minimum düzeyde gerekli spreadsheet ve bigquery.readonly OAuth kapsamlarına ek olarak bir Drive OAuth kapsamı ekler:

{ ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/bigquery.readonly",
    "https://www.googleapis.com/auth/spreadsheets",
    "https://www.googleapis.com/auth/drive" ],
... }

Örnek: Veri kaynağı nesnesi oluşturma ve yenileme

Aşağıdaki örneklerde veri kaynağı ekleme, veri kaynağından veri kaynağı nesnesi oluşturma, veri kaynağı nesnesini yenileme ve yürütme durumunu alma işlemleri gösterilmektedir.

Veri kaynağı ekle

Aşağıdaki örneklerde sırasıyla BigQuery ve Looker veri kaynağı ekleme gösterilmektedir.

BigQuery

Bir e-tabloya BigQuery veri kaynağı eklemek için veri kaynağı spesifikasyonu içeren bir veri kaynağı sayfası ekleyin. Veri kaynağı sayfası, önizleme verilerini getirmek için otomatik olarak yenilenir.

Aşağıdaki <YOUR_PROJECT_ID> kısmını geçerli bir Google Cloud proje kimliğiyle değiştirin.

// For operations that fetch data from BigQuery, enableBigQueryExecution() must be called.
SpreadsheetApp.enableBigQueryExecution();
var spreadsheet = SpreadsheetApp.create('Test connected sheets');
Logger.log('New test spreadsheet: %s', spreadsheet.getUrl());

// Build data source spec by selecting a table.
var dataSourceSpec = SpreadsheetApp.newDataSourceSpec()
    .asBigQuery()
    .setProjectId('<YOUR_PROJECT_ID>')
    .setTableProjectId('bigquery-public-data')
    .setDatasetId('ncaa_basketball')
    .setTableId('mbb_historical_tournament_games')
    .build();
// Add data source and its associated data source sheet.
var dataSourceSheet = spreadsheet.insertDataSourceSheet(dataSourceSpec);
var dataSource = dataSourceSheet.getDataSource();

Looker

Bir e-tabloya Looker veri kaynağı eklemek için veri kaynağı spesifikasyonu içeren bir veri kaynağı sayfası ekleyin. Veri kaynağı sayfası, önizleme verilerini getirmek için otomatik olarak yenilenir.

Aşağıdaki örnekte <INSTANCE_URL>,<MODEL_NAME>, <EXPLORE_NAME> değerlerini sırasıyla geçerli bir Looker örneği URL'si, model adı ve keşif adıyla değiştirin.

// For operations that fetch data from Looker, enableLookerExecution() must be called.
SpreadsheetApp.enableLookerExecution();
var spreadsheet = SpreadsheetApp.create('Test connected sheets');
Logger.log('New test spreadsheet: %s', spreadsheet.getUrl());

// Build data source spec by selecting a table.
var dataSourceSpec = SpreadsheetApp.newDataSourceSpec()
    .asLooker()
    .setInstanceUrl('<INSTANCE_URL>')
    .setModelName('<MODEL_NAME>')
    .setExploreName('<EXPLORE_NAME>')
    .build();
// Add data source and its associated data source sheet.
var dataSourceSheet = spreadsheet.insertDataSourceSheet(dataSourceSpec);
var dataSource = dataSourceSheet.getDataSource();

Veri kaynağı nesnesi ekleme

Veri kaynağı e-tabloya eklendikten sonra veri kaynağı nesneleri oluşturulabilir. Bu örnekte, BigQuery veri kaynağı ekleyen kod örneğinde oluşturulan BigQuery dataSource üzerinde DataSourcePivotTable kullanılarak bir pivot tablo oluşturulur.

Izgara sayfalarındaki hücre dizini veya A1 notasyonlarıyla referans verilen normal verilerin aksine, veri kaynaklarındaki verilere genellikle sütun adlarıyla referans verilir. Bu nedenle, veri kaynağı nesnelerindeki çoğu mülk ayarlayıcı, giriş olarak sütun adını kullanır.

var rootCell = spreadsheet.insertSheet('pivotTableSheet').getRange('A1');

// Add data source pivot table and set data source specific configurations.
var dataSourcePivotTable = rootCell.createDataSourcePivotTable(dataSource);
var rowGroup = dataSourcePivotTable.addRowGroup('season');
rowGroup.sortDescending().setGroupLimit(5);
dataSourcePivotTable.addColumnGroup('win_school_ncaa');
dataSourcePivotTable.addPivotValue('win_pts',
SpreadsheetApp.PivotTableSummarizeFunction.AVERAGE);
dataSourcePivotTable.addPivotValue('game_date',
SpreadsheetApp.PivotTableSummarizeFunction.COUNTA);
var filterCriteria = SpreadsheetApp.newFilterCriteria()
    .whenTextEqualToAny(['Duke', 'North Carolina'])
    .build();
dataSourcePivotTable.addFilter('win_school_ncaa', filterCriteria);

// Get a regular pivot table instance and set shared configurations.
var pivotTable = dataSourcePivotTable.asPivotTable();
pivotTable.setValuesDisplayOrientation(SpreadsheetApp.Dimension.ROWS);

Veri kaynağı nesnesini yenileme

Veri kaynağı özelliklerine ve nesne yapılandırmalarına göre BigQuery'den en son verileri getirmek için veri kaynağı nesnelerini yenileyin.

Verileri yenileme işlemi eşzamansızdır. Bir veri kaynağı nesnesini yenilemek için aşağıdaki yöntemleri kullanın:

refreshData() veri yenileme yürütmesini başlatır.
waitForCompletion(), veri yürütme işlemi tamamlandıktan sonra son durumu döndürür. Bu sayede yürütme durumunu sürekli olarak yoklamanız gerekmez.
DataExecutionStatus.getErrorCode(), veri yürütme başarısız olursa hata kodunu alır.

Aşağıdaki örnekte, pivot tablo verilerinin yenilenmesi gösterilmektedir:

var status = dataSourcePivotTable.getStatus();
Logger.log('Initial state: %s', status.getExecutionState());

dataSourcePivotTable.refreshData();

status = dataSourcePivotTable.waitForCompletion(/* timeoutInSeconds= */ 60);
Logger.log('Ending state: %s', status.getExecutionState());
if (status.getExecutionState() == SpreadsheetApp.DataExecutionState.ERROR) {
  Logger.log('Error: %s (%s)', status.getErrorCode(),
  status.getErrorMessage());
}

Bağlı sayfalarla tetikleyicileri kullanma

Tetikleyiciler ve etkinlikler ile Bağlı Sayfalar veri kaynağı işlevlerinizi otomatikleştirin. Örneğin, veri kaynağı nesnelerini belirli bir zamanda tekrar tekrar yenilemek için zamana dayalı tetikleyicileri, önceden tanımlanmış bir etkinlikte veri yürütmeyi tetiklemek için ise e-tablo etkinlik tetikleyicilerini kullanın.

Aşağıdaki örnekte, sorgu parametresi içeren bir BigQuery veri kaynağı ekleniyor ve sorgu parametresi düzenlendiğinde veri kaynağı sayfası yenileniyor.

<YOUR_PROJECT_ID> kısmını geçerli bir Google Cloud proje kimliğiyle değiştirin.

// Add data source with query parameter.
function addDataSource() {
  SpreadsheetApp.enableBigQueryExecution();
  var spreadsheet = SpreadsheetApp.getActive();

  // Add a new sheet and use A1 cell as the parameter cell.
  var parameterCell = spreadsheet.insertSheet('parameterSheet').getRange('A1');
  parameterCell.setValue('Duke');

  // Add data source with query parameter.
  var dataSourceSpec = SpreadsheetApp.newDataSourceSpec()
      .asBigQuery()
      .setProjectId('<YOUR_PROJECT_ID>')
      .setRawQuery('select * from `bigquery-public-data`.`ncaa_basketball`.`mbb_historical_tournament_games` WHERE win_school_ncaa = @SCHOOL')
      .setParameterFromCell('SCHOOL', 'parameterSheet!A1')
      .build();
  var dataSourceSheet = spreadsheet.insertDataSourceSheet(dataSourceSpec);
  dataSourceSheet.asSheet().setName('ncaa_data');
}

// Function used to configure event trigger to refresh data source sheet.
function refreshOnParameterEdit(e) {
  var editedRange = e.range;
  if (editedRange.getSheet().getName() != 'parameterSheet') {
    return;
  }
  // Check that the edited range includes A1.
  if (editedRange.getRow() > 1 || editedRange.getColumn() > 1) {
     return;
  }

  var spreadsheet = e.source;
  SpreadsheetApp.enableBigQueryExecution();
  spreadsheet.getSheetByName('ncaa_data').asDataSourceSheet().refreshData();
}

Önceki örnekte, addDataSource() işlevi e-tabloya bir veri kaynağı ekler. addDataSource() komutunu çalıştırdıktan sonra Apps Komut Dosyası Düzenleyici'de bir etkinlik tetikleyicisi oluşturun. Etkinlik tetikleyici oluşturmayı öğrenmek için Yüklenebilir tetikleyiciler başlıklı makaleyi inceleyin.

Tetikleyiciniz için aşağıdaki seçenekleri belirleyin:

Etkinlik kaynağı: E-tablodan
Etkinlik türü: Düzenleme yapıldığında
Çalıştırılacak işlev: refreshOnParameterEdit

Tetikleyici oluşturulduktan sonra, parametre hücresi her düzenlendiğinde veri kaynağı sayfası otomatik olarak yenilenir.

Sorun giderme

Hata mesajı Çözünürlük

BIGQUERY veri kaynaklarına yönelik veri yürütme işlemlerini etkinleştirmek için enableBigQuery() yöntemini kullanın. Bu hata, BigQuery verileri getirilmeden önce SpreadsheetApp.enableBigQueryExecution() işlevinin çağrılmadığını gösterir.
BigQuery yürütme yöntemlerini kullanan işlevlerde SpreadsheetApp.enableBigQueryExecution()'ı çağırın.
Örneğin, veri kaynağı nesnelerinde refreshData(), Spreadsheet.insertDataSourceTable() ve DataSource.updateSpec().
Bu yöntemlerin çalışması için ek bir bigquery.readonly OAuth kapsamı gerekir.

Veri kaynaklarında işlem yapılmasına izin verilmiyor.
Özelliği etkinleştirmek için lütfen yöneticinizle iletişime geçin. Bu hata, hesapta bağlı sayfaların etkinleştirilmediğini gösterir.
Bağlı sayfalar yalnızca belirli aboneliklere sahip Google Workspace kullanıcıları tarafından kullanılabilir.
Özelliği etkinleştirmek için yöneticinizle iletişime geçin.

Hata mesajı	Çözünürlük
BIGQUERY veri kaynaklarına yönelik veri yürütme işlemlerini etkinleştirmek için `enableBigQuery()` yöntemini kullanın.	Bu hata, BigQuery verileri getirilmeden önce `SpreadsheetApp.enableBigQueryExecution()` işlevinin çağrılmadığını gösterir. BigQuery yürütme yöntemlerini kullanan işlevlerde `SpreadsheetApp.enableBigQueryExecution()`'ı çağırın. Örneğin, veri kaynağı nesnelerinde `refreshData()`, `Spreadsheet.insertDataSourceTable()` ve `DataSource.updateSpec()`. Bu yöntemlerin çalışması için ek bir bigquery.readonly OAuth kapsamı gerekir.
Veri kaynaklarında işlem yapılmasına izin verilmiyor. Özelliği etkinleştirmek için lütfen yöneticinizle iletişime geçin.	Bu hata, hesapta bağlı sayfaların etkinleştirilmediğini gösterir. Bağlı sayfalar yalnızca belirli aboneliklere sahip Google Workspace kullanıcıları tarafından kullanılabilir. Özelliği etkinleştirmek için yöneticinizle iletişime geçin.

Bağlı Sayfaları kullanma Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.