Giriş

Bulut depolama alanında dosyaları yükleyin ve yönetin, otomatik optimizasyon ile.

🎯 Bu modül ne yapar?

FileUploading modülü, OneEntry bulut depolama alanında dosyaları yüklemenizi, geri almanızı ve silmenizi sağlar - resimler, PDF'ler, videolar, belgeler ve otomatik optimizasyon ve CDN dağıtımı ile her türlü dosya türü.

Bunu bulut depolama yöneticiniz olarak düşünün - dosyaları bir kez yüklersiniz ve OneEntry bunları depolar, resimleri otomatik olarak optimize eder ve hızlı bir şekilde CDN üzerinden sunar.

📖 Basit Açıklama

Kullanıcıların bir uygulama oluşturduğunuzu hayal edin:

📸 Profil fotoğraflarını yükleyin - otomatik boyutlandırma ve optimizasyon
📄 Belgeleri yükleyin - PDF'leri, DOC'ları güvenli bir şekilde depolayın
🖼️ Ürün resimlerini yükleyin - her ürün için birden fazla resim
🎥 Videoları yükleyin - video içeriğini depolayın ve akışını sağlayın
📎 Ekleri yükleyin - her türlü dosya türü

Kendi depolamanızı yönetmek yerine:

✅ Dosyaları OneEntry bulutuna yükleyin
✅ Otomatik resim optimizasyonu (boyutlandırma, sıkıştırma)
✅ Dünyada hızlı CDN dağıtımı
✅ Varlık türüne göre organize edin (ürün, kullanıcı, sayfa)
✅ Anında indirme URL'leri alın
✅ Artık ihtiyaç duyulmayan dosyaları silin

Gerçek dünya örneği:

FileUploading olmadan (manuel):
- AWS S3 bucket kurun ❌
- CDN yapılandırın ❌
- Resim optimizasyon kodu yazın ❌
- Dosya izinlerini yönetin ❌
- İmzalı URL'ler oluşturun ❌

FileUploading ile (otomatik):
- Dosyayı yükle → İndirme URL'sini al ✅
- Resimler otomatik olarak optimize edildi ✅
- CDN dağıtımı yerleşik ✅
- Kolay dosya yönetimi ✅

✨ Temel Kavramlar

Dosya Yükleme Nedir?

Dosya yükleme, dosyaları bulut depolama alanında saklamaktır:

Yükleme - Dosyayı OneEntry bulutuna gönderin
Depolama - Dosyalar bulutta güvenli bir şekilde saklanır
CDN - Kullanıcılara yakın sunuculardan hızlı dağıtım
Optimizasyon - Resimler otomatik olarak sıkıştırılır ve boyutlandırılır
URL - Kalıcı indirme bağlantısını alın

Desteklenen Dosya Türleri

Herhangi bir dosya türünü yükleyin:

Kategori	Dosya Türleri	Otomatik Optimizasyon
Resimler	JPG, PNG, GIF, WebP, SVG	Evet (boyutlandırma, sıkıştırma)
Belgeler	PDF, DOC, DOCX, XLS, XLSX	Hayır (olduğu gibi saklanır)
Videolar	MP4, MOV, AVI, WebM	Hayır (olduğu gibi saklanır)
Arşivler	ZIP, RAR, TAR, GZ	Hayır (olduğu gibi saklanır)
Diğer	Herhangi bir dosya türü	Hayır (olduğu gibi saklanır)

Resim Optimizasyonu

Resim yüklerken, OneEntry şunları yapabilir:

📐 Boyutlandırma - Boyutları azaltma (örneğin, maksimum 1920px genişlik)
🗜️ Sıkıştırma - Dosya boyutunu azaltma (daha küçük, daha hızlı)
🖼️ Format - Optimal formata dönüştürme (WebP)
📱 Duyarlı - Birden fazla boyut oluşturma

Örnek:

Orijinal: 5MB, 4000x3000px
↓ (otomatik optimize)
Optimize edilmiş: 200KB, 1920x1440px

📋 Bilmeniz Gerekenler

Yükleme Parametreleri

Dosyaları yüklerken, şunları belirtebilirsiniz:

await FileUploading.upload(file, {
  entity: 'product',     // Varlık türü (zorunlu)
  id: 123,               // Varlık ID'si (isteğe bağlı)
  type: 'image',         // Dosya türü ipucu (isteğe bağlı)
  width: 1920,           // Resimler için maksimum genişlik (isteğe bağlı)
  height: 1080,          // Resimler için maksimum yükseklik (isteğe bağlı)
  compress: true         // Resimleri sıkıştır (isteğe bağlı)
});

Parametrelerin açıklaması:

