Ana içeriğe geç

FTP Read Konnektör

FTP Read Konnektör Konfigürasyonu
Dosya Erişimi

FTP sunucularınız ya da farklı ortamlarınızdaki dosya içeriklerine erişebilirsiniz.

Dosya Arama

Belirli kriterlere ve desenlere göre dosya arayabilirsiniz.

Format Dönüşümü

Dosya içeriklerini farklı formatlarda (JSON, ZIP, MTOM) indirebilirsiniz.

Kullanım​

bilgi

Oluşturacağınız FTP dosya okuma konnektörü sayesinde, FTP sunucusundan dosya okuma işlemlerini gerçekleştirebilirsiniz. Bu konnektör, dosya adı desenlerine göre, joker karakter eşleştirmesi ve tam eşleşme gibi esnek arama kriterleri ile birlikte çeşitli formatlarda çıktı üretebilme imkanı sunarak ihtiyacınıza uygun çözümler geliştirmenizi sağlar.

Konnektör, JSON gövdeli HTTP POST isteği kabul eder. İstek gövdesi boş gönderilirse, varsayılan değerler kullanılır.

HTTP İsteği​

curl --location --request POST "https://<APINIZER_ACCESS_URL>/<RELATIVE_PATH>" \
  -H "Content-Type: application/json" \
  --data-raw '{"searchType": "WILDCARD", "searchPattern": "*.json", "returnType": "ALL_MATCHES", "outputFormat": "JSON_BASE64"}'

İstek Gövdesi Parametreleri​

Dosya Arama Ayarları
searchType

Tip: string

Varsayılan Değer: STARTS_WITH

Açıklama: Dosya adlarının nasıl aranacağını belirtir. Kullanılabilir seçenekler:

  • STARTS_WITH: Dosya adının verilen desenle başlayıp başlamadığını kontrol eder
  • EXACT_MATCH: Verilen dosya adı ile tam eşleşme kontrolü yapar
  • CONTAINS: Dosya adının içinde verilen deseni içerip içermediğini kontrol eder
  • ENDS_WITH: Dosya adının verilen desenle bitip bitmediğini kontrol eder
  • WILDCARD: Joker karakter eşleştirmesi kullanır (* herhangi bir dizi ile eşleşir, ? tek karakter ile eşleşir)
searchPattern

Tip: string

Varsayılan Değer: (boş - tüm dosyaları döndürür)

Açıklama: Aranacak dosya adı veya deseni. Kullanım searchType'a göre değişir:

  • WILDCARD için: *.json, dosya?.txt, fatura_*.pdf
  • ENDS_WITH için: .json, .pdf, .xml
  • STARTS_WITH için: fatura_, rapor, veri
  • CONTAINS için: 2025, test, _yedek
  • EXACT_MATCH için: rapor.pdf, ayar.json
caseInsensitive

Tip: boolean

Varsayılan Değer: true

Açıklama: Dosya adı aramasının büyük/küçük harf duyarlı olup olmayacağını belirler. true olduğunda "Dosya.txt" ve "dosya.txt" aynı kabul edilir.

returnType

Tip: string

Varsayılan Değer: ALL_MATCHES

Açıklama: Döndürülecek sonuç miktarını belirtir:

  • FIRST_MATCH: Sadece ilk eşleşen dosyayı indirir ve aramayı durdurur. Hızlı bir şekilde tek bir dosyaya ihtiyacınız olduğunda kullanışlıdır.
  • ALL_MATCHES: Tüm eşleşen dosyaları indirir. Birden fazla dosyayı işlemeniz gerektiğinde kullanın.
Dosya Boyutu Sınırlaması
maxFileSizeKB

Tip: integer

Varsayılan Değer: (sınır yok)

Açıklama: İndirilecek maksimum dosya boyutu kilobayt (KB) cinsinden. Bu boyuttan büyük dosyalar atlanır ve yanıta dahil edilmez.

Örnek: 10240 değeri sadece 10 MB'a (10240 KB) kadar olan dosyaların indirileceği anlamına gelir.

Kullanım Amacı: Çok büyük dosyaların indirilmesini ve bellek veya performans sorunlarına yol açmasını önler.

Çıktı Formatı Ayarları
outputFormat

Tip: string

Varsayılan Değer: JSON_BASE64

