Veri Kaynakları (Data Sources)

Yönetim Paneli → Bağlantılar → Veri Kaynakları (/settings/connectors) ekranı, harici sistemlerinizi salt-okuma olarak bilgi tabanınıza (RAG) bağlar. Kaynak sistemlerde hiçbir değişiklik/silme yapılmaz — yalnız okunur ve indexlenir.

Genel akış

1. Yönetim Paneli → Bağlantılar → Veri Kaynakları'nı açın. Üstte Bağlı Kaynaklar listesi, altta Yeni Bağlantı Ekle bölümü vardır.
2. Eklemek istediğiniz kaynak türünü seçin (SQL · Google Drive · Dropbox · Notion · Zendesk).
3. Her kaynak formunun en üstünde bir Bağlantı nasıl yapılır? düğmesi vardır — o kaynağa özel adımları ve alan açıklamalarını panelden de görürsünüz.
4. Alanları doldurup Kaydet ve bağla'ya basın. Bağlı her kaynağın satırında İçerik (indekslenen dokümanları gözat), Test (bağlantıyı doğrula), Senkronize (yeniden çek), Webhook (webhook adresini kopyalar), Düzenle ve Sil düğmeleri vardır.
5. Senkron aralığı (dk) ile ne sıklıkta yeniden çekileceğini, Tam yeniden senkron ile de tam tazelemeyi ayarlarsınız.

Bağlanma yolları (OAuth kaynakları)

OAuth ile bağlanan kaynaklar (Google Drive, Dropbox, Notion) için yollar:

Aşağıda her kaynak için ayrıntılı adımlar var. BYO'da tek-tık akışı için panele yalnızca Client ID + Client secret girmeniz yeterlidir.

Veritabanları (SQL)

Salt-okuma SQL kaynakları: PostgreSQL · MySQL · SQL Server (MSSQL). Bir SELECT sorgusunun sonucu satır satır indexlenir.

Adım adım: salt-okur kullanıcı oluşturma

SemAgent'ın veritabanınızda hiçbir şeyi değiştirememesi için yalnızca SELECT yetkili yeni bir kullanıcı açın (mümkünse bir read-replica üzerinde). Motorunuza göre:

PostgreSQL:

CREATE USER semagent_ro WITH PASSWORD 'guclu-bir-parola';
GRANT CONNECT ON DATABASE veritabani_adi TO semagent_ro;
GRANT USAGE ON SCHEMA public TO semagent_ro;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO semagent_ro;
-- ileride eklenecek tablolar da otomatik okunabilsin:
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO semagent_ro;

MySQL / MariaDB:

CREATE USER 'semagent_ro'@'%' IDENTIFIED BY 'guclu-bir-parola';
GRANT SELECT ON veritabani_adi.* TO 'semagent_ro'@'%';
FLUSH PRIVILEGES;

SQL Server (MSSQL):

CREATE LOGIN semagent_ro WITH PASSWORD = 'guclu-bir-parola';
USE veritabani_adi;
CREATE USER semagent_ro FOR LOGIN semagent_ro;
ALTER ROLE db_datareader ADD MEMBER semagent_ro;

1. Yukarıdaki komutları çalıştırıp kullanıcıyı oluşturun (parolayı kendiniz belirleyin).
2. Sunucunuz IP kısıtlıysa izin vermeniz gereken adresleri [email protected] adresinden isteyin; bu adreslerden gelen bağlantıya izin verin (güvenlik duvarı / pg_hba.conf / bulut "authorized networks").
3. Panelde host, port, database, user, password alanlarını doldurun.
4. Sorgu alanına indekslenecek içeriği döndüren bir SELECT (veya WITH) yazın — ör. ürün, SSS ya da bilgi tablonuz. Yazma sorguları reddedilir.
5. Artımlı çekim için Artımlı kolon'a bir güncelleme zamanı sütunu (updated_at) girin; yalnız değişen satırlar çekilir.
6. Kaydet ve bağla → Test ile doğrulayın.

Bulut depolama & dokümanlar

