Contextator
ENTR

Kaynaklar

Notion

API üzerinden bir Notion çalışma alanını indekslemek — bir integration oluşturmak, sayfaları paylaşmak, neyin içeri alındığı, ve dışa aktarım zip alternatifi.

Güncelleme:

Bir Notion çalışma alanını doğrudan API üzerinden indeksleyin: dahili bir integration ile paylaşılan her sayfa Markdown’a dönüştürülür ve senkronize tutulur. Değişen sayfalar yeniden render edilir; paylaşımı durdurulan sayfalar kaldırılır.

Bir integration oluşturmak istemiyorsanız, bir Notion Export → Markdown & CSV zip’ini de yükleyebilirsiniz — aşağıda dışa aktarım yolune bakın.

1. Bir integration oluşturun

  1. notion.so/profile/integrations’a gidin ve dahili bir integration oluşturun.
  2. Token’ını kopyalayın (ntn_ ya da secret_ ile başlar).

2. Sayfaları onunla paylaşın

Notion’da, indekslenmesini istediğiniz her sayfayı ya da veritabanını açın ve onu integration ile paylaşın (… → Connections → integration’ınız). Bir üst sayfayı paylaşmak, çocuklarını da paylaşır.

Bunu yapana kadar Contextator’a hiçbir şey görünmez — yepyeni bir integration hiçbir şey görmez.

3. Kaynağı ekleyin

Add source → Notion

Alan Notlar
Name Bağlama öneki. Değiştirilemez
Integration token SECRET_KEY ile şifrelenmiş saklanır, bir daha gösterilmez
Root pages or databases Opsiyonel. Sayfa ya da veritabanı id’leri — ya da yalnızca URL’leri, id ayıklanır. Satır başına bir tane. İntegration ile paylaşılan her şeyi almak için boş bırakın

Kaynak kaydedildikten sonra satırındaki Test’e (ya da Edit diyaloğundaki Test connection’a) basın: integration’ın kendi kullanıcısını okur ve adıyla yanıt verir (Connected as Docs Importer), böylece herhangi bir indeksleme başlamadan önce yanlış bir token belli olur.

Bir kaynak bir token saklayabilmeden önce SECRET_KEY ayarlanmış olmalıdır (32+ karakter). Bkz. Yapılandırma.

Connect with Notion (OAuth)

