Connector Yönetimi ve Senkronizasyon

Connector, bir sisteme erişim sağlayan teknik adaptörden fazlasıdır. Kaynağın hangi bölümünün alınacağını, hangi kimlikle okunacağını, değişiklik ve silmelerin nasıl izleneceğini, içeriğin hangi Space'e gideceğini ve erişim sınırlarının nasıl korunacağını tanımlayan veri hattıdır.

Bu rehber connector yaşam döngüsünü uçtan uca ele alır:

Kaynak seçimi → Yetki → Kapsam → İlk keşif → Senkronizasyon
             → Ayrıştırma → İndeksleme → Doğrulama → İzleme → Kapatma

Önce entegrasyon türünü ayırın

Knowentra'da aynı servis adı iki farklı amaçla kullanılabilir:

Bir SharePoint veya Google Drive bağlantısı bilgi senkronizasyonu için kullanılabilir; aynı sağlayıcının workflow operation'ları dosya oluşturabilir veya paylaşımı değiştirebilir. Bu iki yetkiyi aynı credential ve aynı risk sınıfında yönetmeyin.

Senkronizasyon mu, canlı erişim mi?

Hibrit yaklaşım sık kullanılır: politika ve uzun belgeler indekslenir; bakiye, stok veya ticket durumu gibi hızla değişen alanlar canlı okunur. Birleştirilen cevapta her verinin kaynağı ve yaşı korunmalıdır.

Adım 1 — Connector kayıt formunu hazırlayın

Bağlantıyı oluşturmadan önce şu alanları kaydedin:

Amaç ve kapsam onaylanmadan “tüm drive”, “tüm site” veya tenant-geneli yetki istemeyin.

Adım 2 — Kaynak kapsamını keşfedin

İlk bağlantıda doğrudan tam senkronizasyon başlatmayın. Önce salt-okunur keşif çalıştırın:

• Erişilebilir site, klasör, kanal veya proje sayısı
• Tahmini dosya/kayıt ve toplam veri hacmi
• Dosya türü, boyut ve yaş dağılımı
• Taslak, arşiv, çöp kutusu ve kişisel içerik konumları
• Kaynak ACL ve paylaşım linki yapısı
• Değişiklik zamanı veya delta cursor desteği
• Silinme/tombstone olayının nasıl bildirildiği
• API rate limit ve sayfalama davranışı

Keşif raporu içerik değerlerini değil mümkün olduğunca metadata ve toplamları göstermelidir. Örneklem gerekiyorsa veri sahibiyle ve düşük riskli klasörle sınırlandırın.

Include ve exclude kuralları

Pozitif allowlist, geniş bir kökten negatif filtrelemeye göre daha güvenlidir:

include:
  /Policies/Published/**

exclude:
  **/Drafts/**
  **/Archive/**
  **/*.tmp
  **/~$*

Filtre sırası, büyük/küçük harf davranışı, sembolik link/kısayol ve alt klasör mirasını test edin. Kaynak yeniden adlandırıldığında kuralın sessizce daha geniş alanı kapsamamasına dikkat edin.

Adım 3 — Kimlik ve credential modelini seçin

Servis hesabı

Periyodik bilgi senkronizasyonu için çoğunlukla uygundur:

• Kişiden bağımsız yaşam döngüsü
• Dar, salt-okunur kapsam
• Merkezi rotasyon
• Açık sahiplik ve audit

Kullanıcı OAuth bağlantısı

Kullanıcı adına canlı erişimde gerekli olabilir:

• Kaynaktaki kişisel yetki korunabilir.
• Consent ve token yenileme yönetilmelidir.
• Kullanıcı ayrıldığında bağlantı sona erebilir.
• Workflow'un uzun süreli sahipliği kişiye bağlanmamalıdır.

On-behalf-of / delegation

Kaynak sistem destekliyorsa kullanıcının gerçek yetkisiyle sorgu yapılabilir. Token exchange, audience, scope ve kullanıcı bağlamı her çağrıda doğrulanmalıdır.

Adım 4 — İlk bağlantıyı doğrulayın

Credential kaydedildikten sonra:

1. Kimlik ve hedef tenant doğrulanır.
2. Yalnız izinli root/site/project listelenir.
3. Tek bir düşük riskli örnek kaynak okunur.
4. Yazma veya yönetim operation'larının kullanılamadığı kontrol edilir.
5. Secret'ın log ve kullanıcı arayüzüne dönmediği doğrulanır.
6. Rate-limit ve token-expiry bilgisi kaydedilir.
7. Bağlantı testi audit olayına bağlanır.

“Connection successful” yalnız kimlik doğrulamasını gösterebilir. Gerçek scope ve dosya okuma testi ayrıca yapılmalıdır.