Açıklama: Dosya içeriklerinin hangi formatta döndürüleceğini belirtir:

  • JSON_BASE64: Dosya içerikleri JSON formatında Base64 kodlaması ile döndürülür. API entegrasyonları ve yapılandırılmış yanıt ihtiyacınız olduğunda en iyisidir.
  • MTOM: Dosyalar MTOM (Message Transmission Optimization Mechanism) formatında multipart SOAP mesajı olarak döndürülür. SOAP tabanlı entegrasyonlar için kullanışlıdır.
  • ZIP: Tüm eşleşen dosyalar tek bir ZIP arşivine paketlenir. Birden fazla veya büyük dosya indirmek için en verimli yöntemdir.
uyarı

MTOM veya ZIP formatı kullanılırken, eğer hiç dosya bulunamazsa, yanıt HTTP 404 durum kodu ve hata mesajı döndürür. Sadece JSON_BASE64 formatı boş dosya dizisi ile HTTP 200 döndürür.

Yanıt Formatı​

Yanıt formatı outputFormat parametresine göre değişir:

JSON_BASE64 Formatı (Varsayılan)​

Başarılı Yanıt:

{
  "count": 2,
  "files": [
    {
      "name": "fatura_2025_001.pdf",
      "data": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL...",
      "size": 245760
    },
    {
      "name": "fatura_2025_002.pdf",
      "data": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL...",
      "size": 198432
    }
  ]
}

Boş Yanıt (Dosya Bulunamadı):

{
  "count": 0,
  "message": "No files found",
  "files": []
}
bilgi

JSON_BASE64 formatında data alanı Base64 kodlanmış dosya içeriğini barındırır. Gerçek dosya içeriğine erişmek için bu veriyi decode etmeniz gerekir.

ZIP Formatı​

outputFormat değeri ZIP olarak ayarlandığında, tüm eşleşen dosyalar tek bir ZIP arşivine paketlenir ve binary veri olarak döndürülür.

Başlıklar:

  • Content-Type: application/zip
  • Content-Disposition: attachment; filename="ftp_files.zip"

Yanıt: Binary ZIP dosya verisi

uyarı

Eğer hiç dosya bulunamazsa, HTTP 404 durum kodu ve hata mesajı döndürür: "No files found"

MTOM Formatı​

outputFormat değeri MTOM olarak ayarlandığında, dosyalar MTOM formatında multipart SOAP mesajı olarak döndürülür.

Başlıklar:

  • Content-Type: multipart/related; boundary=...; type="application/xop+xml"

Yanıt: Dosya eklerini içeren multipart MTOM mesajı

uyarı

Eğer hiç dosya bulunamazsa, HTTP 404 durum kodu ve hata mesajı döndürür: "No files found"

Örnek Senaryolar​

Örnek 1: JSON Formatı - İlk Eşleşme​

Kullanım Senaryosu: "fatura_2025_" ile başlayan ilk dosyayı bul ve JSON formatında döndür. Maksimum 10 MB boyutundaki dosyaları kabul et.

İstek:

{
  "caseInsensitive": true,
  "searchType": "STARTS_WITH",
  "searchPattern": "fatura_2025_",
  "returnType": "FIRST_MATCH",
  "maxFileSizeKB": 10240,
  "outputFormat": "JSON_BASE64"
}

Yanıt:

{
  "count": 1,
  "files": [
    {
      "name": "fatura_2025_001.pdf",
      "data": "JVBERi0xLjQKJeLjz9MK...",
      "size": 245760
    }
  ]
}

Örnek 2: ZIP - Tüm Eşleşmeler​

Kullanım Senaryosu: Tüm PDF dosyalarını bul ve ZIP arşivi olarak indir.

İstek:

{
  "caseInsensitive": false,
  "searchType": "ENDS_WITH",
  "searchPattern": ".pdf",
  "returnType": "ALL_MATCHES",
  "outputFormat": "ZIP"
}

Yanıt: Tüm eşleşen PDF dosyalarını içeren binary ZIP dosyası.

Örnek 3: MTOM Formatı​

Kullanım Senaryosu: "payload.xml" adındaki dosyayı tam eşleşme ile bul ve SOAP entegrasyonu için MTOM formatında döndür.

İstek:

{
  "searchType": "EXACT_MATCH",
  "searchPattern": "payload.xml",
  "returnType": "FIRST_MATCH",
  "outputFormat": "MTOM"
}

