ONLYOFFICE API Entegrasyon Gücünü Keşfedin: Docs 9.1 ve DocSpace 3.5 Yenilikleri

Daha sonra, bir JavaScript kodu ile editörü başlatın. Bu kod, dokümanın detaylarını, kullanıcının bilgilerini ve editör ayarlarını içerecektir:

const ONLYOFFICE_DOCS_SERVER = "http://";

function initOnlyofficeEditor(documentTitle, documentFileUrl, callbackUrl, documentKey, user) {
    var config = {
        "document": {
            "fileType": documentFileUrl.split('.').pop(), // Dosya türünü URL'den al
            "key": documentKey || generateDocumentKey(), // Benzersiz doküman anahtarı
            "title": documentTitle,
            "url": documentFileUrl,
            "permissions": {
                "edit": true, // Düzenleme izni ver
                "download": true,
                "print": true
            }
        },
        "documentType": getDocumentType(documentFileUrl.split('.').pop()), // "text", "spreadsheet", "presentation"
        "editorConfig": {
            "callbackUrl": callbackUrl,
            "lang": "tr", // Türkçe dil ayarı
            "mode": "edit", // "view" veya "edit"
            "user": {
                "id": user.id,
                "name": user.name
            },
            "customization": {
                "about": true, // Hakkında penceresini göster
                "feedback": false // Geri bildirim butonunu gizle
                // Docs 9.1 ile gelen yeni customization seçenekleri buraya eklenebilir
            }
        }
    };

    // Yeni Docs 9.1 özellikleri: Örneğin, belirli alanları düzenlenemez yapma
    // config.editorConfig.region = "A1:C10"; // Sadece bu bölgeyi düzenlenebilir yapar (örnek)

    var docEditor = new DocsAPI.DocEditor("placeholder", config);

    console.log("ONLYOFFICE Editör başlatıldı:", documentTitle);
}

// Yardımcı fonksiyonlar
function generateDocumentKey() {
    return Date.now().toString(); // Basit bir anahtar oluşturma
}

function getDocumentType(fileExtension) {
    if (["docx", "docm", "dotx", "dotm", "doc", "dot", "rtf", "odt"].includes(fileExtension)) {
        return "text";
    }
    if (["xlsx", "xlsm", "xltx", "xltm", "xls", "xlt", "ods"].includes(fileExtension)) {
        return "spreadsheet";
    }
    if (["pptx", "pptm", "potx", "potm", "ppt", "pot", "odp"].includes(fileExtension)) {
        return "presentation";
    }
    return "text"; // Varsayılan
}

// Uygulamanızdan çağrılacak örnek:
// initOnlyofficeEditor(
//     "Proje Raporu.docx",
//     "http:///documents/ProjeRaporu.docx",
//     "http:///onlyoffice/callback",
//     "rapor-belge-1234",
//     { id: "1", name: "Ayşe Yılmaz" }
// );

Adım 3: Callback İşleyicisini Uygulamanızda Kurma

Bu en kritik adımlardan biridir. ONLYOFFICE Doküman Sunucusu, dokümandaki değişiklikleri kaydetmek veya belgeyi kapatmak gibi olaylarda uygulamanızın callbackUrl'sine POST isteği gönderir. Uygulamanız bu isteği almalı, değişiklikleri işlemeli ve dokümanı kendi depolama alanınıza kaydetmelidir.

// Node.js (Express) için basit bir callback örneği
const express = require('express');
const bodyParser = require('body-parser');
const fs = require('fs');
const app = express();

app.use(bodyParser.json());