Google Drive, Dropbox ve Notion. Bağlanmanın yolları: (1) platformun merkezi tek-tık OAuth'u (operatör kurmuşsa); (2) kendi OAuth uygulamanızla tek-tık (BYO — önerilen; Google Drive ve Dropbox): panele yalnızca Client ID + Client secret girip "Kaydet ve Bağlan"a basarsınız, SemAgent onay akışını sizin uygulamanızla koşar (refresh_token'ı elle üretmenize gerek yok); (3) elle token (kendiniz üretip yapıştırırsınız). BYO'da aşağıdaki redirect URI'yi uygulamanıza girmeniz şarttır; girmezseniz redirect_uri_mismatch hatası alırsınız. Girdiğiniz Client secret şifreli saklanır ve panele geri gösterilmez.

Google Drive

Tek tık: Google Drive formundaki "Kendi OAuth uygulamanızla bağlanın (önerilen)" kutusunda "Neyi indeksleyelim?" seçimini yapıp "Kaydet ve Bağlan"a basın → Google onay ekranında hesabınızı seçip izni verin. Client ID ve Client secret alanlarını boş bırakırsanız SemAgent'in merkezi uygulaması kullanılır (operatör kurmuşsa); o zaman kendi OAuth uygulamanızı oluşturmanıza gerek yoktur. "Yalnız seçtiğim dosyalar" modunda, bağlandıktan sonra kart üzerindeki "Dosya Seç" ile açılan Google Picker'dan indekslenecek dosyaları seçersiniz. "Access blocked / redirect_uri_mismatch" alıyorsanız sorun giderme'ye bakın.

Kendi OAuth uygulamanızla (BYO) — Google Cloud Console adım adım

Google, OAuth ekranını yeni Google Auth Platform arayüzüne taşıdı (console.cloud.google.com/auth). Sıra şöyle:

1. Proje seçin/oluşturun: üstteki proje seçiciden bir proje seçin ya da New Project ile oluşturun. Organization (Kuruluş) — kişisel Gmail hesabında genelde "No organization" olur; bu normaldir, öylece bırakın. Google Workspace hesabıysanız kuruluşunuz seçili gelir.
2. Drive API'yi etkinleştirin: APIs & Services → Library → Google Drive API → Enable.
3. Consent screen / Branding: sol menü Google Auth Platform → Branding → App name (ör. SemAgent Data Source), User support email, Developer contact email girin → Save.
4. Audience (Hedef kitle): Google Auth Platform → Audience →
   • User type: kişisel Gmail veya farklı Workspace hesaplarını bağlayacaksanız External seçin. (Yalnız kendi Workspace kuruluşunuzsa Internal — onay ekranı olmadan çalışır.)
   • Publishing status: Testing'de bırakabilirsiniz; bu durumda Test users'a bağlanacağınız Google hesabı e-postasını EKLEYİN (yoksa "Access blocked: app is being tested" alırsınız). Herkese açmak isterseniz Publish app (hassas drive.readonly kapsamı doğrulama gerektirir; test için Testing yeterli).
5. Scopes (Kapsamlar) — Data Access: Google Auth Platform → Data Access → Add or remove scopes → listeden veya "Manually add scopes" ile https://www.googleapis.com/auth/drive.readonly (salt-okuma) ekleyip Save. (drive.readonly "restricted/sensitive" bir kapsamdır — Testing modunda sorun değil.)
6. OAuth client (İstemci) oluşturun: Google Auth Platform → Clients → Create client →
   • Application type: Web application.
   • Authorized redirect URIs → Add URI: https://semagent.ai/api/connectors/oauth/google/callback (OAuth Playground ile token üretecekseniz ayrıca https://developers.google.com/oauthplayground).
   • Authorized JavaScript origins: boş bırakın (sunucu-taraflı akış).
   • Create → dönen Client ID ve Client secret'ı kaydedin.
7. Panelde bağlayın (tek-tık — önerilen): Veri Kaynakları → Google Drive → "Kendi OAuth uygulamanızla bağlanın" panelinde Client ID + Client secret'ı girip "Kaydet ve Bağlan"a basın. SemAgent onay akışını SİZİN uygulamanızla koşar ve refresh_token'ı sizin için alır — elle token üretmenize gerek yoktur. (Uygulamanız Testing'de kalabilir; kendinizi Test user eklemeyi unutmayın.)
8. Alternatif (elle refresh_token): dilerseniz OAuth Playground ile üretebilirsiniz: sağ üst dişli → "Use your own OAuth credentials" → Client ID/Secret girin → sol listeden Drive API v3 → drive.readonly → Authorize APIs → Exchange authorization code for tokens → çıkan refresh_token'ı panelde Refresh token + Client ID + Client secret alanlarına yapıştırın (Playground'u redirect URI'lerinize eklemeyi unutmayın). İsteğe bağlı Klasör ID (Drive URL'sindeki .../folders/<ID>) tek klasörü sınırlar.