Yanıt: Dosyanın eklendiği multipart MTOM mesajı.

Örnek 4: Joker Karakter Deseni - Tüm JSON Dosyaları​

Kullanım Senaryosu: Dizindeki tüm JSON dosyalarını joker karakter deseni kullanarak bulma.

İstek:

{
  "searchType": "WILDCARD",
  "searchPattern": "*.json",
  "returnType": "ALL_MATCHES",
  "outputFormat": "JSON_BASE64"
}

Bu desen şu dosyalarla eşleşir: ayar.json, veri.json, rapor.json

Örnek 5: Karmaşık Joker Karakter Deseni​

Kullanım Senaryosu: Tek karakter joker karakteri ile belirli desene uyan dosyaları bulma.

İstek:

{
  "searchType": "WILDCARD",
  "searchPattern": "rapor_2025_0?.pdf",
  "caseInsensitive": true
}

Bu desen şu dosyalarla eşleşir:

  • ✅ rapor_2025_01.pdf
  • ✅ rapor_2025_09.pdf
  • ❌ rapor_2025_10.pdf (0'dan sonra iki basamak)
  • ❌ rapor_2024_01.pdf (farklı yıl)

Örnek 6: İçinde Belirli Metin Geçen Dosyalar​

Kullanım Senaryosu: Adında "yedek" geçen tüm dosyaları bulma.

İstek:

{
  "searchType": "CONTAINS",
  "searchPattern": "yedek",
  "caseInsensitive": true,
  "maxFileSizeKB": 50000
}

Bu desen şu dosyalarla eşleşir: gunluk_yedek.zip, yedek_2025.tar.gz, vt_yedek_tam.sql

Örnek 7: Büyük/Küçük Harfe Duyarlı Arama​

Kullanım Senaryosu: Tam harf eşleşmesi ile dosya bulma.

İstek:

{
  "searchType": "STARTS_WITH",
  "searchPattern": "Rapor",
  "caseInsensitive": false
}

Bu desen:

  • ✅ Rapor_2025.pdf ile eşleşir
  • ❌ rapor_2025.pdf ile eşleşmez (küçük harf 'r')
  • ❌ RAPOR_2025.pdf ile eşleşmez (tümü büyük harf)

Hata Yönetimi​

JSON_BASE64 Formatı​

Her zaman HTTP 200 durum kodu döndürür. Dosya bulunamadığında:

{
  "count": 0,
  "message": "No files found",
  "files": []
}

ZIP ve MTOM Formatları​

Dosya bulunamadığında HTTP 404 durum kodu döndürür:

Durum Kodu: 404 Not Found

Yanıt Gövdesi: "No files found"

En İyi Uygulamalar​

maxFileSizeKB Kullanın

Çok büyük dosyaların indirilmesini ve bellek sorunlarına yol açmasını önlemek için her zaman makul bir maxFileSizeKB sınırı belirleyin.

Doğru Formatı Seçin
  • API entegrasyonları ve yapılandırılmış yanıt için JSON_BASE64 kullanın
  • Birden fazla veya büyük dosya indirirken ZIP kullanın
  • MTOM'u sadece SOAP tabanlı entegrasyonlar için kullanın
FIRST_MATCH Kullanın

Sadece bir dosyaya ihtiyacınız olduğunda, performansı artırmak için returnType: "FIRST_MATCH" kullanın. İlk eşleşmeden sonra arama durur.

Joker Karakterler
  • * sıfır veya daha fazla karakter ile eşleşir
  • ? tam olarak bir karakter ile eşleşir
  • Karmaşık desenler için birleştirin: dosya_*.??? şu dosyalarla eşleşir dosya_veri.txt, dosya_test.pdf

Performans İpuçları​

bilgi
  • FIRST_MATCH kullanımı: Sadece bir dosyaya ihtiyacınız varsa, ilk eşleşmeden sonra arama durduğu için performansı artırır
    • maxFileSizeKB sınırı: Bellek kullanımını kontrol altında tutar ve çok büyük dosyaların indirilmesini engeller
    • Spesifik desenler: Genel desenler yerine mümkün olduğunca spesifik desenler kullanın (örn: fatura_*.pdf yerine fatura_2025_*.pdf)
    • Case sensitivity: Gereksiz yere caseInsensitive: false kullanmaktan kaçının, özellikle Türkçe karakterlerle çalışırken
En son tarihinde güncellendi