Veri dönüştürme ve kaynak boru hattı
Gelen olay ve kişi verisini yazmadan önce düzeltin, süzün ve zenginleştirin; kendi sistemlerinizden webhook veya zamanlanmış HTTP çekme ile veri alın. Hatalı bir kural veriyi düşürmez: kayıt karantinaya alınır, kural…
Gelen olay ve kişi verisini yazmadan önce düzeltin, süzün ve zenginleştirin; kendi sistemlerinizden webhook veya zamanlanmış HTTP çekme ile veri alın. Hatalı bir kural veriyi düşürmez: kayıt karantinaya alınır, kural düzeltilince yeniden işlenir. Growth ve üzeri planlarda kullanılabilir (ADR-0088).
Nasıl çalışır
- Olay SDK'dan, public API'den, içe aktarmadan, Segment'ten veya bir kaynak bağlayıcısından gelir.
- App'in açık dönüştürmeleri sırayla (
position) uygulanır. Bir dönüştürme hedefe (eventveyaperson), kaynağa (sdk,api,import,system,webhook_source,pull_source) ve olay adına göre sınırlanabilir; liste boşsa hepsine uygulanır. - Sonuç doğrulanır ve yazılır. Süzme kuralına takılan kayıt bilinçli olarak düşer. Kural, JavaScript, doğrulama veya yazım hatası veren kayıt karantinaya özgün hâliyle yazılır.
Olay dönüştürmeleri yalnız name, properties, value ve occurred_at alanlarını değiştirebilir; kişi/abonelik bağı
ve event_id değiştirilemez. Public API'nin accepted sayısı değişmez (süzülen ve karantinadaki olay da kabul
edilmiştir). Kişi dönüştürmeleri kaynak bağlayıcılarının kişi kayıtlarına ve Segment identify çağrılarına uygulanır.
Kural dönüştürmesi
Panel → Kitle → Veri boru hattı → Dönüştürmeler → Yeni dönüştürme. Kural adımları sırayla çalışır; alan yolları
noktalıdır (properties.cart.0.sku).
| İşlem | Açıklama |
|---|---|
map | Değeri başka alana kopyalar (alan eşleme). |
rename | Değeri taşır, eski alanı siler. |
remove | Alanı siler (ör. gizli alan). |
set | Sabit değer yazar (zenginleştirme). |
template | {{yol}} yer tutucularıyla metin üretir. |
compute | lower, upper, trim, length, round, abs, add, multiply, now. |
cast | string, number, integer, boolean, date; dönüşmezse on_error: fail (karantina, varsayılan), null, keep. |
filter | Koşullar sağlanınca kaydı düşürür (drop) ya da yalnız sağlananları tutar (keep); all / any. |
Koşul işleçleri: eq, neq, gt, gte, lt, lte, contains, starts_with, ends_with, in, exists,
not_exists.
{
"name": "Fiyat düzeltme",
"target": "event",
"kind": "rules",
"event_names": ["checkout"],
"rules": [
{ "op": "filter", "action": "drop", "conditions": [{ "path": "properties.test", "operator": "eq", "value": true }] },
{ "op": "rename", "from": "properties.fiyat", "to": "properties.price" },
{ "op": "cast", "path": "properties.price", "to": "number" },
{ "op": "set", "path": "properties.channel", "value": "web" }
]
}API ile: POST /v1/apps/{app_id}/data-pipelines/transforms (admin kapsamı); okuma uçları users:read ile çalışır.
JavaScript dönüştürmesi
transform(record, context) fonksiyonu tanımlayın. Nesne dönerse kayıt güncellenir, null dönerse kayıt bilinçli
süzülür; başka bir dönüş veya istisna kaydı karantinaya gönderir. context: app_id, target, source, now.
function transform(record, context) {
if (record.properties.internal) return null;
record.properties.email = (record.properties.email || '').toLowerCase();
record.properties.total = Number(record.properties.price || 0) * Number(record.properties.qty || 1);
return record;
}Kod WebAssembly içinde çalışan bir QuickJS yorumlayıcısında, her çalıştırmada yeni ve yalıtılmış bir örnekte
yürütülür: require, process, dosya sistemi, ağ ve zamanlayıcılar yoktur. Sınırlar: kayıt başına 50 ms, toplu
çalıştırma 2 sn, bellek 16 MB, kod 20 KB. Süreyi veya belleği aşan kayıt js_timeout / js_memory koduyla
karantinaya alınır. console.log çıktısı yalnız önizlemede görünür. Kod kaydedilirken derlenir; transform
tanımlı değilse kayıt reddedilir.
Önizleme
Panelde kural editörünün Önizle düğmesi ya da POST /v1/apps/{app_id}/data-pipelines/transforms/preview örnek
kayıtlarla kuru çalıştırma yapar; hiçbir şey yazılmaz ve karantinaya alınmaz. Kaydedilmemiş bir tanım (transform),
tek bir kayıtlı dönüştürme (transform_id) veya app'in açık dönüştürmelerinin tümü çalıştırılabilir. Her kayıt için
sonuç (kept, dropped, failed), çıktı, hata kodu/yolu ve konsol satırları döner.
Kaynak bağlayıcıları
Webhook kaynağı size bir uç adresi verir: POST /hooks/data-sources/{id} (gövde en çok 1 MB, istek başına en
çok 1000 kayıt). Kimlik doğrulama iki moddan biridir:
signature(varsayılan):Pushizo-Signaturebaşlığı, giden webhook'larımızla aynı biçimde (t=<unix>,v1=<HMAC-SHA256>, imzalanan metin<t>.<gövde>, 5 dk tolerans).token:Authorization: Bearer <anahtar>veyaX-Pushizo-Token: <anahtar>.
Anahtar yalnız kaynak oluşturulduğunda ve yenilendiğinde bir kez gösterilir; şifreli saklanır.
HTTP pull kaynağı verdiğiniz https adresini 5–1440 dakikada bir çeker. İsteğe bağlı kimlik bilgisi bir başlığa
(varsayılan Authorization) yazılır ve şifreli saklanır. Özel ağ adresleri reddedilir, yönlendirme izlenmez, istek
10 sn ve 5 MB ile sınırlıdır. Sayfalama için next_cursor_path (yanıttaki sonraki imleç) ve cursor_param (sorgu
parametresi) verin; çalıştırma başına en çok 10 sayfa / 5000 kayıt. resume_cursor açıksa sonraki çalıştırma son
imleçten devam eder. Panelden veya POST …/sources/{id}/run ile hemen çalıştırılabilir.
Eşleme, ham kaydı olay veya kişiye çevirir:
{
"records_path": "data.items",
"event_name_path": "type",
"external_id_path": "customer.id",
"event_id_path": "id",
"occurred_at_path": "created_at",
"value_path": "total",
"properties_path": "attributes"
}properties_path boşsa kaydın tamamı özellik olur. Kişi kaynağında external_id_path (zorunlu), properties_path
ve tags_path kullanılır. Olayın kişisi external_id ile bulunur, yoksa oluşturulur. Aynı kaydın tekrar
çekilmesinde çift yazımı önlemek için hem event_id_path hem occurred_at_path eşleyin (olay kimliği ikisinden
türetilir). Kaynak kayıtları webhook_source / pull_source kaynağıyla dönüştürülür ve import olarak yazılır.
Karantina ve hata kaydı
Panel → Veri boru hattı → Karantina sekmesi hata veren kayıtları kod, alan yolu ve iletiyle listeler. Her dönüştürmenin hata sayacı ve son hata kodu tanımında görünür.
| Kod | Anlamı |
|---|---|
mapping_failed | Kaynak kaydı nesne değil veya eşlenemedi. |
invalid_path | Kuraldaki alan yolu geçersiz. |
cast_failed | Tür dönüştürülemedi (on_error: fail). |
rule_failed | Kural adımı uygulanamadı (ör. sayı olmayan değerde add). |
invalid_output | Sonuç yazılabilir değil (olay adı, kişi kimliği, özellik boyutu). |
js_error, js_invalid_return | JavaScript istisnası veya geçersiz dönüş. |
js_timeout, js_memory | Süre veya bellek sınırı aşıldı. |
write_failed | Yazım reddedildi (ör. etiket kotası). |
Kuralı düzelttikten sonra Yeniden işle (veya POST …/quarantine/reprocess, kimlik verilmezse en eski 500
bekleyen kayıt) kayıtları güncel dönüştürmelerle yeniden çalıştırır: başarılı olan yazılır, yine hata veren
bekleyende kalır. Kapat kaydı yeniden işlemeden kapatır. İşlenen ve kapatılan kayıtların içeriği silinir.
Karantina kişisel veri içerir: kullanıcı silindiğinde ilgili kayıtlar da silinir ve kayıtlar 30 gün sonra temizlenir.
Notlar
- Dönüştürme değişiklikleri birden çok API sunucusunda en geç 15 saniye içinde geçerli olur.
- Plan Growth altına düşerse tanımlar korunur ama uygulanmaz; webhook kaynağı
403, pull kaynağıskippeddöner. - HTTP pull zamanlayıcısı API sürecinde çalışır; bir replikada kapatmak için
DATA_PIPELINE_CONSUMER=false.