app.post('/onlyoffice/callback', async (req, res) => {
    const { status, url, key } = req.body;

    console.log(ONLYOFFICE Callback alındı. Doküman Key: ${key}, Durum: ${status});

    if (status === 2 || status === 6) { // Durum 2: Belge kaydedildi, Durum 6: Belge otomatik kaydedildi (zorunlu kaydetme ile)
        try {
            // ONLYOFFICE sunucusundan güncel belgeyi indir
            const response = await fetch(url);
            if (!response.ok) {
                throw new Error(HTTP hata kodu: ${response.status});
            }
            const arrayBuffer = await response.arrayBuffer();
            const buffer = Buffer.from(arrayBuffer);

            // Belgeyi kendi depolama alanınıza kaydet
            const filePath = ./documents/${key}.docx; // Veya uygun dosya adı
            fs.writeFileSync(filePath, buffer);

            console.log(Belge başarıyla kaydedildi: ${filePath});
            res.json({ error: 0 }); // Başarılı yanıt
        } catch (error) {
            console.error('Callback işlenirken hata oluştu:', error);
            res.json({ error: 1, message: error.message }); // Hata yanıtı
        }
    } else {
        res.json({ error: 0 }); // Diğer durumlar için başarı yanıtı gönder
    }
});

app.listen(3000, () => {
    console.log('Sunucu 3000 portunda dinliyor.');
});

Bu örnek, temel bir Node.js sunucusunda callback'in nasıl işleneceğini göstermektedir. Gerçek bir uygulamada, güvenlik doğrulamasını (JWT token kontrolü gibi) ve daha robust hata yönetimini eklemeniz önemlidir. Docs 9.1 ile gelen yeni callback parametreleri, bu süreci daha da detaylandırmanıza olanak tanır.

Mobil Uyumlu Entegrasyon Nasıl Yapılır?

Mobil uyumluluk, modern web uygulamaları için bir lüks değil, bir zorunluluktur. ONLYOFFICE editörünü entegre ederken, farklı ekran boyutlarına ve cihazlara uyum sağlayan responsive bir tasarım benimsemek kritik öneme sahiptir. Bu, kullanıcılarınızın tabletlerde, telefonlarda ve masaüstü bilgisayarlarda tutarlı ve optimize edilmiş bir deneyim yaşamasını sağlar.

1. Viewport Meta Etiketi: Her şeyden önce, HTML sayfanızın bölümüne aşağıdaki meta etiketini ekleyin. Bu, tarayıcıya sayfanın cihazın genişliğine göre ölçeklenmesi gerektiğini bildirir:

2. Esnek Düzenler ve Akışkan Boyutlandırma: CSS'de sabit piksel değerleri yerine yüzde (%), vw/vh (viewport width/height) birimleri veya flexbox/grid gibi responsive düzen tekniklerini kullanın. ONLYOFFICE editörünün gömüldüğü
   elementinin genişliğini ve yüksekliğini dinamik olarak ayarlayın. Örneğin:

   #placeholder {
       width: 100%; /* Sayfanın tüm genişliğini kapla */
       height: 80vh; /* Ekran yüksekliğinin %80'ini kapla */
       /* Diğer CSS kuralları */
   }

3. Media Queries Kullanımı: Belirli ekran boyutları için farklı stil kuralları tanımlamak için CSS media queries kullanın. Bu, küçük ekranlarda editörün boyutunu veya çevresindeki diğer UI elementlerini ayarlamak için idealdir. Örneğin, daha küçük ekranlarda bazı yan panelleri gizlemek isteyebilirsiniz:

   /* Genel stiller */
   #editor-container {
       width: 90%;
       margin: 20px auto;
   }
   
   /* Küçük ekranlar için (örn: 768px altı tablet ve telefonlar) */
   @media (max-width: 768px) {
       #editor-container {
           width: 100%; /* Küçük ekranlarda tam genişlik */
           margin: 0;
           padding: 10px;
       }
       /* Mobil cihazlarda bazı butonları gizle veya yeniden düzenle */
       .mobile-hidden {
           display: none;
       }
   }
   
   /* Çok küçük ekranlar için (örn: 480px altı telefonlar) */
   @media (max-width: 480px) {
       #editor-container {
           height: 100vh; /* Dikeyde tam ekran */
       }
       /* Daha küçük font boyutları vb. */
   }
   

