Copilot Studio Accelerator: SharePoint'ten Azure AI Search'e Custom Connector Rehberi

Native Bağlantının Sınırları

Copilot Studio, SharePoint'i doğrudan bilgi kaynağı olarak kullanma imkânı sunuyor. Ancak bu native bağlantı, kurumsal senaryolarda ciddi kısıtlamalarla karşılaşıyor:

• Private endpoint desteği yok — Ağ izolasyonu gerektiren kurumsal ortamlarda kullanılamıyor
• Conditional Access uyumsuzluğu — Koşullu erişim politikaları devredeyken bağlantı sorunları yaşanabiliyor
• SLA garantisi yok — Preview aşamasındaki connector için Microsoft tarafından servis düzeyi taahhüdü bulunmuyor
• Format kontrolü sınırlı — Hangi dosya formatlarının nasıl işleneceği konusunda özelleştirme yapılamıyor
• 7 MB dosya boyutu limiti — Microsoft 365 Copilot lisansı olmayan ortamlarda SharePoint dosyaları 7 MB'ı aşamıyor
• Yalnızca modern sayfalar — Klasik ASPX sayfaları ve SPFx bileşenleri içeren modern sayfalar desteklenmiyor

Bu sınırlamalar, özellikle gelişmiş grounding, tam kontrol veya üretken yapay zeka iş akışları gerektiren senaryolarda ekipleri alternatif çözümler aramaya itiyor.

Neden Custom Connector?

Microsoft, bu ihtiyaca yanıt olarak SharePoint → Azure AI Search Connector accelerator'ını açık kaynak olarak yayınladı. Bu accelerator, kendi custom push connector'ınızı oluşturmak için bir başlangıç noktası sunuyor.

Native connector ile custom connector arasındaki temel farklar:

• Tam kontrol — Hangi dosyaların indeksleneceğine, nasıl chunk'lanacağına ve hangi metadata'nın ekleneceğine siz karar veriyorsunuz
• Ağ uyumluluğu — Private endpoint ve Conditional Access ile sorunsuz çalışıyor
• Format esnekliği — 25'ten fazla dosya formatı destekleniyor; PDF tablolarından e-postalara, ZIP arşivlerinden EPUB'lara kadar
• Boyut limiti yok — 100 MB'a kadar dosyalar işlenebiliyor (yapılandırılabilir)
• Güvenlik trimming — Entra ID izinleri indeks seviyesinde saklanarak sorgu zamanı filtreleme yapılabiliyor
• Production-grade — SLA'nız kendi Azure altyapınıza bağlı, preview bağımlılığı yok

Pipeline Mimarisi

Connector, bir Azure Function üzerinde zamanlayıcı tetiklemesiyle çalışıyor. Her çalıştırmada şu adımlar sırayla gerçekleşiyor:

• Zamanlayıcı tetiklenir — Azure Functions runtime, CRON zamanlamasına göre (varsayılan: saatte bir) sharepoint_indexer fonksiyonunu çağırır
• İndeks kontrolü — Arama indeksi şeması oluşturulur veya güncellenir (idempotent)
• Dosya keşfi — Microsoft Graph API ile yapılandırılmış doküman kütüphanelerindeki dosyalar listelenir. Artımlı modda lastModifiedDateTime ile filtrelenir
• Her dosya için paralel işlem (yapılandırılabilir eşzamanlılık):

• Tazelik kontrolü — İndeksteki mevcut kayıt güncel mi kontrol edilir (±1 saniye tolerans)
• İndirme — Graph API üzerinden dosya byte'ları çekilir
• Metin çıkarma — Dosya uzantısına göre doğru extractor devreye girer
• Parçalama (Chunking) — Metin, akıllı sınır tespiti ile örtüşmeli parçalara ayrılır
• Embedding oluşturma — Parçalar Azure OpenAI'a 16'lık batch'ler halinde gönderilir
• Eski parçaları silme — Dosyanın önceki parçaları indeksten kaldırılır
• Yeni parçaları yükleme — Embedding, metadata ve izin bilgileriyle birlikte indekse push edilir

• Reconciliation (yalnızca tam reindex) — İndeksteki parent_id değerleri SharePoint'teki mevcut dosyalarla karşılaştırılır, artık var olmayan dosyaların parçaları temizlenir

Teknik Kararlar ve Gerekçeleri

Accelerator'ın mimarisinde bilinçli tercihler yapılmış:

Push Connector (Pull Değil)

Azure AI Search'ün kendi pull connector'ı yerine push modeli tercih edilmiş. Bu sayede neyin, ne zaman indeksleneceği tamamen kontrol altında. Azure'ın preview connector altyapısına bağımlılık ortadan kalkıyor.

Blob Ara Katmanı Yok

Dosyalar SharePoint'ten doğrudan belleğe alınıp indekse gönderiliyor. Blob Storage gibi bir ara katman yok. Bu, mimariyi basitleştiriyor, maliyeti düşürüyor ve yönetilecek ek depolama ortadan kaldırıyor.

System-Assigned Managed Identity

Tüm Azure servisleri için managed identity kullanılıyor — yönetilecek sıfır secret. Yalnızca Graph API için özel izin ataması gerekiyor (Sites.Read.All ve Files.Read.All).

HNSW Vector Search