Adım 5 — Hedef ve sahipliği belirleyin

Senkronize içerik bir organizasyon, departman ve bilgi tabanı/Space sınırına bağlanmalıdır:

Kaynak connector
  → organizasyon
  → departman
  → bilgi tabanı
  → izinli Space/agent

Bir kaynak birden fazla departmanda gerekiyorsa aynı veriyi kontrolsüzce kopyalamak yerine paylaşım ve sahiplik modelini belirleyin. Kaynak kaldırıldığında bütün türev indekslerin nasıl bulunacağını kaydedin.

Her obje için provenance metadata'sı taşıyın:

source_system
connector_id
source_object_id
source_url
source_parent_id
source_revision / etag
source_updated_at
synced_at
content_hash
permission_revision

Bu bilgiler deduplication, kaynak gösterme, silme ve olay incelemesi için gereklidir.

Adım 6 — İlk tam senkronizasyonu planlayın

İlk full sync'i küçük bir pilot kapsamla başlatın:

1. Kaynak sayısını ve byte hacmini ölçün.
2. Sayfalama boyutu ve worker concurrency'yi düşük ayarlayın.
3. API limitleri için rate-limit bütçesi belirleyin.
4. Dosyaları indir, tür ve boyut kontrolü yapın.
5. Ayrıştırma, chunk ve embedding'i ayrı durumlarla izleyin.
6. Yeni indeks tamamlanmadan kullanıcılara kısmi sonucu açıp açmayacağınıza karar verin.
7. Kaynak ve indeks sayılarını reconciliation ile karşılaştırın.
8. Pilot doğrulandıktan sonra kapsamı kademeli genişletin.

Sync durum modeli

Tek bir success/failed alanı yetersizdir:

discovered → fetched → parsed → chunked → embedded → indexed
                    ↘ quarantined / failed

Bir dosyanın fetch edilmesi aranabilir olduğu anlamına gelmez. UI ve operasyon metrikleri son başarılı aşamayı göstermelidir.

Adım 7 — Artımlı senkronizasyon

Kaynak destekliyorsa delta cursor, değişiklik token'ı, webhook veya updated_at + stable ID kullanın.

Checkpoint şunları içermelidir:

• Connector ve kaynak scope revision'ı
• Cursor/token veya son güvenli zaman penceresi
• Son sayfanın stabil anahtarı
• Başlangıç ve bitiş zamanı
• İşlenen, atlanan, başarısız ve silinen obje sayısı
• Kaynak API revision'ı

Checkpoint yalnız bütün sayfa ve türev yazımlar başarıyla tamamlandıktan sonra ilerletilir. Önce cursor'ı kaydedip sonra indeks yazmak, hata anında belge atlanmasına yol açar.

Zaman penceresi kullanılıyorsa

Saat kayması ve aynı timestamp'e sahip kayıtlar için overlap kullanın:

önceki_başarılı_zaman - güvenlik_penceresi
    → şimdi - kaynak_gecikme_penceresi

Tekrar gelen kayıtları source_object_id + revision/content_hash ile idempotent işleyin.

Adım 8 — Ayrıştırma ve içerik güvenliği

Her dosya veya kayıt:

• İzin verilen tür ve maksimum boyut kontrolünden geçer.
• Zararlı dosya ve gerekiyorsa makro taramasından geçer.
• Şifreli/bozuk dosyada görünür hata üretir.
• Metin, tablo, sayfa ve başlık yapısı mümkün olduğunca korunarak ayrıştırılır.
• Prompt injection içeriği “talimat” değil güvenilmeyen kaynak metni olarak işaretlenir.
• Metadata ve kaynak bağlantısını korur.
• Gereksiz embedded obje veya izleme parametresini temizler.

OCR kullanılan belgelerde güven skoru ve sayfa bilgisi saklanmalıdır. Düşük güvenli çıkarım, kesin politika maddesi gibi agent bağlamına verilmemelidir.

Adım 9 — Chunk, embedding ve indeksleme

Chunk stratejisi kaynak türüne göre değişir:

Her chunk kaynak obje, revision, konum ve ACL metadata'sını korumalıdır. Embedding modeli veya chunk stratejisi değiştiğinde aynı indeks üzerine sessizce karışık vektör yazmayın; yeni bir index revision oluşturup doğruladıktan sonra atomik geçiş yapın.

Adım 10 — ACL ve görünürlük

Üç yaklaşım vardır:

1. Kapsam bazlı: Connector yalnız belirli departman/Space için onaylı içerik alır.
2. ACL aynalama: Kaynak kullanıcı/grup izinleri indekse taşınır ve sorguda uygulanır.
3. Canlı yetki kontrolü: Retrieval anında kaynak sisteme yetki sorulur.

