Data Studio’ya bağlamak istediğin veri kaynağı standart Google connector’larında (GA4, Search Console, Ads, Sheets, BigQuery) yoksa iki seçenek var: Supermetrics gibi paid bir köprü aboneliği ya da kendi Community Connector’ını yazmak. Bu yazı ikinci yolun mimarisini, dört zorunlu Apps Script fonksiyonunu, sürümlü deployment akışını ve hâlâ pek çok ajansın atladığı maintenance maliyetini ele alıyor.
Bağlam: Looker Studio, 10 Nisan 2026’da resmi olarak Data Studio ismine geri döndü1. Looker (eski enterprise BI) ile arasındaki ayrım netleşti; Community Connector geliştirme yüzeyi ise tüm bu yeniden adlandırmaların altında değişmedi. Apps Script Data Studio servisi2 hâlâ resmi geliştirme arabirimi.
Community Connector Nedir, Ne Değildir
Community Connector, internet üzerinden erişilebilir herhangi bir veri kaynağını Data Studio’ya bağlayan, Apps Script ile yazılmış bir eklentidir. Resmi tanım: “scripts to access and modify Data Studio Community Connectors”2. Pratikte üç katmandan oluşan bir bridge:
- Apps Script kodu — dört zorunlu fonksiyon ve yardımcı utility’ler
- Manifest (
appsscript.json) — Data Studio’nun connector’ı tanıması için meta veri - Deployment — Head (geliştirme) ve sürümlü (production) iki ayrı yayım
Connector, Data Studio’nun bilmediği bir API ya da niş bir veri kaynağı için tasarlanır. Tipik kullanım alanları:
- E-ticaret platform raporları (Shopify, WooCommerce custom report’ları)
- Niş reklam ağları (TikTok, Reddit Ads, Quora Ads gibi büyük platformlar dışında kalanlar)
- Custom CRM veya HRIS sistemleri
- Public open data setleri
- Şirket içi REST API’lar
Connector olmayan şeyler: data transformation engine değil (ETL Data Studio’da değil, kaynakta yapılır), real-time stream değil (cache ve refresh interval’a bağlı), dashboard değil (sadece veri sağlayıcı).
Ne Zaman Community Connector Yazılır
Karar, hedef veri kaynağının üç boyutu üzerinden verilir:
| Boyut | Custom connector mantıklı | Paid çözüm (Supermetrics, Funnel.io) mantıklı |
|---|---|---|
| Kaynak sayısı | 1-3 niş API | 5+ farklı platform |
| API stabilitesi | Stabil, versiyonlu | Sık breaking change |
| Bakım süresi | Aylık 2-3 saat ayrılabilir | Bakım iç ekipten çıkarılmak isteniyor |
| Bütçe | Sıfır direct cost, geliştirici zamanı var | Aylık $90-300 abonelik OK |
| Privacy | Veri kendi GCP’ne gitmeli | Üçüncü taraf cloud OK |
Whatagraph’ın 2026 review’inde geçen gözlem net:
“Community connectors are great in theory. Sketchy in production. If the dev who built it doesn’t maintain it, you’re on your own.”
Bu cümle, custom connector kararını verirken üzerinde durulması gereken tek paragraflık özet. Sketchy in production uyarısı %2 oranlı resmi Google connector ile %98 oranlı topluluk connector’ü arasındaki bakım asimetrisinden geliyor: gallery’de 24 Google-built stable connector’a karşılık 1.188 üçüncü taraf connector listeleniyor.
Dört Zorunlu Fonksiyon
Her Community Connector dört global fonksiyonu export etmek zorunda. Eksik biri olursa Data Studio connector’ı yüklemiyor.
getAuthType()
Connector’ın hangi auth mekanizmasını kullandığını Data Studio’ya bildiren minimal fonksiyon.
var cc = DataStudioApp.createCommunityConnector();
function getAuthType() {
var AuthTypes = cc.AuthType;
return cc
.newAuthTypeResponse()
.setAuthType(AuthTypes.KEY)
.setHelpUrl("https://example.com/help")
.build();
}Apps Script Data Studio servisi yedi auth tipi sunuyor2:
| Auth tipi | Kullanım senaryosu |
|---|---|
NONE | Public API, auth gerekmez |
OAUTH2 | Standart OAuth 2.0 (Sheets, GitHub, niche reklam platformları) |
USER_PASS | Basic auth: kullanıcı adı + parola |
PATH_USER_PASS | API endpoint path + kullanıcı adı + parola |
PATH_KEY | API endpoint path + API key |
KEY | Tek bir API key veya bearer token |
USER_TOKEN | Kullanıcı adı + personal access token |
OAuth 2.0 seçilirse ek fonksiyonlar zorunlu: get3PAuthorizationUrls(), authCallback(), resetAuth(), isAuthValid(). OAuth 2.0 implementasyonu basit bir KEY auth’una göre 4-5 kat fazla kod ve sertifikalandırma süreci gerektiriyor.
getConfig(request)
Kullanıcının connector’ı Data Studio’ya eklerken görüntülediği konfigürasyon UI’sini tanımlar.
function getConfig() {
var config = cc.getConfig();
config
.newInfo()
.setId("instructions")
.setText("Enter npm package names to fetch their download count.");
config
.newTextInput()
.setId("package")
.setName("Enter package name(s), comma-separated")
.setHelpText('e.g. "googleapis" or "package,somepackage,anotherpackage"')
.setPlaceholder("googleapis")
.setAllowOverride(true);
config.setDateRangeRequired(true);
return config.build();
}Konfigürasyon UI bileşenleri: Info, TextInput, TextArea, Checkbox, SelectSingle, SelectMultiple. Hepsi builder pattern ile.
Dinamik konfigürasyon (örnek: hesap → property → view zinciri) için config.setIsSteppedConfig(true) çağrılır. Stepped config aktifken getConfig() her form değişikliğinde yeniden çağrılıyor; bu nedenle ağır API çağrıları konfigürasyon fonksiyonunda değil getData() içinde tutulur.
getSchema(request)
Connector’ın döndüreceği alanları (boyutlar ve metrikler) tanımlar.
function getFields() {
var fields = cc.getFields();
var types = cc.FieldType;
var aggregations = cc.AggregationType;
fields
.newDimension()
.setId("packageName")
.setName("Package")
.setType(types.TEXT);
fields
.newDimension()
.setId("day")
.setName("Date")
.setType(types.YEAR_MONTH_DAY);
fields
.newMetric()
.setId("downloads")
.setName("Downloads")
.setType(types.NUMBER)
.setAggregation(aggregations.SUM);
return fields;
}
function getSchema(request) {
return { schema: getFields().build() };
}FieldType enum’ı 100’den fazla değere sahip. Pratikte en sık kullanılanlar:
- Tarih:
YEAR,YEAR_MONTH,YEAR_MONTH_DAY,YEAR_MONTH_DAY_HOUR,DAY_OF_WEEK,DURATION - Coğrafi:
COUNTRY,COUNTRY_CODE,REGION,CITY,LATITUDE_LONGITUDE - Para:
CURRENCY_TRY,CURRENCY_USD,CURRENCY_EUR(90+ ISO kod desteği) - Sayısal:
NUMBER,PERCENT,BOOLEAN - Metin/medya:
TEXT,URL,HYPERLINK,IMAGE,IMAGE_LINK
TR e-ticaret için kritik nokta: CURRENCY_TRY doğrudan desteklendiği için Data Studio’da TL formatlama için ekstra calculated field tanımlamaya gerek yok.
getData(request)
Asıl veri çekiminin yapıldığı fonksiyon. Request objesi üç kritik parametre taşıyor:
request.fields— Data Studio’nun istediği alanlar listesi (her zaman tüm schema değil)request.configParams—getConfig()’den gelen kullanıcı input’urequest.dateRange—setDateRangeRequired(true)ise{ startDate, endDate }request.lastRefresh— son refresh timestamp’ı, cache kararı için
function getData(request) {
request.configParams = validateConfig(request.configParams);
var requestedFields = getFields().forIds(
request.fields.map(function (field) {
return field.name;
}),
);
try {
var apiResponse = fetchDataFromApi(request);
var normalizedResponse = normalizeResponse(request, apiResponse);
var data = getFormattedData(normalizedResponse, requestedFields);
} catch (e) {
cc.newUserError()
.setDebugText("Error fetching data from API. Exception details: " + e)
.setText(
"The connector has encountered an unrecoverable error. Please try again later, or file an issue if this error persists.",
)
.throwException();
}
return {
schema: requestedFields.build(),
rows: data,
};
}
function fetchDataFromApi(request) {
var url = [
"https://api.npmjs.org/downloads/range/",
request.dateRange.startDate,
":",
request.dateRange.endDate,
"/",
request.configParams.package,
].join("");
return UrlFetchApp.fetch(url);
}getData() performans ve maliyet katmanının kalbi. Üç pratik kural:
- Sadece istenen alanları işle.
requestedFields = getFields().forIds(...)filtresi olmadan tüm schema dönülürse gereksiz hesap ve transfer yapılır. lastRefreshile cache karşılaştırması. Apps Script Cache Service3 kullanılarak son veri çekiminden bu yana yeterli süre geçtiyse cache’ten serve edilir.- Try/catch + UserError pattern. Yakalanmamış istisna Data Studio chart’ında jenerik “Internal error” mesajı üretir; user-facing mesaj UserError ile yönetilmek zorunda.
Manifest
Apps Script editor → View → Show manifest file ile appsscript.json dosyası açılır. Data Studio bloğu zorunlu:
{
"dependencies": {
"libraries": []
},
"dataStudio": {
"name": "npm Downloads",
"logoUrl": "https://raw.githubusercontent.com/npm/logos/master/npm%20square/n-64.png",
"company": "Your Company",
"companyUrl": "https://example.com",
"addonUrl": "https://example.com/connector",
"supportUrl": "https://example.com/support",
"description": "Get npm package download counts.",
"sources": ["npm"]
},
"oauthScopes": ["https://www.googleapis.com/auth/script.external_request"]
}oauthScopes listesi sıfır toleranslı: connector hangi Apps Script kaynaklarını kullanıyorsa hepsi açıkça beyan edilmeli. External HTTP isteği için script.external_request, Cache Service için ek bir scope yok (script.scriptapp altında implicit). Eksik scope’lar yayım sırasında değil, runtime’da hata olarak ortaya çıkıyor.
Head Deployment ile Test
Apps Script her save’de otomatik bir Head Deployment güncelliyor. Bu deployment her zaman en son kodu çalıştırıyor; production’a göre geliştirme döngüsü çok daha hızlı.
Test akışı:
- Apps Script editor → Deploy → Test deployments → Head Deployment ID kopyala
- Tarayıcıda aç:
https://datastudio.google.com/datasources/create?connectorId=HEAD_DEPLOYMENT_ID - Data Studio connector’ı yüklüyor,
getAuthType()→getConfig()→getSchema()→getData()zincirini tek tek çağırıyor - Her save sonrası tarayıcıyı yenile, yeni kod doğrudan etkin
UrlFetchApp.fetch çağrıları Apps Script execution log’larında görülüyor (View → Executions). Debug için Logger.log() yerine console.log() tercih edilmeli; daha okunabilir log çıktısı veriyor.
Sürümlü Production Deployment
Head Deployment her save’le güncellendiği için son kullanıcıya verilmez. Production için iki ayrı versioned deployment tutulur:
| Deployment | Amaç |
|---|---|
| Head | Geliştirme, her save’de otomatik güncel |
| Test | Stabil test, manuel olarak version pinlenir |
| Production | Son kullanıcı, manuel version pin |
Yeni sürüm yayma akışı:
- Apps Script → Deploy → New deployment
- Type: Add-on (Community Connector için bu seçilir)
- Version’ı pinle (otomatik sayı verilir)
- Deployment ID + connector URL alınır
- URL son kullanıcı veya internal team ile paylaşılır
Mevcut deployment’ı güncellemek için Deploy → Manage deployments → Edit → New version. Son kullanıcı re-share gerekmiyor; aynı deployment URL’i yeni versiyonu otomatik servis ediyor.
Hata Yönetimi: UserError ve DebugError
Apps Script Data Studio servisi iki tür hata objesi sunuyor2:
// Son kullanıcı görür
cc.newUserError()
.setText("Invalid API key. Please check your credentials.")
.setDebugText("API returned 401 with body: " + responseBody)
.throwException();
// Sadece connector geliştirici / admin görür
cc.newDebugError()
.setText("Schema mismatch: expected 5 columns, got 7")
.throwException();Ayrım önemli: kullanıcı dostu mesaj ile teknik debug mesajı aynı objede ama farklı alanlarda tutuluyor. DebugError son kullanıcıya hiç görünmüyor, sadece Apps Script execution log’unda görünüyor. PII içeren veya sistem mimarisini ifşa eden mesajlar UserError.text alanında değil UserError.debugText alanında olmalı.
Workspace Admin Bağlamı
Connector’ı Google Workspace organizasyonu içinde dağıtacaksan iki policy katmanını doğrulamak zorundasın:
-
Apps Script açık mı? Admin console → Apps → Google Workspace → Drive and Docs → Google Apps Script. Kapalıysa connector veri çekemez, kullanıcılar şu mesajı görür:
Can't show data. Apps Script is disabled for your organization. -
Üçüncü taraf connector policy’si? Workspace admin → Data Studio settings → Community connector data source creation. Kapalıysa:
Community connectors are disabled for your organization.
Bu iki policy birbirinden bağımsız. Apps Script açık olsa da Data Studio policy’si kapalı olabilir. Connector deploy etmeden önce hedef organizasyonun policy durumunu admin ile teyit etmek, deployment sonrası “kullanıcılarda çalışmıyor” tipi destek talebini sıfırlıyor.
Apps Script ON ama Drive and Docs OFF edge case’inde: kullanıcı script create/edit yapamaz ama mevcut script’ler çalışmaya devam eder. Connector’ı geliştirici kapatılmış bir Drive ortamında deploy etti ise normal kullanım çalışır, sadece kod düzenleme bloklanır.
Production Ortamı Hata Kalıpları
Custom connector deploy edildikten sonra karşılaşılan beş tipik hata kalıbı:
| Hata | Sebep | Çözüm |
|---|---|---|
| Connector internal error | getData() API response parse edemedi | try/catch + UserError, fallback data row’u |
Service invoked too many times in a short time: exec qps | Apps Script execution quota | Cache Service ile rate limit; UrlFetchApp call’larını batch’le |
| ”Apps Script is disabled for your organization” | Workspace admin Apps Script’i kapatmış | Admin ile teması açıkça yönet |
| Real-time refresh fails | API quota veya cache miss | Extract Data connector ile cache layer ekle |
| Auth fails after working initially | Token expired veya scope değişti | Reauthorize data source akışı, gerekirse resetAuth() çağrısı |
Cache Service kullanımı kritik. Apps Script free Workspace hesapları için UrlFetchApp günlük 20.000 çağrı limiti, premium hesaplar 100.000 üzeri. Bir connector kullanıcı sayısı arttıkça bu sınır beklenenden hızlı dolar. Cache kalıbı:
var cache = CacheService.getScriptCache();
var cacheKey =
"data_" + request.configParams.package + "_" + request.dateRange.startDate;
var cached = cache.get(cacheKey);
if (cached) {
return JSON.parse(cached);
}
var freshData = fetchDataFromApi(request);
cache.put(cacheKey, JSON.stringify(freshData), 1800); // 30 dakika
return freshData;Cache TTL’i Data Studio refresh interval’ından biraz kısa tutmak gerekiyor (örnek: Data Studio 1 saatte bir refresh ise cache 50-55 dakika). Eşit ya da uzun TTL stale veri riskini artırıyor.
BigQuery Config: Connector İçinden SQL Çalıştırmak
Connector’ın hedef veri kaynağı zaten BigQuery’de ise BigQueryConfig builder’ı kullanılır2. Bu, Apps Script’in UrlFetchApp yerine native BigQuery API’sini çağırması anlamına geliyor.
var config = cc
.newBigQueryConfig()
.setAccessToken(token)
.setBillingProjectId("my-project")
.setUseStandardSql(true)
.setQuery("SELECT * FROM dataset.table WHERE date = @date")
.addQueryParameter("date", cc.BigQueryParameterType.STRING, "2026-05-24");Maliyet sınırlama üç katmanlı:
-
Query level limit. BigQuery query’sinde Maximum bytes billed ayarı (More → Query settings → Advanced) aşılırsa query fail olur, cost sıfır kalır. Connector’ın sorgu wrapper’ına bu limit dahil edilmeli.
-
Schema level disiplin. Hedef tablo
PARTITION BY date_col CLUSTER BY high_cardinality_col+OPTIONS (require_partition_filter=true)ile yaratılırsa filtersiz sorgu engellenir. Connector kullanıcısı yanlışlıkla full table scan tetiklemez. -
0-cost operasyon disiplini.
SELECT DISTINCT day FROM tableörnek case’te 149 GB / $1.18, aynı sonucuINFORMATION_SCHEMA.PARTITIONSile çekmek 10 MB / $0.00008 — 14.900 kat fark4. Connector’da yardımcı sorgular içinINFORMATION_SCHEMApattern’i tercih edilir.
LIMIT 1000 ile sorgu maliyeti azalmıyor; BigQuery tüm tabloyu scan eder, sadece return edilen row sayısı düşer. Maliyet azaltmak için TABLESAMPLE SYSTEM (X PERCENT) veya column subset (SELECT * yerine spesifik kolonlar) kullanılır4.
Maintenance: Sessiz Bedel
Custom connector’ın yazılışı genelde 8-16 saat alıyor. Asıl maliyet bu değil; deploy sonrası bakım süresi. Tipik yıllık bakım kalemleri:
- API breaking change adaptasyonu — kaynak API’nin V1’den V2’ye geçişi, response format değişikliği
- OAuth scope güncellemeleri — Google ya da üçüncü taraf scope policy değiştirir, re-auth gerekir
- Rate limit yeniden kalibrasyonu — kullanıcı sayısı arttıkça cache strategy revize edilir
- Schema değişiklikleri — kullanıcı yeni alan istediğinde
getSchema()vegetData()paralel güncellenmeli - Workspace admin policy değişiklikleri — kullanıcı organizasyonu Apps Script policy’sini revize ederse destek talebi
Whatagraph’ın aktardığı practitioner uyarısı yeniden:
“You can build your own or use open-source ones published by others. This adds flexibility, but it’s not plug-and-play. You’ll need technical expertise, API familiarity, and time to maintain it.”
Bu yüzden custom connector kararı verilmeden önce 24 aylık maintenance commitment’ı zihinsel olarak verilmiş olmalı. Aksi halde connector deploy edilir, 6 ay sonra API breaking change gelir, kimse fix etmez, kullanıcılar sessizce hatalı veri raporlamaya başlar. Silent data truncation Data Studio’da gözlemlenen tipik production failure’larından biri5.
Dağıtım Opsiyonları
Connector deploy edildikten sonra iki dağıtım modeli var:
-
Direct share. Deployment URL’i hedef kullanıcıya gönderilir, kullanıcı
connectorId=...URL’i ile Data Studio’da data source oluşturur. Internal ekipler ve ajans-müşteri ilişkileri için yeterli. -
Public Gallery submission. Google’ın resmi Connector Gallery6’sine başvuru yapılır. Onay süreci weeks. Onaylanırsa connector tüm Data Studio kullanıcılarına aranabilir hale gelir. Marketing analytics niche’inde public connector yayımı brand exposure ve potansiyel lead generation kaynağı; ancak gallery onayı için support ve docs requirement yüksek.
Direct share modeli, ajans-müşteri çalışması veya iç organizasyon connector’ları için %90 senaryoyu kapsıyor. Public gallery yayımı production-grade documentation ve support kapasitesi olmadan zarar verir; abandoned connector listeleri Data Studio gallery’sinde mevcut.
Karar Özeti
| Soru | Cevap |
|---|---|
| Hedef veri kaynağı niche ve stabil mi? | Custom connector mantıklı |
| 5+ farklı kaynak gerekiyor mu? | Supermetrics veya Funnel.io mantıklı |
| Aylık 2-3 saat bakım kabul edilebilir mi? | Custom connector mantıklı |
| Veri privacy nedeniyle üçüncü taraf cloud istenmiyor mu? | Custom connector mantıklı |
| Geliştirici Apps Script’e zaman ayıramıyor mu? | Paid çözüm |
| BigQuery’de veri zaten var mı? | BigQueryConfig veya doğrudan native BQ connector |
Cluster’ın ikinci yazısı Data Studio Pro Ne Zaman Değer? Pro tier’ın Community Connector tarafına katkısını ve yine maintenance ekonomisini ele alıyor; Pro sabit bir kullanıcı başı aylık abonelik olduğu için karar müşteri sayısından çok manuel iş yükü tasarrufuna bağlanıyor.
Niche API entegrasyonu, OAuth scope tasarımı, Apps Script execution quota planlaması ve BigQuery maliyet sınırlandırma. Custom connector mu yoksa paid çözüm mü mantıklı sorusunu sizin senaryonuza özel cevaplayalım.
İletişime GeçinFootnotes
- Looker Studio is Data Studio (Google Cloud Blog, 10 Nisan 2026) ↩
- Apps Script Data Studio Service Reference ↩ ↩2 ↩3 ↩4 ↩5
- Apps Script Cache Service ↩
- Volker Janz, “Burn Data Rather Than Money with BigQuery: The Definitive Guide” (2024) ↩ ↩2
- r/BusinessIntelligence — “Looker Studio vs Others” practitioner thread (2024) ↩
- Data Studio Connector Gallery ↩
- 01 Community Connector dört zorunlu fonksiyondan oluşan bir Apps Script eklentisidir: getAuthType, getConfig, getSchema, getData
- 02 Test için Head Deployment URL'i, production için sürümlü deployment (Test ve Production) ayrı tutulur
- 03 Auth tipleri arasında karar OAuth 2.0, KEY, USER_PASS ve PATH_KEY arasında veri kaynağının protokolüne göre verilir
- 04 Workspace audience için connector deploy etmeden önce Apps Script ve Data Studio admin policy'leri doğrulanmalıdır
- 05 Custom connector ücretsiz başlasa da maintenance, error handling ve API breaking change adaptasyonu yazılım yazana ait
- 06 BigQueryConfig kullanılıyorsa Maximum bytes billed + cluster filter + Cache Service üçlüsü maliyet kontrolünün temelidir
+ Community Connector yazmak için Apps Script bilmek şart mı?
Evet, Community Connector resmi olarak Apps Script üzerinde geliştirilir. JavaScript syntax yeterli, V8 runtime varsayılan. Apps Script Data Studio servisi (DataStudioApp.createCommunityConnector) builder ve enum'ları sağlıyor, böylece IDE benzeri bir setup gerekmiyor.
+ Workspace hesabımda Community Connector çalışmıyor, neden?
Workspace admin Apps Script'i kapatmış olabilir veya Data Studio settings altında üçüncü taraf connector'lerden data source oluşturma policy'si reddedilmiş olabilir. Apps Script kapalıyken connector veri çekemez, chart'lar 'Can't show data. Apps Script is disabled for your organization' mesajı verir. Admin ile konuşulup ilgili policy'nin org-unit bazında açılması gerekir.
+ Custom Community Connector mı yoksa Supermetrics gibi paid çözüm mü daha iyi?
Connector'ın hedeflediği veri kaynağı niche ve istikrarlı bir API sunuyorsa custom connector ücretsiz başlangıç sunuyor, ancak maintenance commitment'ı yazılım yazılımı kişiye geçiyor. Supermetrics 100+ kaynak için hazır connector, support, SLA ve breaking change adaptasyonu sunar. Tek veya iki API ile sınırlıysan ve aylık iki saatlik bakım ayırabiliyorsan custom mantıklı; aksi halde paid çözüm operasyonel maliyeti düşürüyor.
+ Connector kullanıcı credential'ını saklıyor mu?
Hayır. Data Studio, kullanıcının connector'a verdiği credential'ı (API key, OAuth token, kullanıcı adı/parola) saklamıyor. Connector her veri çekiminde credential'ı üçüncü taraf API'ya iletip 'hâlâ geçerli mi' sorgusu yapıyor. Bu davranış güvenlik için tasarlanmış olsa da connector geliştiricisinin token rotation ve scope değişikliklerine dayanıklı kod yazmasını zorunlu kılıyor.
+ Connector BigQuery üzerinde SQL çalıştırıyorsa maliyeti nasıl sınırlanır?
BigQueryConfig builder kullanılırsa connector doğrudan kullanıcının BigQuery projesinde sorgu çalıştırıyor. Maliyet kontrolü için iki katman gerekir: query level Maximum bytes billed limit ve dataset bazında partition + cluster zorunluluğu (require_partition_filter=true). Connector kodu içinde de Apps Script Cache Service ile lastRefresh timestamp kontrolü yapıp gereksiz BigQuery query'lerini engellemek kritik.