ONLYOFFICE editörünün kendisi, farklı ekran boyutlarına otomatik olarak uyum sağlayan responsive bir tasarıma sahiptir. Ancak, onu barındıran uygulamanızın da mobil uyumlu olması, bütünsel bir kullanıcı deneyimi sunmak için şarttır. Bu adımları takip ederek, ONLYOFFICE entegrasyonunuzun her cihazda sorunsuz çalışmasını sağlayabilirsiniz.

İleri Düzey Optimizasyon ve Güvenlik İpuçları Nelerdir?

ONLYOFFICE API entegrasyonunuzu temel seviyede kurduktan sonra, sıra performans, ölçeklenebilirlik ve güvenlik gibi ileri düzey konulara gelir. Bu bölümde, daha deneyimli geliştiriciler için entegrasyonlarını bir sonraki seviyeye taşıyacak kritik ipuçları ve en iyi uygulamaları ele alacağız. Docs 9.1 ve DocSpace 3.5'in sunduğu yetenekleri tam olarak kullanarak, daha sağlam ve verimli bir sistem oluşturabilirsiniz.

Performans Optimizasyonu: Hızı ve Akıcılığı Maksimize Etme

1. Önbellekleme (Caching): Doküman sunucusu ile uygulamanız arasındaki veri trafiğini azaltmak için önbellekleme stratejileri uygulayın. Özellikle sık erişilen veya az değişen statik kaynaklar (CSS, JS dosyaları) ve belirli doküman sürümleri için önbellekleme kullanmak, yükleme sürelerini önemli ölçüde kısaltabilir. Ters proxy (Nginx gibi) yapılandırması, bu tür önbellekleme için etkili bir yöntemdir.
2. Donanım ve Ağ Optimizasyonu: ONLYOFFICE Doküman Sunucusu'nun yeterli CPU, RAM ve disk IO kaynaklarına sahip olduğundan emin olun. Özellikle çok sayıda eşzamanlı kullanıcının beklendiği durumlarda güçlü bir sunucu kritik öneme sahiptir. Ayrıca, Doküman Sunucusu ile uygulamanız arasındaki ağ gecikmesini minimumda tutmak için sunucuları coğrafi olarak yakın yerleştirmek faydalı olacaktır.
3. Doküman Boyutu ve Karmaşıklığı: Büyük ve karmaşık belgeler (örneğin, çok sayıda resim, karmaşık tablolar, makrolar içerenler) daha yavaş yüklenebilir ve düzenlenebilir. Mümkünse, kullanıcıların daha küçük ve yönetilebilir belgelerle çalışmasını teşvik edin veya belgeyi parçalara ayırma stratejileri geliştirin.
4. HTTP/2 Kullanımı: ONLYOFFICE Doküman Sunucusu ile uygulamanız arasında HTTP/2 protokolünü kullanarak birden fazla isteği tek bir bağlantı üzerinden gönderebilir, bu da performansı artırabilir.

Güvenlik İyileştirmeleri: Entegrasyonunuzu Sağlamlaştırma

Güvenlik, API entegrasyonlarının en hassas noktalarından biridir. Hassas doküman verilerini işlerken, olası güvenlik açıklarını en aza indirmek için proaktif adımlar atılmalıdır.

1. JWT (JSON Web Token) Doğrulaması: ONLYOFFICE Doküman Sunucusu ile uygulamanız arasındaki tüm iletişimi JWT ile güvence altına alın. Bu, yetkisiz erişimi engeller ve iletişimdeki verilerin bütünlüğünü sağlar. Hem Doküman Sunucusu'ndan gelen callback'leri doğrulamak hem de uygulamanızdan editöre gönderilen yapılandırma verilerini imzalamak için JWT kullanın. Docs 9.1, bu doğrulamaların daha esnek yönetilmesine olanak tanır.

   // ONLYOFFICE config objesine JWT ekleme örneği (Sunucu tarafında oluşturulmalıdır)
   // Bu token, sunucu tarafında oluşturulup istemciye gönderilmelidir.
   config.token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkb2N1bWVudCI6eyJmaWxlVHlwZSI6ImRvY3giLCJrZXkiOiJyYXBvci1iZWxnZS0xMjM0IiwidGl0bGUiOiJQcm9qZSBSYXBvcnQuZG9jeiJ9LCJlZGl0b3JDb25maWciOnsiY2FsbGJhY2tVcmwiOiJodHRwOi8vPCUzQ19BUEBfU0VSVkVSX0lQJTNFL29ubHlvZmZpY2UvY2FsbGJhY2sifSwiaWF0IjoxNjc4NjQxNDU1fQ.some_signature_here";
   