Endüstri standardı yaklaşık en yakın komşu algoritması. Hız ve recall arasında iyi bir denge sunuyor.

text-embedding-3-large (1536 boyut)

OpenAI'ın en kaliteli embedding modeli. 1536 boyut, kalite/maliyet dengesi için iyi bir tercih (model 3072'ye kadar destekliyor).

Desteklenen Dosya Formatları

Connector, 25'ten fazla dosya formatını destekliyor:

• PDF — PyMuPDF ile sayfa sayfa metin çıkarma
• Word (.docx, .docm) — python-docx ile paragraf metni
• Excel (.xlsx, .xlsm) — openpyxl ile tüm sayfalar
• PowerPoint (.pptx, .pptm) — python-pptx ile tüm metin çerçeveleri
• Düz metin (.txt, .md) — Encoding fallback zinciri
• CSV, JSON, XML/KML — Built-in kütüphanelerle
• HTML — BeautifulSoup ile script/style temizliği
• E-posta (.eml, .msg) — Konu, gönderen, tarih ve gövde
• EPUB, OpenDocument (.odt, .ods, .odp) — Tam metin çıkarma
• Arşivler (.zip, .gz) — İç dosyaları çıkarıp işleme (derinlik limiti: 3)

Production ortamında karmaşık dokümanlar (tablolu PDF'ler, taranmış görseller, formlar) için bu katmanın Azure Document Intelligence ile değiştirilmesi öneriliyor.

Artımlı Senkronizasyon

Connector iki modda çalışabiliyor:

Artımlı Mod

Production'da önerilen mod. Saatlik CRON ile 65 dakikalık pencere kullanılıyor (60 dakikalık aralık + 5 dakika örtüşme). Graph API sorgusu lastModifiedDateTime ile filtreleniyor. Yalnızca değişen dosyalar işleniyor.

5 dakikalık örtüşme şunları kompanze ediyor:

• SharePoint ile Function App arasındaki saat farkı
• Önceki pencerenin son saniyelerinde değiştirilen dosyalar
• Serverless ortamlardaki zamanlayıcı kayması

Tam Reindex

INCREMENTAL_MINUTES=0 ayarıyla tüm dosyalar işleniyor. Tazelik kontrolü hâlâ aktif olduğu için güncel dosyalar atlanıyor. Ek olarak reconciliation çalışıyor: SharePoint'te artık bulunmayan dosyaların indeksteki parçaları temizleniyor.

Güvenlik Trimming

Connector, her dosya için Entra ID nesne kimliklerini (kullanıcılar ve gruplar) permission_ids alanında saklıyor. Bu sayede sorgu zamanında güvenlik filtreleme yapılabiliyor.

Her dosya için GET /beta/drives/{driveId}/items/{itemId}/permissions çağrısı yapılıyor. grantedToV2 (doğrudan izinler) ve grantedToIdentitiesV2 (paylaşım linkleri) üzerinden kimlik ID'leri çıkarılıyor.

Sorgu zamanında kullanıcının Entra nesne kimliği ve grup üyelikleri ile permission_ids alanı filtreleniyor. Böylece kullanıcı yalnızca erişim yetkisi olan dosyalardan gelen sonuçları görüyor.

Önemli not: İzinler, dosyanın indekslendiği andaki anlık görüntüdür. SharePoint'te izin değişiklikleri, dosya yeniden indekslenene kadar (bir sonraki değişiklik veya tam reindex) yansımaz.

Kurumlar İçin Öneriler

Bu accelerator bilinçli olarak basit tutulmuş — bir başlangıç noktası. Production ortamına taşırken dikkat edilmesi gerekenler:

• Document Intelligence entegrasyonu — Tablolu PDF'ler, taranmış belgeler ve formlar için temel metin çıkarma yeterli olmayacaktır. Azure Document Intelligence veya Unstructured.io gibi servisleri entegre edin
• Chunk stratejisini özelleştirin — Varsayılan 2000 karakter / 200 karakter örtüşme, her doküman tipi için optimal olmayabilir. Kendi dokümanlarınızla test edip ayarlayın
• İndeks şemasını genişletin — İş ihtiyaçlarınıza göre ek metadata alanları ekleyin
• İzleme ve alerting — Application Insights üzerinden çalıştırma özetlerini izleyin, hata oranlarına alert tanımlayın
• Maliyet optimizasyonu — Flex Consumption planı ile boştayken sıfıra ölçekleniyor. Ancak embedding maliyetlerini takip edin; büyük kütüphanelerde ilk tam indeksleme maliyetli olabilir

Sonuç

Copilot Studio'nun native SharePoint bağlantısı, basit senaryolar için yeterli olsa da kurumsal gereksinimler arttığında sınırlarına ulaşıyor. Microsoft'un bu accelerator'ı, kendi pipeline'ınızı oluşturmak için sağlam bir temel sunuyor.

Custom connector yaklaşımı daha fazla ilk kurulum çalışması gerektiriyor ancak karşılığında tam kontrol, ağ uyumluluğu, geniş format desteği ve güvenlik trimming gibi kritik yetenekler kazandırıyor.

Kaynak koduna GitHub üzerinden erişebilir, Copilot Studio SharePoint limitleri hakkında detaylı bilgiyi Microsoft Learn üzerinden inceleyebilirsiniz.