0.6.0’dan beri bir kaynağı yetkilendirmenin ikinci bir yolu var: Connect with Notion. Bir integration oluşturup token’ını yapıştırmak yerine sayfaları Notion’ın kendi sayfa seçicisinde seçersiniz. Kendi kaydettiğiniz bir public connection gerekir (notion.so/profile/integrations altında, dahili değil public bir connection) — Contextator’a ait bir connection yoktur — ve instance’ta üç değişken: NOTION_OAUTH_CLIENT_ID, NOTION_OAUTH_CLIENT_SECRET ve bir yönlendirme URI’si (NOTION_OAUTH_REDIRECT_URI ya da PUBLIC_BASE_URL’den türetilir; bkz. Yapılandırma). Hiçbiri ayarlı değilse hiçbir şey değişmez: dashboard yalnızca token alanını gösterir.

  • Yönlendirme URI’si bu instance’ı adlandırmalıdır: https://<alan-adınız>/api/sources/notion/oauth/callback ya da kendi makinenizdeki bir instance için http://localhost:<port>/api/sources/notion/oauth/callback. IP adresi olmaz.
  • Dashboard’u aynı host’ta açın: oturum çerezleri bir host adına aittir; yönlendirme URI’si localhost derken dashboard 127.0.0.1’de açıksa tarayıcı, oturum açmadığınız bir host’a geri gönderilir.
  • Yalnızca kimlik ve gizli anahtardan biri ayarlıysa, ne yönlendirme URI’si ne de PUBLIC_BASE_URL ayarlıysa ya da SECRET_KEY eksikse başlangıç reddedilir.
  • Yalnızca oturum açmış bir proje editor’ü dashboard’dan başlatabilir; bir API token’ı ya da ADMIN_TOKEN başlatamaz, çünkü bu bir tarayıcı gidiş dönüşüdür.
  • Erişim ve yenileme token’ı SECRET_KEY ile şifrelenmiş saklanır. Notion erişim token’ını reddedince kaynak onları yeniler; iptal edilmiş bir bağlantı çalışmayı Reconnect isteyerek bitirir, bu da kaynağı adını ve ayarlarını değiştirmeden yeniden yetkilendirir.
  • Bir OAuth kaynağının webhook’u yoktur: bir public connection’ın webhook’u tek bir kaynağa değil connection’a aittir, bu yüzden güncel tutmayı zamanlama sağlar. Proje dışa aktarımı token’ları bırakır, bu yüzden içe aktarılmış bir OAuth kaynağı Reconnect ister. { ile başlayan bir Notion secret’ı API üzerinden 400 invalid_request ile reddedilir: bu bir OAuth bağlantısının biçimidir ve onu yalnızca dashboard akışı oluşturur.

Neyin içeri alındığı

Her sayfa, üst sayfa başına bir klasöre yerleştirilmiş, başlığı, Notion id’si, URL’si ve last_edited_time’ı frontmatter’da olan tek bir Markdown dosyası olur. Dosya ve klasör adları, başlığın slug hali artı Notion id’sinin ilk sekiz karakteridir; bir veritabanında duran sayfa ise database--<id'nin ilk sekiz karakteri> klasöründe yer alır:

notion/engineering--1a2b3c4d/runbooks--5e6f7a8b/rotating-the-signing-key--9c0d1e2f.md

Render edilen blok türleri: paragraflar, üç başlık seviyesinin tümü (katlanabilir bir başlığın altına katlanmış bloklar dahil), iç içe geçmeleriyle madde işaretli, numaralı ve yapılacaklar listeleri, alıntılar, callout’lar, kod blokları, tablolar, ayraçlar, denklemler, yer imleri, görseller ve dosya bağlantıları. Bilinmeyen blok türleri, sayfayı başarısız kılmak yerine atlanır, böylece yeni bir Notion özelliği bir içe aktarımı asla bozmaz.

Kaynak başına sınırlar: varsayılan olarak 5000 sayfa (NOTION_MAX_PAGES, 1 ile 100 000 arası, instance başına ayarlanır — bkz. Yapılandırma) ve 25 seviye iç içe geçme. İstekler saniyede yaklaşık üçe kısıtlanır, ki bu Notion’ın belgelenmiş hız sınırıdır — büyük bir çalışma alanı ilk senkronizasyonda biraz zaman alır ve sonrasında hızlıdır.

Senkronize tutmak

Her indeksleme çalışmasının başında, Contextator çalışma alanını yeniden çeker ve yalnızca last_edited_time’ı değişen sayfaları yeniden render eder. Artık paylaşılmayan ya da silinmiş bir sayfanın dosyası kaldırılır.

Notion’ın kendi push webhook’u bir git sağlayıcısının tersi yönde çalışır: URL yine de bir Notion subscription’ına yapıştırılır, başka yerdeki Push Webhook’ları ile aynı örüntü, ama sır ters yönde akar. Önce kaynağın Edit diyaloğundaki Open verification window ile 15 dakikalık bir doğrulama penceresi açın; Notion’ın o URL’e ilk gönderimi token’ı taşır, o da doğrulamayı bitirmek için Notion’ın Webhooks sekmesine geri yapıştırılır. Doğrulandıktan sonra bir sayfa düzenlendiğinde, silindiğinde ya da taşındığında bir senkronizasyon başlatır — birkaç saniye içinde değil, çünkü bir gönderim yığını tek bir çalışmaya indirgenir ve çalışmalar arasında en az WEBHOOK_MIN_INTERVAL_MINUTES (varsayılan olarak 5) vardır — ama her boşluğu kapatmaz: Notion, bir sayfanın paylaşımı kaldırıldığında hiçbir olay göndermez; yani paylaşımın kaldırılmasının kendine ait bir olayı yoktur. Sayfayı bir sonraki tam senkronizasyon düşürür; onu başka bir sayfa için gelen bir webhook’un, Sync’in ya da Sync every aralığının başlatmış olması fark etmez. Aralığın kontrolü paylaşım kaldırmayı tek başına göremez: yalnızca çalışma alanındaki en yeni düzenleme zamanına bakar, yani düzenlemeleri fark eder, paylaşım kaldırmalarını değil.

Başka hiçbir şey senkronizasyon başlatmazsa garantiyi zamanlanmış kontrol verir ve bu sınırlıdır. Zamanlanmış bir kaynak, son başarılı senkronizasyonu SYNC_MAX_SKIP_HOURS değerinden (varsayılan 24 saat) eskiyse, kontrol ne derse desin eksiksiz senkronize edilir. Sayfa o çekimde yoktur, bu yüzden dosyası kaldırılır: paylaşımı kaldırılan bir sayfa, bu süre artı kaynağın kendi Sync every aralığı, en fazla bir dakika ve senkronizasyonun kendi süresi ya da süren bir çalışma kadar bir süre içinde indeksten ve arama sonuçlarından çıkar. Değişkeni 0 yaparsanız sınır kapanır; sayfa, çalışma alanında herhangi bir yerdeki bir sonraki düzenleme bir çalışmayı tetikleyene kadar kalır. Never olarak ayarlanmış bir kaynak zamanlanmış değildir, bu yüzden sınır ona ulaşmaz.

Paylaşımı kaldırılan bir sayfayı hemen düşürmek için kaynakta Sync’e basın, projede Re-index’e basın ya da POST /api/projects/:id/reindex’i çağırın — sayfa o çekimde yoktur, bu yüzden dosyası kaldırılır (bkz. Admin API). Webhook doğrulanana kadar düzenlemeleri yakalayan Sync every’dir.

Bir şeyler yanlış olduğunda

Token reddedilirse, ya da yapılandırılan root sayfalarının hiçbiri okunamıyorsa, senkronizasyon başarısız olur ve bunu bildirir. Boş bir çalışma alanı bildirmez — ki bu aksi halde daha önce içeri alınan her sayfayı silerdi. Projenin diğer kaynakları yine de indekslenir, ve proje şunu bildirir:

2/3 sources synced; notion: No configured Notion root could be read — 1a2b3c4d… (object_not_found)

Bazı root’lar okunabiliyor ve diğerleri okunamıyorsa, okunabilenler içeri alınır ve başarısızlıklar bildirilir.

Belirti Neden ve çözüm
Test, Notion’ın geçersiz bir API token’ı hakkındaki kendi mesajıyla yanıt verir (hata kodu unauthorized) Yanlış ya da iptal edilmiş token. Yeni bir tane oluşturun ve yapıştırın
Kaynak hiçbir şey içeri almaz Henüz integration ile hiçbir şey paylaşılmamış. Sayfaları paylaşın (… → Connections)
Belirli bir sayfa eksik O — ya da üst sayfası — integration ile paylaşılmamış, ya da 25 seviyeden daha derinde
Bir root id için object_not_found Id yanlış, ya da o sayfa integration ile paylaşılmamış
Bir veritabanının satırları eksik Yalnızca içindeki sayfaları değil, veritabanının kendisini paylaşın

Dışa aktarım zip’i alternatifi

Bir integration oluşturamıyorsanız, Notion’dan dışa aktarın (… → Export → Markdown & CSV) ve zip’i içerik türü Notion export olan bir Upload files kaynağı olarak yükleyin. Notion’ın her dosya ve klasör adına eklediği 32 karakterlik sayfa id’si, yollardan ve onlara işaret eden bağlantılardan ayıklanır, ve dışa aktarımın içindeki iç içe geçmiş Part-1.zip otomatik olarak açılır.

Ödünleşim: hiçbir şey kendiliğinden senkronize olmaz — içerik değiştiğinde yeniden dışa aktarır ve yeniden yüklersiniz.

Gezinmek için ok tuşları, açmak için Enter.