Kaynağın ACL modeli tam taşınamıyorsa bunu açık risk olarak kaydedin. “İçerik kurum içi” olduğu için tüm organizasyona açmayın.

Yetki değişikliği

İçerik değişmediğinde bile ACL değişebilir. Permission revision'ı ayrı izleyin ve yüksek riskli kaynaklarda erişim kaldırmayı normal içerik sync'inden daha hızlı işleyin.

Adım 11 — Değişiklik ve deduplication

Her obje için:

• Sabit kaynak kimliğiyle eşleştirin; dosya adına güvenmeyin.
• etag, revision veya content hash değişmediyse tekrar embedding yapmayın.
• Yeniden adlandırmayı sil + yeni obje yerine metadata güncellemesi olarak tanıyın.
• Taşınan objede parent/ACL kapsamını yeniden değerlendirin.
• Aynı içeriğin farklı kaynaklarda bulunmasının beklenen mi duplicate mi olduğunu belirleyin.
• Version history'nin tamamını değil yalnız onaylı/current revision'ı indeksleyin.

Hash eşitliği, izin ve metadata eşitliği anlamına gelmez. İçerik aynı kalsa da ACL veya kaynak konumu değişmiş olabilir.

Adım 12 — Silme semantiği

Kaynak silme olayı en riskli sync davranışlarından biridir:

Kaynakta görünmüyor
├── gerçekten silindi
├── connector yetkisi kayboldu
├── scope/filter değişti
├── geçici API/sayfalama hatası
└── kaynak taşındı veya yeniden adlandırıldı

Tek bir eksik liste sonucuyla indeks içeriğini topluca silmeyin.

Güvenli silme akışı

1. Tombstone/delta delete varsa doğrulayın.
2. Yoksa iki başarılı taramada eksik olmasını veya doğrudan kaynak lookup'ını kullanın.
3. Objeyi önce pending_delete/quarantined olarak işaretleyin.
4. Retrieval'dan hemen çıkarıp saklama süresince geri alınabilir tutun.
5. Türev chunk ve vektörleri aynı source ID ile bulun.
6. Saklama kuralı sonunda hard delete uygulayın.
7. Sayı ve hash reconciliation ile orphan kalmadığını doğrulayın.

Connector scope daraltılması ile kaynaktaki gerçek silmeyi audit kaydında ayırın.

Adım 13 — Hata, retry ve karantina

Poison document sürekli kuyruğu kilitlememelidir. Maksimum denemeden sonra karantinaya alın, veri sahibine görünür kılın ve diğer objelerin devam etmesine izin verin.

Adım 14 — Reconciliation

Periyodik olarak kaynak ve hedefi karşılaştırın:

Toplam sayılar tek başına yetmez. Stabil örneklemde source ID, revision, hash, ACL ve retrieval sonucunu karşılaştırın.

Adım 15 — Tazelik ve SLO

“Sync çalışıyor” yerine ölçülebilir hedefler koyun:

Discovery lag = kaynak değişim zamanı → connector'ın görme zamanı
Processing lag = discovery → indeks hazır
Permission lag = ACL kaldırma → retrieval'dan çıkma
Deletion lag = kaynak silme → türev verinin kaldırılması

Örnek SLO:

• Değişikliklerin %95'i 45 dakika içinde aranabilir.
• Kritik erişim kaldırmalarının %99'u 10 dakika içinde uygulanır.
• Karantinadaki dosya 1 iş günü içinde sahiplenilir.
• Başarısız connector 15 dakika içinde alarm üretir.

Dashboard kaynak zamanı ile Knowentra synced_at zamanını ayrı göstermelidir.

Adım 16 — İzleme ve alarm

• Son başarılı sync ve checkpoint yaşı
• Sync süresi ve işlenen obje/byte
• Kaynak API hata ve rate-limit oranı
• Token expiry ve consent iptali
• Fetch/parse/embed/index başarı oranları
• Queue depth ve en yaşlı iş
• Karantina ve pending delete sayısı
• Source/index reconciliation farkı
• Retrieval'da stale revision oranı
• ACL/permission update gecikmesi

Alarmı yalnız “job failed” olayına bağlamayın. Job teknik olarak başarılı olup 10.000 belge yerine 12 belge almış olabilir; ani hacim düşüşü veya artışı da alarm üretmelidir.

Adım 17 — Değişiklik yönetimi

Şu değişiklikler yeni bir connector revision ve kontrollü doğrulama gerektirir:

• Root/site/klasör kapsamı
• Include/exclude filtresi
• Credential veya OAuth scope
• Kaynak API sürümü
• Parser veya OCR sürümü
• Chunk stratejisi
• Embedding modeli
• Hedef bilgi tabanı/Space
• ACL mapping
• Silme ve saklama kuralı
• Schedule veya concurrency

Değişikliği önce dry-run discovery ile değerlendirin: eklenecek, güncellenecek ve silinecek obje sayısını gösterin. Büyük silme planını çift onaya bağlayın.

Adım 18 — Credential rotasyonu

1. Yeni credential'ı aynı dar scope ile oluşturun.
2. Staging veya connection testinde tenant ve izinleri doğrulayın.
3. Connector'ı kısa süre durdurun veya atomik referans değiştirin.
4. Yeni credential ile küçük artımlı sync çalıştırın.
5. Checkpoint ve kaynak kimliğinin değişmediğini doğrulayın.
6. Eski token/secret'ı iptal edin.
7. Audit ve runbook kaydını güncelleyin.

Rotasyon yeni connector oluşturmamalı veya tüm içeriği duplicate etmemelidir.

Adım 19 — Connector'ı kapatma

Connector silme ile içerik silme aynı karar değildir:

1. Yeni sync işleri ve webhook subscription'larını durdurun.
2. Aktif/queue işleri tamamlayın veya güvenli iptal edin.
3. Son checkpoint ve reconciliation raporunu saklayın.
4. İndeks içeriğinin korunacağı, arşivleneceği veya silineceğini veri sahibine onaylatın.
5. Türev chunk, embedding ve dosyaları provenance ile bulun.
6. Credential ve consent'i iptal edin.
7. Kaynak tarafındaki app/webhook yetkilerini kaldırın.
8. Saklama politikası sonunda veriyi silin ve kanıtlayın.

Operasyon runbook'u

Connector 401/403 veriyor

1. Secret değerini loglamadan expiry/consent durumunu kontrol edin.
2. Tenant, audience ve scope'un değişmediğini doğrulayın.
3. Kaynak admininin servis hesabı veya uygulama iznini kaldırıp kaldırmadığını inceleyin.
4. Credential'ı güvenli yöntemle yenileyin.
5. Son başarılı checkpoint'ten artımlı devam edin; gereksiz full sync başlatmayın.

Belge güncellendi ama yanıtta eski

1. Kaynak updated_at/revision ile connector kaydını karşılaştırın.
2. Checkpoint'in değişikliği kapsayıp kapsamadığını kontrol edin.
3. Fetch, parse, embed ve index aşamalarını ayrı inceleyin.
4. Aktif index revision ve cache durumunu doğrulayın.
5. Retrieval sonucundaki source revision'ı karşılaştırın.

Çok sayıda belge silinmek üzere

1. Silme işini dondurun.
2. Kaynak API health, pagination, credential ve filter revision'ını kontrol edin.
3. Önceki discovery sayılarıyla farkı çıkarın.
4. Örnek source ID'leri doğrudan kaynaktan sorgulayın.
5. Gerçek kapsam daraltmasıysa veri sahibinden onay alın.
6. Karantina sürecini kullanın; doğrudan hard delete yapmayın.

Kalite kontrol listesi

• Connector türü: sync, canlı erişim veya workflow operation olarak sınıflandı.
• İş, veri ve teknik sahipler belli.
• Kaynak kapsamı pozitif allowlist ile daraltıldı.
• Credential en az yetkili ve kişiden bağımsız where appropriate.
• İlk keşif raporu hacim, tür, ACL ve limitleri gösteriyor.
• Hedef departman, bilgi tabanı ve Space açık.
• Source ID, revision, hash ve provenance korunuyor.
• Full sync pilot ve kademeli yürütülüyor.
• Checkpoint yalnız başarılı türev yazımdan sonra ilerliyor.
• Parser, chunk ve embedding sürümleri izleniyor.
• ACL değişiklikleri içerik değişikliğinden bağımsız işleniyor.
• Rename, move, duplicate ve delete semantiği test edildi.
• Toplu silme karantina ve onay içeriyor.
• Hata sınıfına göre retry/karantina uygulanıyor.
• Reconciliation ve tazelik SLO'ları ölçülüyor.
• Hacim anomalisi ve checkpoint yaşı alarm üretiyor.
• Rotasyon duplicate veya full-sync kaybı oluşturmuyor.
• Kapatma planı credential ve türev veriyi kapsıyor.

Sonraki adımlar

• Mevcut katalog için Desteklenen Entegrasyonlar
• Bilgi işleme için RAG Sistemi
• Dosya yönetimi için Belge Yükleme
• Workflow operation'ları için Workflow Tasarım Rehberi
• Agent araçları için Araç Bağlama ve MCP