2. Callback URL Doğrulaması: ONLYOFFICE'tan gelen callback isteklerinin gerçekten beklediğiniz kaynaktan geldiğini doğrulamak için IP beyaz listeleme veya özel bir API anahtarı kullanımı gibi ek doğrulama adımları uygulayın.
3. HTTPS Kullanımı: Tüm iletişim kanallarınızın (Doküman Sunucusu, uygulamanız, kullanıcı tarayıcısı) HTTPS üzerinden şifrelenmiş olduğundan emin olun.
4. İzin Yönetimi: Docs 9.1 ve DocSpace 3.5, daha granüler izin yönetimi sunar. Kullanıcıların yalnızca ihtiyaç duydukları belgelere veya özelliklere erişebildiğinden emin olun. Örneğin, belirli bir belgeyi yalnızca görüntüleme modunda açmak için "edit": false ayarlamasını kullanın. DocSpace API'leri ile kullanıcı ve grup bazında dosya ve klasör izinlerini programatik olarak yönetin.
5. Giriş Filtrelemesi ve Çıkış Kaçışı: Doküman adları, kullanıcı girdileri gibi verileri işlerken XSS (Cross-Site Scripting) ve SQL Injection gibi saldırılara karşı koruma sağlamak için her zaman giriş filtrelemesi ve çıkış kaçışı tekniklerini uygulayın.

Bu ileri düzey ipuçları, ONLYOFFICE API entegrasyonunuzun sadece işlevsel değil, aynı zamanda yüksek performanslı ve güvenli olmasını sağlayacaktır. Modern uygulamaların gerektirdiği bu standartları karşılamak, kullanıcı güvenini artırırken, sisteminizin uzun ömürlü ve sorunsuz çalışmasını temin edecektir.

Sonuç: Geleceğin Entegrasyonları ve Sıkça Sorulan Sorular

ONLYOFFICE Docs 9.1 ve DocSpace 3.5 güncellemeleri, API entegrasyonu alanında önemli bir sıçramayı temsil ediyor. Bu yenilikler, işletmelerin ve geliştiricilerin mevcut iş akışlarına yalnızca bir belge düzenleyici eklemekle kalmayıp, aynı zamanda belge yönetimi, işbirliği ve süreç otomasyonunu kökten dönüştürmelerine olanak tanıyor. Daha esnek API'ler, geliştirilmiş kontrol mekanizmaları ve genişletilmiş DocSpace yetenekleri sayesinde, entegre çözümler artık sadece güçlü değil, aynı zamanda daha güvenli, verimli ve kullanıcı odaklı hale geliyor.

Bu makalede, ONLYOFFICE API'nin temel kavramlarından başlayarak, Docs 9.1 ve DocSpace 3.5 ile gelen spesifik yeniliklere, gerçek dünya senaryolarına ve adım adım entegrasyon rehberine değindik. Ayrıca, mobil uyumluluk ve ileri düzey performans ve güvenlik optimizasyonları gibi kritik konuları da ele aldık. Gelecekte, yapay zeka entegrasyonları, daha akıllı otomasyon ve özel dikey çözümler için daha derin entegrasyon yetenekleri görmeye devam edeceğimiz kesin. ONLYOFFICE, bu alandaki sürekli yatırımlarıyla, geliştiricilere ve işletmelere daha önce hayal bile edemeyecekleri entegrasyon imkanları sunmayı sürdürüyor. Şimdi, bu güçlü araçları kullanarak kendi benzersiz çözümlerinizi oluşturma ve iş süreçlerinizi "güçlendirme" zamanı.

