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
- notion.so/profile/integrations’a gidin ve dahili bir integration oluşturun.
- Token’ını kopyalayın (
ntn_ya dasecret_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_KEYayarlanmış 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/callbackya da kendi makinenizdeki bir instance içinhttp://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
localhostderken dashboard127.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_URLayarlıysa ya daSECRET_KEYeksikse başlangıç reddedilir. - Yalnızca oturum açmış bir proje editor’ü dashboard’dan başlatabilir; bir API token’ı ya da
ADMIN_TOKENbaşlatamaz, çünkü bu bir tarayıcı gidiş dönüşüdür. - Erişim ve yenileme token’ı
SECRET_KEYile ş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 Notionsecret’ı API üzerinden400 invalid_requestile 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.