PushizoDocs

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

  1. Olay SDK'dan, public API'den, içe aktarmadan, Segment'ten veya bir kaynak bağlayıcısından gelir.
  2. App'in açık dönüştürmeleri sırayla (position) uygulanır. Bir dönüştürme hedefe (event veya person), 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.
  3. 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).

İşlemAçıklama
mapDeğeri başka alana kopyalar (alan eşleme).
renameDeğeri taşır, eski alanı siler.
removeAlanı siler (ör. gizli alan).
setSabit değer yazar (zenginleştirme).
template{{yol}} yer tutucularıyla metin üretir.
computelower, upper, trim, length, round, abs, add, multiply, now.
caststring, number, integer, boolean, date; dönüşmezse on_error: fail (karantina, varsayılan), null, keep.
filterKoş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-Signature baş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> veya X-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.

KodAnlamı
mapping_failedKaynak kaydı nesne değil veya eşlenemedi.
invalid_pathKuraldaki alan yolu geçersiz.
cast_failedTür dönüştürülemedi (on_error: fail).
rule_failedKural adımı uygulanamadı (ör. sayı olmayan değerde add).
invalid_outputSonuç yazılabilir değil (olay adı, kişi kimliği, özellik boyutu).
js_error, js_invalid_returnJavaScript istisnası veya geçersiz dönüş.
js_timeout, js_memorySüre veya bellek sınırı aşıldı.
write_failedYazı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ğı skipped döner.
  • HTTP pull zamanlayıcısı API sürecinde çalışır; bir replikada kapatmak için DATA_PIPELINE_CONSUMER=false.

Bu sayfada