ONLYOFFICE API Hakkında Sıkça Sorulan Sorular (SSS)

ONLYOFFICE Doküman Sunucusu ve ONLYOFFICE DocSpace arasındaki temel fark nedir?

ONLYOFFICE Doküman Sunucusu, asıl çevrimiçi düzenleme motorudur. Belgeleri tarayıcıda görüntülemek ve düzenlemek için gereken tüm işlevleri sağlar ve genellikle mevcut bir doküman yönetim sistemine (DMS) entegre edilir. Kendisi bir depolama veya kullanıcı yönetim sistemi içermez, sadece düzenleme işlevselliğini sunar.

ONLYOFFICE DocSpace ise, Doküman Sunucusu'nun yeteneklerini temel alan, ancak aynı zamanda entegre bir doküman yönetim sistemi, işbirliği araçları, kullanıcı ve çalışma alanı yönetimi sunan kapsamlı bir platformdur. DocSpace, hem dış kullanıcılarla güvenli dosya paylaşımı hem de iç ekipler arasında merkezi bir işbirliği merkezi olarak tasarlanmıştır. DocSpace API'leri, bu depolama ve yönetim işlevlerine programatik erişim sağlar.

Docs 9.1'deki yeni API'ler ile hangi tür özelleştirmeleri yapabilirim?

Docs 9.1 ile birlikte gelen yeni API'ler, editörün kullanıcı arayüzü ve davranışları üzerinde daha fazla kontrol sağlar. Örneğin, editorConfig parametreleri aracılığıyla belirli araç çubuğu butonlarını gizleyebilir, belge içinde belirli alanları düzenlenemez hale getirebilir (içerik kontrolü gibi), yeni callback'ler ile dosya kaydetme veya kapatma olaylarını daha detaylı izleyebilir ve hatta onPaste gibi olay işleyicileriyle yapıştırma işlemlerini kontrol edebilirsiniz. Bu sayede, entegre ettiğiniz editörün uygulamanızın genel görünümüne ve iş akışına daha iyi uyum sağlamasını garantilersiniz.

ONLYOFFICE API entegrasyonunun güvenliğini nasıl sağlayabilirim?

Entegrasyon güvenliği için birkaç temel adım bulunmaktadır: Öncelikle, Doküman Sunucusu ile uygulamanız arasındaki tüm iletişimi HTTPS üzerinden şifreleyin. İkinci ve en kritik adım, JWT (JSON Web Token) kullanarak tüm API isteklerini doğrulamaktır. Bu, yetkisiz erişimi engeller ve verilerin bütünlüğünü sağlar. Ayrıca, uygulamanızın callback URL'sine gelen isteklerin ONLYOFFICE Doküman Sunucusu'ndan geldiğini doğrulamak için IP beyaz listeleme veya özel anahtarlar kullanabilirsiniz. Son olarak, kullanıcı izinlerini dikkatlice yöneterek (örneğin, sadece görüntüleme veya düzenleme izni verme) hassas verilere erişimi kısıtlayın.

Mobil cihazlarda ONLYOFFICE entegrasyonu nasıl bir deneyim sunar?

ONLYOFFICE editörü responsive bir tasarıma sahiptir, bu da farklı ekran boyutlarına ve cihazlara otomatik olarak uyum sağlayabildiği anlamına gelir. Kendi uygulamanızın HTML'inde viewport meta etiketini kullanarak ve CSS media queries ile responsive tasarım prensiplerini uygulayarak, mobil cihazlarda optimize edilmiş bir deneyim sunabilirsiniz. Bu sayede, kullanıcılar akıllı telefonlarında veya tabletlerinde bile belgeleri sorunsuz bir şekilde görüntüleyebilir ve düzenleyebilirler, tıpkı masaüstü deneyiminde olduğu gibi.