FTP Bağlantısı
Genel Bakış
Amacı Nedir?
Connection (Bağlantı) tanımını merkezi tutarak FTP/SFTP/FTPS erişimini tüm Integration Flow adımlarında tutarlı hale getirir.
Dosya aktarımı yapan Connector adımlarında otomatik kimlik doğrulama ve SSL/TLS parametrelerini yeniden kullanarak yapılandırma süresini kısaltır.
Çalışma dizini (workingDir) kısıtlamasıyla sadece yetkili klasörlere erişilmesini sağlayarak veri sızıntısı riskini azaltır.
Yeniden deneme (retryCount) ve timeout değerleri sayesinde kararsız ağlarda bile aktarım başarısını yükseltir.
Ortam seçimi ile Test Connection yapılabilir; Environment Variable desteği ile host, port, username, password gibi alanlarda ${var} syntax kullanılabilir.
Çalışma Prensibi
Integration Flow veya Connector içerisinden FTP/SFTP/FTPS bağlantısı talep edildiğinde, sistem yapılandırılmış connection parametrelerini okur.
Kullanıcı adı ve parola ile hedef FTP dizinine erişim sağlanır. SSH anahtar tabanlı kimlik doğrulama desteklenmez.
Seçilen protokol üzerinden TCP katmanında dosya yükleme/indirme, listeleme veya silme işlemleri gerçekleştirilir.
İşlem tamamlandığında oturum kapatılır.
Bağlantı hatası, timeout veya authentication hatası durumunda tanımlı retryCount devreye girer, sonuç deployment loglarına yazılır.
Kullanım Alanları
Partner sistemlerinden gelen dosyaların belirli aralıklarla indirilmesi
Toplu rapor veya log dosyalarının düzenli olarak FTP sunucularına yüklenmesi
SFTP üzerinden finansal veri paylaşımı yapan dış servislerle entegrasyon
FTPS (Explicit) ile regülasyon gereği şifreli aktarım zorunluluğu bulunan kurum bağlantıları
İç ağdaki Legacy dosya aktarım sunucularının Integration Flow adımlarında kullanılması
Teknik Özellikler ve Yetenekler
Temel Özellikler
FTP, SFTP ve FTPS protokolleri tek bağlantı tanımı altında seçilebilir.
workingDir alanı ile bağlantının erişebileceği dizin sınırlandırılır.
retryCount ile ağ kesintilerinde otomatik yeniden deneme sağlanır.
Test Connection için ortam seçimi zorunludur; environment variable'lar ortam bazlı çözümlenir.
Connection'ı aktif veya pasif hale getirme (enable/disable toggle). Pasif durumda bağlantı kullanılamaz ancak yapılandırması saklanır.
İleri Düzey Özellikler
useImplicit ve useExplicit bayraklarıyla TLS el sıkışmasının nasıl yapılacağı belirlenir.
Bağlantı proje içinde tutulabilir veya Move to Global ile tüm projelerde erişilebilir kılınır.
ZIP import işlemlerinde 100 MB boyuta kadar FTP bağlantı tanımları içe alınabilir.
"Test Connection" butonu ile bağlantı parametrelerini kaydetmeden önce doğrulama imkanı. Test için ortam seçimi zorunludur.
Connection yapılandırmasını ZIP dosyası olarak export etme. Farklı ortamlara (Development, Test, Production) import etme. Versiyon kontrolü ve yedekleme imkanı.
Host, port, username, password, workingDir ve sslProtocol alanlarında ${variableName} syntax ile ortam değişkenleri kullanılabilir.
Connection Parametreleri
Zorunlu Parametreler
Açıklama: Connection adı (benzersiz olmalı)
Örnek Değer: Production_FTP
Notlar: Boşlukla başlamaz, özel karakterler kullanılmamalı
Açıklama: FTP/SFTP sunucusunun adresi
Örnek Değer: ftp.partner.local
Notlar: IPv4/IPv6 veya FQDN kabul edilir
Açıklama: Protokolün çalıştığı port
Örnek Değer: 21
Notlar: SFTP için 22, FTPS için 990 önerilir
Açıklama: Hedef sunucudaki kullanıcı adı
Örnek Değer: partner_sync
Notlar: Least privilege prensibine göre oluşturulmalı
Açıklama: Başlangıç çalışma dizini
Örnek Değer: /outbound
Notlar: İlgili kullanıcının erişim izni olmalı
Açıklama: Kullanılacak aktarım protokolü
Örnek Değer: FTP / SFTP / FTPS
Notlar: EnumFtpProtocol listesinden seçilir
Açıklama: Bağlantı zaman aşımı (sn)
Örnek Değer: 30
Notlar: Saniye cinsindendir
Açıklama: Yeniden deneme sayısı
Örnek Değer: 3
Notlar: Ağ kesintilerinde kaç tekrar yapılacağını belirtir
Açıklama: FTPS el sıkışmasında kullanılacak sürüm
Örnek Değer: TLS
Notlar: FTPS kullanımında zorunludur
İsteğe Bağlı Parametreler
Açıklama: Kullanıcı şifresi veya environment variable referansı
Varsayılan Değer: (Boş)
Önerilen Değer: ${variableName} syntax ile environment variable kullanımı
Açıklama: FTPS implicit el sıkışmasını aktive eder
Varsayılan Değer: false
Önerilen Değer: true (FTPS implicit gereken ortamlarda)
Açıklama: FTPS explicit STARTTLS sürecini aktive eder
Varsayılan Değer: true
Önerilen Değer: true (varsayılan; FTPS dışı senaryolarda false yapılabilir)
Kullanım Senaryoları
Durum: Tedarikçi her gece XML yükler
Çözüm: WorkingDir=/inbox, Protocol=SFTP, RetryCount=5
Beklenen Davranış: Gece job'ı dosyaları güvenli şekilde indirir
Durum: Banka sistemi FTPS implicit ister
Çözüm: UseImplicit=true, Port=990, SSL Protocol=TLS1.2
Beklenen Davranış: TLS el sıkışması başarılı olur, dosyalar şifreli taşınır
Durum: Eski sistem sadece FTP destekler
Çözüm: Protocol=FTP, Port=21, Timeout=45
Beklenen Davranış: Gateway klasik FTP üzerinden yükleme yapar
Durum: Uzun süren transferler
Çözüm: Timeout=90, Flow'da chunk upload
Beklenen Davranış: Uzun süren transferlerde kopma yaşanmaz
Durum: DR ortamına paralel kopya gönderilir
Çözüm: Ortam=Production, Host=dr-ftp.local veya environment variable ile
Beklenen Davranış: Ana ve DR sistemleri senkron tutulur
Durum: SOC ekibi SFTP ile log çeker
Çözüm: Ortam=Test, Protocol=SFTP, WorkingDir=/audit
Beklenen Davranış: Sadece audit klasörü erişilir
Connection Yapılandırma
Yeni FTP Bağlantısı Oluşturma
Yapılandırma Adımları
- Sol menüden Connection → FTP Bağlantısı bölümüne gidin.
- Sağ üstteki [+ Create] butonuna tıklayın.
Enable Status (Aktif Durumu):
- Toggle ile aktif/pasif durumu ayarlayın. Yeni connection'lar varsayılan olarak aktiftir.
Name (İsim) - Zorunlu:
- Örnek:
Production_FTP - Benzersiz isim girin, boşlukla başlamaz.
- Sistem otomatik kontrol eder. Yeşil tik: kullanılabilir. Kırmızı çarpı: mevcut isim.
Description (Açıklama):
- Örnek: "Partner FTP yüklemeleri"
- Maks. 1000 karakter.
- Connection'ın amacını açıklayın.
Sayfanın üst kısmındaki işlem butonları alanında, [<> Variable] butonunu kullanarak dinamik değer seçebilir, Global variable ifadeleri sayesinde connection parametrelerini sabit değer yerine değişken tabanlı yönetebilirsiniz. Detaylı bilgi için Dinamik Değişkenler sayfasını inceleyebilirsiniz.
- Dropdown menüden ortam seçin: Development, Test, veya Production.
- Test Connection için ortam seçimi zorunludur.
- Host & Port: Hedef FTP adresini girin, protokole göre port ayarlayın.
- Protocol: FTP, SFTP veya FTPS seçin.
- WorkingDir: Erişilecek klasörün tam yolunu yazın.
- Username/Password: Kullanıcı adı ve parola girin. Environment variable için Variable butonundan değişken seçip yapıştırabilirsiniz.
- UseImplicit / UseExplicit: FTPS el sıkışma şeklini seçin.
- SSL Protocol: TLS sürümünü belirleyin (örn. TLS1.2).
- Timeout: Ağ gecikmesine göre 30-90 sn arası ayarlayın.
- RetryCount: Kararsız bağlantılarda 3-5 arası önerilir.
- Kullanıcı adı/şifre veya environment variable kullanın.
- FTPS için gerekli sertifikaları trust store'a yükleyin (FTPS kullanıyorsanız).
- Uyarı: Production ortamında anonim FTP erişimine izin vermeyin.
- [Test Connection] butonuna tıklayın.
- Ortam seçili olduğundan emin olun.
- Bağlantı parametrelerinin doğru olup olmadığını test edin.
- Başarılı: Yeşil onay mesajı
- Başarısız: Hata detayları gösterilir
- Sağ üstteki [Save and Deploy] butonuna tıklayın.
Kontrol Listesi:
- Benzersiz isim
- Zorunlu alanlar dolu
- Test connection başarılı (önerilir)
Sonuç:
- Connection listeye eklenir
- Integration Flow ve Connector adımlarında kullanılabilir hale gelir
- Ortama göre aktif olur
Connection başarıyla oluşturuldu! Artık Integration Flow ve Connector adımlarında kullanabilirsiniz.
Connection'ı Silme
Connection'ı silmek için:
- Connection listesinde satır sonundaki ⋮ menüsünden Delete seçeneğini tıklayın.
- Onay dialogunda silme işlemini onaylayın.
Silmeden Önce Kontrol Edin:
- Integration Flow veya Connector adımlarında kullanılıyor olabilir.
- Gerekirse alternatif bir connection atayın.
- Silmeden önce Export ile yedek alın.
- Silmek yerine connection'ın aktif durumunu pasif hale getirin.
- Connection pasif olur ancak silinmez.
- Gerektiğinde aktif hale getirerek yeniden kullanabilirsiniz.
Connection'ı Dışa/İçe Aktarma
Bu adımda kullanıcı, mevcut connection'ları yedekleme, farklı ortamlara taşıma veya paylaşma amacıyla dışa aktarabilir (export) ya da daha önce dışa aktarılmış bir connection'ı tekrar içe aktarabilir (import). Bu işlem, sürüm yönetimi, test ve üretim ortamları arasında geçiş veya ekipler arası paylaşım süreçlerinde veri bütünlüğünü korumak için kullanılır.
Dışa Aktarma (Export)
- Connection listesinde satır sonundaki ⋮ menüsünden Export seçeneğini tıklayın.
- ZIP dosyası otomatik olarak indirilir.
Format: {Date}-ftp-integration-{ConnectionName}-export.zip
Örnek: 13 Nov 2025-ftp-integration-Production_FTP-export.zip
- Connection JSON dosyası
- Metadata bilgileri
- Bağımlılık bilgileri (örneğin sertifikalar, key store)
- Yedekleme
- Ortamlar arası taşıma (Test → Prod)
- Versiyonlama
- Ekip veya proje bazlı paylaşım
İçe Aktarma (Import)
- Ana listede [Import FTP Bağlantısı] butonuna tıklayın.
- İndirilen ZIP dosyasını seçin.
- Sistem kontrolleri: Format geçerli mi? İsim çakışması var mı? Bağımlılıklar mevcut mu?
- Ardından [Import] butonuna tıklayın.
Senaryo 1: İsim Çakışması → Eski connection'ın üzerine yazın veya yeni bir isimle oluşturun.
Senaryo 2: Eksik Bağımlılıklar → Eksik sertifikaları veya key store'ları önce oluşturun veya import sırasında çıkarın.
Connection'ın Kullanım Alanları
Adımlar:
- Connection'ı oluşturun
- Test Connection ile bağlantıyı doğrulayın
- Save and Deploy ile kaydedin ve etkinleştirin
- Connection'ın Enabled durumda olduğundan emin olun.
FTP/SFTP/FTPS protokolü ile dosya aktarımı gerektiren adımlarda connection seçilir. Örnek: "FTP Read File", "FTP List File" gibi adımlar. Bağlantı seçimi bu adımların yapılandırmasında yer alan Connection alanından yapılır. Aynı bağlantı, hem dosya gönderme hem alma adımlarında yeniden kullanılabilir.
Zamanlanmış görevlerde (ör. belirli aralıklarla dosya alma/gönderme, log arşivleme vb.) bağlantı seçilerek FTP/SFTP sunucularına erişim sağlanır. Connection değiştiğinde, job çalışma davranışı da buna göre güncellenir.
Connection Test özelliği ile bağlantının doğruluğu Integration Flow'dan bağımsız olarak kontrol edilebilir. Bu test hata ayıklama sürecinde kritik önem taşır.
Test sonuçları production aktarımının garantisi değildir; Integration Flow'u ayrıca test edin
Best Practices
Yapılması Gerekenler ve En İyi Uygulamalar
Kötü: Kullanıcıya root dizin erişimi vermek
İyi: Yalnızca gerekli klasöre izin vermek
En İyi: Her senaryo için ayrı workingDir tanımlayıp ACL ile sınırlandırmak
Kötü: Parolayı formda düz metin olarak saklamak
İyi: Environment variable kullanarak hassas bilgileri saklamak
En İyi: Variable butonu ile ${var} referansları kullanmak
Kötü: Varsayılan FTP'yi her ortamda kullanmak
İyi: Gerektiğinde SFTP veya FTPS seçmek
En İyi: Ortam bazlı protokol yönetip güvenlik gereksimiyle eşlemek
Kötü: Tüm ortamlarda aynı connection parametrelerini kullanmak
İyi: Her ortam için ayrı connection oluşturmak
En İyi: Environment seçeneğini kullanarak tek connection'da tüm ortamları yönetmek, ortamlar arası geçişte sadece environment değiştirmek
Kötü: Connection'ı test etmeden kaydetmek ve deploy etmek
İyi: Kaydetmeden önce Test Connection ile doğrulamak
En İyi: Her parametre değişikliğinden sonra test etmek, production'a geçmeden önce test ortamında tam entegrasyon testi yapmak
Güvenlik En İyi Uygulamaları
FTP sunucularını sadece Apinizer gateway IP aralığına açın, gerektiğinde pasif FTP port aralığını beyaz listeleyin
Transfer sonrası checksum doğrulaması yaparak beklenmeyen manipülasyonları yakalayın
Kullanıcı adı ve şifre gibi hassas bilgileri environment variable kullanarak saklayın. Kimlik bilgilerini kod veya konfigürasyon dosyalarına hardcode etmeyin. Periyodik olarak şifreleri güncelleyin
Production ortamında mutlaka SSL/TLS aktif edin. Self-signed sertifikalar sadece development ortamında kullanın. Sertifika expiration tarihlerini takip edin ve zamanında yenileyin
Connection yapılandırmasını sadece yetkili kullanıcıların değiştirmesine izin verin. Connection değişiklik loglarını saklayın. Kritik connection'lar için değişiklik approval süreci uygulayın
Kaçınılması Gerekenler
Neden kaçınılmalı: Kimlik doğrulama bypass edilir, veri sızıntısı olur
Alternatif: Kimlik bilgisi zorunlu kullanıcılar tanımlayın
Neden kaçınılmalı: Gereksiz silme/yazma yetkisi riski artırır
Alternatif: Salt okunur veya sadece gerekli dizinlere yetkili hesaplar kullanın
Neden kaçınılmalı: FTPS gereksinimi olan ortamda FTP seçimi regülasyon ihlali doğurur
Alternatif: Gereksinime göre SFTP/FTPS seçin, protokolü dökümante edin
Neden kaçınılmalı: Test verileri production sistemine yazılabilir, gerçek kullanıcılar etkilenebilir, güvenlik riski oluşur
Alternatif: Her ortam için ayrı connection oluşturun, environment parametresini kullanın, connection isimlerini ortama göre prefix ekleyerek ayırın (Test_, Prod_)
Neden kaçınılmalı: Ağ gecikmelerinde connection sürekli timeout olur, Entegrasyon adımları başarısız olur
Alternatif: Gerçek kullanım senaryolarına göre timeout değerlerini ayarlayın, network latency'yi ölçün ve timeout'ları buna göre belirleyin
Performans İpuçları
Öneri: Büyük dosyaları Integration Flow seviyesinde parçalara ayırın
Etki: Transfer süresi kısalır, yeniden deneme maliyeti düşer
Öneri: Firewall arkasında pasif FTP kullanın ve port aralığını daraltın
Etki: Ağ sorunları azalır, bağlantı stabilitesi artar
Öneri: Gerçek network latency'yi ölçün, timeout değerlerini buna göre ayarlayın, çok düşük veya çok yüksek timeout'lardan kaçının
Etki: Gereksiz beklemeler önlenir, hızlı fail-over sağlanır, kullanıcı deneyimi iyileşir
Sorun Giderme (Troubleshooting)
Directory Listing Başarısız
Yanlış workingDir, kullanıcının listeleme yetkisi yok veya firewall pasif port aralığını engelliyor olabilir.
WorkingDir değerini doğrulayın.
FTP kullanıcı izinlerini kontrol edin.
Pasif port aralığını açın.
SSL/TLS Negotiation Hatası
Yanlış sslProtocol değeri, sertifika süresi doldu veya UseImplicit/UseExplicit uyumsuz olabilir.
TLS sürümünü karşı tarafla hizalayın.
Sertifikayı yenileyin.
Doğru FTPS modunu seçin.
Connection Timeout
Network gecikmesi, hedef sistem yavaş yanıt veriyor veya timeout değeri çok düşük olabilir.
Network connectivity kontrol edin.
Hedef sistem sağlığını kontrol edin.
Timeout değerlerini artırın.
Connection loglarını inceleyin.
Authentication Failed
Yanlış kullanıcı adı/şifre, expired credentials veya yetki problemi olabilir.
Kimlik bilgilerini doğrulayın.
Hedef sistemde kullanıcının aktif olduğunu kontrol edin.
Gerekli yetkilerin verildiğini kontrol edin.
SSL/TLS sertifikalarını kontrol edin.
Connection Test Başarılı Ama Entegrasyon Akışı Hata Veriyor
Integration/Connector adımında farklı connection seçili olabilir, adım yanlış yapılandırılmış olabilir veya Flow/Job redeploy edilmemiş olabilir.
Connection'ın enable toggle'ının aktif olduğunu kontrol edin.
Integration Flow'da doğru connection'ın seçildiğini doğrulayın.
Connection'ı tekrar deploy edin.
Integration Flow veya Job'ı redeploy edin.
Gateway loglarını kontrol edin.
Sık Sorulan Sorular (SSS)
FTP ve SFTP için ayrı connection tanımlamak zorunda mıyım?
Aynı bağlantıda protokolü değiştirebilirsiniz ancak her protokol için ayrı ortam parametreleri oluşturmak izlenebilirliği artırır.
Çalışma dizinini sonradan değiştirmek akışları etkiler mi?
Evet, Flow'da kullanılan tüm dosya yolları yeni workingDir'e göre güncellenmelidir; aksi halde "dosya bulunamadı" hatası alırsınız.
Pasif FTP port aralığını nereden yönetebilirim?
Port aralığı FTP sunucusunda tanımlanır, gateway tarafında firewall'a aynı aralık açılmalıdır. Connection dokümanında bilgi amaçlı not düşebilirsiniz.
SFTP anahtar dosyasını nasıl bağlarım?
SFTP bağlantısı sadece kullanıcı adı ve parola ile kimlik doğrulaması destekler. SSH anahtar tabanlı kimlik doğrulama mevcut sürümde desteklenmemektedir.
Aynı bağlantıyı hem indirme hem yüklemede kullanabilir miyim?
Evet, yeter ki kullanıcı yetkileri her iki işleme izin versin; Integration Flow adımlarında aynı connection seçilebilir.
Aynı connection'ı birden fazla Integration Flow'da kullanabilir miyim?
Evet, aynı connection birden fazla Integration Flow veya Connector adımında kullanılabilir. Bu merkezi yönetim sağlar ve konfigürasyon tutarlılığını garanti eder. Ancak connection'da yapılan değişiklikler tüm kullanım yerlerini etkileyeceği için dikkatli olunmalıdır.
Test ve Production için farklı connection'lar mı oluşturmalıyım?
Evet, her ortam için ayrı connection oluşturmanız önerilir. Alternatif olarak environment parametresini kullanarak tek connection içinde tüm ortamları yönetebilirsiniz. Bu yaklaşım daha kolay yönetim ve daha az hata riski sağlar.
Test Connection başarılı ama Integration Flow'da çalışmıyor, neden?
Birkaç neden olabilir:
- Connection enable toggle'ı pasif olabilir
- Integration adımında farklı bir connection seçili olabilir
- Connection deploy edilmemiş olabilir
- Integration Flow henüz redeploy edilmemiş olabilir