Notion

İki yol: Integration token (en kolay, önerilen) veya formdaki "Notion ile Bağlan" düğmesiyle tek-tık OAuth (operatör kurmuşsa). Her ikisi de aynı panel alanına yazılır.

Integration token ile — adım adım:

1. notion.so/profile/integrations (veya Settings → Connections → Develop or manage integrations) → New integration → Internal tipini seçip oluşturun. (app.notion.com'daki "Connections → Access token" veya "Personal access tokens" da geçerli bir API token'ı verir — herhangi biri olur.)
2. Internal Integration Token'ı kopyalayın (secret_… veya ntn_… ile başlar).
3. Sayfayı paylaşın: indekslemek istediğiniz sayfayı/veritabanını Notion'da açın → sağ üst ••• → Connections → Connect to → [entegrasyonunuz]. ⚠️ Paylaşmadığınız sayfalar API'ye GÖRÜNMEZ — bağlantı "ok" görünse de 0 doküman gelir.
4. Panelde token'ı Integration token alanına yapıştırın; tek bir veritabanını hedeflemek için URL'den Database ID girebilirsiniz → Sync.

Dropbox

Kendi Dropbox OAuth uygulamanızla tek-tık bağlanırsınız.

1. dropbox.com/developers/apps → Create app → Scoped access + Full Dropbox (veya yalnız bir uygulama klasörü için "App folder").
2. Permissions sekmesi: files.metadata.read + files.content.read + account_info.read işaretleyip Submit edin.
3. Settings sekmesi → OAuth 2 → Redirect URIs'e paneldeki Yönlendirme URI'sini (https://semagent.ai/api/connectors/oauth/dropbox/callback) ekleyin. Aynı sayfadan App key ve App secret'ı alın.
4. SemAgent → Veri Kaynakları → Dropbox → "Kendi OAuth uygulamanızla bağlanın" panelinde App key'i Client ID, App secret'ı Client secret alanına girip "Kaydet ve Bağlan"a basın.
5. İsteğe bağlı: yalnız bir klasörü indekslemek için Klasör yolu'na /Klasör yazın (boş = tüm Dropbox). Metin, PDF ve Office (docx/xlsx/pptx) dosyaları metne çevrilip indekslenir.

Zendesk

OAuth uygulaması gerekmez — bir API token yeterli (Notion gibi). Varsayılan olarak Yardım Merkezi (Help Center) makaleleri indekslenir; destek botu için en değerli kaynak budur.

1. Zendesk'te Admin Center → Apps and integrations → APIs → Zendesk API'yi açın.
2. Token access'i etkinleştirin → Add API token → dönen token'ı kopyalayın (bir daha gösterilmez).
3. SemAgent → Veri Kaynakları → Zendesk: Subdomain (acme.zendesk.com'daki acme), yönetici e-postanız ve API token → Kaydet ve bağla.
4. İsteğe bağlı İçerik türü: articles (varsayılan) · tickets · both. Destek kayıtlarını (ticket konu+açıklama) da indekslemek için both yazın.

Sorun giderme

Google: "Access blocked / redirect_uri_mismatch"

• redirect_uri_mismatch (Error 400): OAuth uygulamanızın Authorized redirect URIs listesinde https://semagent.ai/api/connectors/oauth/google/callback tam olarak yok. Ekleyin (sonda eğik çizgi olmadan, http değil https). Bu hata hesaptan bağımsızdır — hangi hesabı seçerseniz seçin aynı çıkar; önce URI'yi düzeltin.
• "Access blocked: app is being tested": Audience → Publishing status Testing iken bağlandığınız Google hesabı Test users'a eklenmemiş. Ekleyin ya da uygulamayı Publish edin.