file - Dosya nesnesi (girişten veya sürükleyip bırakmadan)
entity - Kategori: product, page, block, user, form, general
id - Dosyayı ilişkilendirmek için varlık ID'si (örneğin, ürün ID'si)
type - Dosya türü ipucu (genellikle otomatik olarak tespit edilir)
width - Piksel cinsinden maksimum genişlik (sadece resimler için)
height - Piksel cinsinden maksimum yükseklik (sadece resimler için)
compress - Sıkıştırmayı etkinleştir (sadece resimler için)

Yükleme Yanıtı

Yükledikten sonra, şunları alırsınız:

{
  filename: "abc123-photo.jpg",              // Benzersiz dosya adı
  downloadLink: "https://cdn.../photo.jpg",  // CDN URL'si
  size: 204800,                              // Dosya boyutu (bayt)
}

Önemli alanlar:

downloadLink - Bu URL'yi <img>, <a>, <video> etiketlerinde kullanın
filename - Bunu daha sonra dosyayı silmek için kaydedin
size - Dosya boyutu bayt cinsinden (204800 bayt = 200KB)

Dosya Organizasyonu En İyi Uygulamaları

Dosyaları varlık türüne göre organize edin

Resim Optimizasyon Seçenekleri

Resimlerin nasıl optimize edileceğini kontrol edin:

Seçenek	Ne Yapar	Örnek
width	Maksimum genişlik (oranı korur)	`width: 1920`
height	Maksimum yükseklik (oranı korur)	`height: 1080`
compress	Dosya boyutunu azalt	`compress: true`

Oran korunur:

Orijinal: 4000x3000 (4:3 oranı)
Genişlik ile: 800
Sonuç: 800x600 (hala 4:3 oranı)

Dosyaları Silme

Her zaman varlık, id ve dosya adını sağlayarak silin:

await FileUploading.delete({
  entity: 'product',
  id: productId,
  filename: 'abc123-photo.jpg'
});

Neden üçü de? Dosyalar varlık → id → dosya adı ile organize edilir.

📊 Hızlı Referans Tablosu - Yöntemler

Yöntem	Ne Yapar	Ne Zaman Kullanılır
upload()	Dosyayı bulut depolama alanına yükler	Kullanıcı resim, belge yükler
getFile()	Dosya bilgilerini alır (boyut, tür, URL)	Dosyanın var olup olmadığını kontrol et
delete()	Depolamadan dosyayı siler	Eski dosyaları kaldırmak için

❓ Sıkça Sorulan Sorular (SSS)

Hangi dosya türlerini yükleyebilirim?

Herhangi bir dosya türü desteklenmektedir:

Resimler: JPG, PNG, GIF, WebP, SVG, BMP, TIFF
Belgeler: PDF, DOC, DOCX, XLS, XLSX, PPT, TXT
Videolar: MP4, MOV, AVI, WebM, MKV
Arşivler: ZIP, RAR, TAR, GZ
Diğer: Herhangi bir dosya türü

Sadece resimler otomatik olarak optimize edilir. Diğer dosyalar olduğu gibi saklanır.

Maksimum dosya boyutu nedir?

OneEntry plan limitlerinizi kontrol edin. Genellikle:

Ücretsiz plan: Dosya başına 5MB
Ücretli planlar: Dosya başına 50MB - 100MB

En iyi uygulama: Yüklemeden önce resimleri optimize edin, boyutunu azaltın.

Dosyalar kalıcı olarak mı saklanır?

Evet, dosyalar manuel olarak FileUploading.delete() ile silene kadar saklanır.

Önemli: Kullanılmayan dosyaları temizleyerek depolama alanı tasarrufu yapın.

Ön uçtan (tarayıcıdan) dosya yükleyebilir miyim?

Evet! Dosya girişi veya sürükleyip bırakma kullanın.

Yüklemeden önce dosyaları nasıl doğrularım?

Dosya türünü ve boyutunu kontrol edin.

Bir varlık için yüklenen tüm dosyaların listesini alabilir miyim?

Bu SDK ile doğrudan değil. Şunları yapmanız gerekir:

Yükleme sırasında dosya adlarını takip edin (veritabanına kaydedin)
Dosyaları listelemek için OneEntry Admin API'yi kullanın

En iyi uygulama: Yüklenen dosya adlarını veritabanınıza kaydedin.

Yükleme hatalarını nasıl yönetirim?

Her zaman try/catch kullanın.

Dosyaları doğrudan CDN'ye yükleyebilir miyim?

Hayır, yüklemeler OneEntry API'si üzerinden geçer, bu da:

Dosyayı doğrular
Resimleri optimize eder (eğer etkinleştirilmişse)
Bulutta saklar
CDN URL'sini döner

Bu, güvenliği ve optimizasyonu sağlar.

Bir varlığı (ürün, kullanıcı) silersem dosyalara ne olur?

Dosyalar depolamada kalır varlık silinse bile.

En iyi uygulama: Varlığı silmeden önce dosyaları silin.

Resimleri tam boyutlara göre yeniden boyutlandırabilir miyim?

Hayır, bozulmayı önlemek için oran her zaman korunur.

Nasıl çalışır:

width: 800, height: 600 belirlersiniz
Resim 800x600 içinde uyacak şekilde boyutlandırılır
Oran korunur

Örnek:

Orijinal: 1000x500 (2:1 oranı)
Genişlik ile: 800, yükseklik ile: 600
Sonuç: 800x400 (hala 2:1 oranı, 800x600 içinde uyuyor)

💡 Önemli Notlar

Dosya Güvenliği

Yüklenen dosyalar CDN üzerinden herkese açıktır:

✅ Resimler, kamu belgeleri için harika
⚠️ Hassas dosyaları yüklemeyin (şifreler, özel veriler)

Özel dosyalar için:

Kimlik doğrulama ile OneEntry Admin API'yi kullanın
Ya da kendi erişim kontrolünüzü uygulayın

Depolama Limitleri

Depolama kullanımınızı izleyin:

Her planın depolama limitleri vardır
Kullanılmayan dosyaları düzenli olarak temizleyin
Yüklemeden önce resimleri sıkıştırın

Resim Optimizasyon İpuçları

En iyi sonuçlar için:

✅ Yüksek kaliteli orijinal dosyaları yükleyin (OneEntry'nin optimize etmesine izin verin)
✅ Web resimleri için compress: true kullanın
✅ Uygun boyutları ayarlayın (örneğin, kahraman resimleri için 1920px, küçük resimler için 500px)
❌ Zaten sıkıştırılmış resimleri yüklemeyin (kalite kaybı)

Tavsiye edilen boyutlar:

Profil fotoğrafları: 500x500
Ürün resimleri: 1920x1920
Kahraman afişleri: 1920x1080
Küçük resimler: 300x300

🎓 En İyi Uygulamalar

Yüklemeden önce dosya türünü ve boyutunu doğrulayın
Dosyaları organizasyon için varlık ID'leri ile ilişkilendirin
Web resimleri için sıkıştırmayı etkinleştirin
Yükleme hatalarını nazikçe yönetin
Daha sonra dosyaları silmek için dosya adlarını kaydedin
Kullanılmayan dosyaları düzenli olarak temizleyin
Kullanıcılara yükleme ilerlemesini gösterin

FileUploading modülünün tanımı


const { FileUploading } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

🔗 İlgili Belgeler

Ürün Modülü - Ürün resimlerini yükleyin
Kullanıcı Modülü - Kullanıcı profil fotoğraflarını yükleyin
Sayfalar Modülü - Sayfa içerik dosyalarını yükleyin
Bloklar Modülü - Blok içerik dosyalarını yükleyin

Giriş

🎯 Bu modül ne yapar?​

📖 Basit Açıklama​

✨ Temel Kavramlar​

Dosya Yükleme Nedir?​

Desteklenen Dosya Türleri​

Resim Optimizasyonu​

📋 Bilmeniz Gerekenler​

Yükleme Parametreleri​

Yükleme Yanıtı​

Dosya Organizasyonu En İyi Uygulamaları​

Resim Optimizasyon Seçenekleri​

Dosyaları Silme​

📊 Hızlı Referans Tablosu - Yöntemler​

❓ Sıkça Sorulan Sorular (SSS)​

Hangi dosya türlerini yükleyebilirim?​

Maksimum dosya boyutu nedir?​

Dosyalar kalıcı olarak mı saklanır?​

Ön uçtan (tarayıcıdan) dosya yükleyebilir miyim?​

Yüklemeden önce dosyaları nasıl doğrularım?​

Bir varlık için yüklenen tüm dosyaların listesini alabilir miyim?​

Yükleme hatalarını nasıl yönetirim?​

Dosyaları doğrudan CDN'ye yükleyebilir miyim?​

Bir varlığı (ürün, kullanıcı) silersem dosyalara ne olur?​

Resimleri tam boyutlara göre yeniden boyutlandırabilir miyim?​

💡 Önemli Notlar​

Dosya Güvenliği​

Depolama Limitleri​

Resim Optimizasyon İpuçları​

🎓 En İyi Uygulamalar​

FileUploading modülünün tanımı​

🔗 İlgili Belgeler​