Veri Kaynakları (Data Sources)

Panel → Ayarlar → 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. Ayarlar → 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 · OneDrive · Dropbox · Notion · Zendesk · OneNote).
3. Her kaynak formunun yanında 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. Ardından Test (bağlantıyı doğrula), Senkronize (yeniden çek) ve İçerik (indekslenen dokümanları gözat) düğmelerini kullanabilirsiniz.
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ı)

Google Drive, OneDrive, OneNote ve 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

Ajanı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, SemAgent'ın çıkış IP'sine (173.212.244.210) 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, OneDrive, OneNote 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): 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 (önerilen): formda "Google ile Bağlan" düğmesine basın → Google onay ekranında hesabınızı seçip drive.readonly iznini verin → geri döndüğünüzde bir Google Picker açılır; indekslenecek dosya veya klasörleri seçersiniz. Kendi OAuth uygulamanızı oluşturmanıza gerek yoktur. "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.

OneDrive

Önerilen — kendi uygulamanızla tek tık: aşağıdaki adımlarla bir Azure uygulaması kaydedin, panele Client ID + Client secret girip "Kaydet ve Bağlan"a basın. "Bu sağlayıcı için OAuth yapılandırılmamış" görüyorsanız merkezi Microsoft OAuth kurulu değildir — bu normaldir; kendi uygulamanızın bilgilerini girin (merkezi doğrulama/CASA'dan kaçınmanın da amacı budur).

Kendi uygulamanızla (BYO) — Azure App registration adım adım

1. ⚠️ Dizin (directory) OLUŞTURMAYIN — gerek yok. Kişisel Microsoft/Outlook hesapları uygulamayı dizin oluşturmadan doğrudan kaydedebilir. portal.azure.com/#create/Microsoft.AzureActiveDirectory ile dizin oluşturmayı denerseniz kişisel hesaplarda genelde 401 "You don't have access" alırsınız — bu adımı tamamen atlayın. Zaten portal.azure.com'a girdiğinizde otomatik bir "home" dizinindesiniz (sağ üstte GUID benzeri bir dizin görürsünüz).
2. Doğrudan App registration: üst arama çubuğuna "App registrations" yazıp açın (veya Microsoft Entra ID → App registrations) → + New registration → ad verin. Supported account types: ⚠️ "Accounts in any organizational directory (Multitenant) and personal Microsoft accounts" seçin (kişisel OneDrive için ŞART). ("not contained within any directory" uyarısını görmezden gelin; uygulama yine de çalışır.) Yalnızca App registration da "no access" derse ücretsiz gerçek bir dizin alın: Microsoft 365 Developer Program (aynı hesapla "Join now" → xxxxx.onmicrosoft.com tenant'ı) → orada kaydı yapın.
3. Redirect URI (Web): https://semagent.ai/api/connectors/oauth/microsoft/callback → Register.
4. API permissions → Add a permission → Microsoft Graph → Delegated: Files.Read.All + offline_access ekleyin. (Kişisel hesapta "Grant admin consent" gerekmez; iş/okul dizininde gerekebilir.)
5. Certificates & secrets → New client secret → değeri kopyalayın. Overview'dan Application (client) ID'yi ve (tek-kiracılı uygulamaysa) Directory (tenant) ID'yi not edin.
6. Panelde bağlayın (tek-tık — önerilen): Veri Kaynakları → OneDrive → "Kendi OAuth uygulamanızla bağlanın" panelinde Client ID + Client secret girin; uygulamanız tek-kiracılıysa (yalnız kendi dizininiz) Azure Dizin (Tenant) ID alanına dizin kimliğinizi yazın (çok-kiracılı/kişisel için common bırakın) → "Kaydet ve Bağlan". SemAgent onay akışını sizin uygulamanızla koşar. İsteğe bağlı Klasör yolu ile bir alt klasörü sınırlayın. Metin dosyaları (txt, md, csv, json, html) indekslenir. (Alternatif: bir OAuth akışıyla elle refresh_token üretip Refresh token + Client ID + Client secret alanlarına yapıştırabilirsiniz.)

OneNote

OneDrive ile aynı Azure uygulamasını kullanır; tek fark izinlerdir:

1. Aynı App registration'ı kullanın (veya yeni oluşturun; redirect URI aynı: .../oauth/microsoft/callback).
2. Microsoft Graph Delegated izinlerine Notes.Read.All + offline_access ekleyin.
3. Veri Kaynakları → OneNote → "Kendi OAuth uygulamanızla bağlanın" panelinde Client ID + Client secret (tek-kiracılıysa Azure Dizin/Tenant ID) girip "Kaydet ve Bağlan"a basın (ya da elle Refresh token yapıştırın). Not defteri sayfaları metne çevrilip indekslenir.

Notion

İki yol: Integration token (en kolay, önerilen) veya tek-tık OAuth. 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 — Microsoft'taki dizin derdi burada yok.

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.

Microsoft: "AADSTS50058 / AADSTS50020 / 401 — interaction required, account does not exist in tenant"

• ⚠️ AADSTS50058 "Interaction required / cookies were not sent" (en sık): Bu bir çerez/oturum sorunudur, yetki değil. Neredeyse her zaman InPrivate/Gizli pencere veya katı izleme-önleme yüzünden olur (üçüncü-taraf çerezler engellenir). Çözüm: InPrivate'tan çıkın, NORMAL bir pencere açın; Edge'de Ayarlar → Çerezler ve site izinleri → İzleme önleme → "Dengeli" yapın (Katı değil) veya [*.]microsoftonline.com + [*.]azure.com'a çerez izni verin; portal.azure.com'a tam giriş yapın (akışı tamamlayın, "Ignore" demeyin). En garantili yol: aşağıdaki M365 Developer Program tenant'ı.
• Bu hata, kişisel (live.com/Gmail tabanlı) hesabınızla size ait olmayan bir Azure uygulamasını (ör. Azure Portal'ın kendi app'i) açmaya çalıştığınızda çıkar. Çözüm: mevcut bir app'i açmayın; portal.azure.com → App registrations → New registration ile kendi kaydınızı oluşturun.
• Dizin oluştururken "You don't have access" (401): #create/Microsoft.AzureActiveDirectory ile dizin oluşturmayı denemeyin — kişisel hesaplarda bu blade 401 verir ve gerekmez. Uygulamayı doğrudan App registrations → New registration ile, hesap tipi "Multitenant + personal Microsoft accounts" seçerek kaydedin (dizinsiz çalışır). SemAgent panelinde Azure Dizin (Tenant) ID'yi common bırakın.
• App registration da "no access" derse: ücretsiz gerçek bir tenant alın — Microsoft 365 Developer Program ("Join now" → xxxxx.onmicrosoft.com, orada Global Admin olursunuz) → kaydı o tenant'ta yapın. Panelde yine common kalır (hesap tipi multitenant+personal olduğundan).