Notion API: Notion bazalarini saytga yoki botga qanday ulash

Qisqa javob

Notion API — bu REST API bo‘lib, u orqali serveringiz Notion sahifalari va bazalarini o‘qiydi va o‘zgartiradi. Sxema doim bir xil:

1. Integratsiya yaratib, maxfiy token olish.
2. Integratsiyaga aniq sahifa yoki bazalarni ulash — standart holatda u hech narsani ko‘rmaydi.
3. api.notion.com manziliga token va Notion-Version sarlavhasi bilan so‘rov yuborish.

Shu tarzda Notion blog uchun yengil CMS, Telegram-bot uchun arizalar bazasi yoki ichki servis uchun ma’lumotnomaga aylanadi.

1-qadam. Integratsiya yarating

• Notion sozlamalaridagi integratsiyalar bo‘limini oching va workspace uchun internal integration yarating.
• Imkoniyatlarni (capabilities) tanlang: faqat kontentni o‘qish yoki qo‘shish/o‘zgartirish ham. Kerakli minimumni bering.
• Internal Integration Secret’ni nusxalab, server muhit o‘zgaruvchilarida saqlang.

Muhim: token hech qachon frontend kodiga yoki mobil ilovaga tushmasligi kerak. Notion’ga barcha so‘rovlar faqat backend orqali yuboriladi.

2-qadam. Bazaga ruxsat bering

Integratsiya faqat o‘ziga ulangan narsalarni ko‘radi. Baza sahifasini oching, «...» menyusida Connections’ni tanlang va integratsiyangizni qo‘shing. Ruxsat ichki sahifalarga ham o‘tadi.

Baza ID’si uning URL manzilidan olinadi — bu ?v= dan oldingi 32 belgili qator.

Yangi boshlovchilarning eng ko‘p uchraydigan muammosi — ID to‘g‘ri bo‘lsa ham object_not_found xatosi. Deyarli doim bu bazani integratsiyaga ulash unutilganini bildiradi.

3-qadam. Bazani pagination va limitlar bilan o‘qish

Baza so‘rovi bir martada ko‘pi bilan 100 ta yozuv qaytaradi. Javobda has_more: true bo‘lsa, so‘rovni next_cursor qiymatini start_cursor sifatida berib takrorlang.

So‘rovlar limiti — integratsiya uchun sekundiga o‘rtacha uchtaga yaqin. Oshib ketsa, API 429 va Retry-After sarlavhasi bilan javob beradi — ko‘rsatilgan soniya kutish kerak.

const headers = {
  Authorization: `Bearer ${process.env.NOTION_TOKEN}`,
  "Notion-Version": "2022-06-28",
  "Content-Type": "application/json",
};

async function queryAll(databaseId, body = {}) {
  const results = [];
  let cursor;
  do {
    const res = await fetch(`https://api.notion.com/v1/databases/${databaseId}/query`, {
      method: "POST",
      headers,
      body: JSON.stringify({ ...body, page_size: 100, start_cursor: cursor }),
    });
    if (res.status === 429) {
      const wait = Number(res.headers.get("Retry-After") || 1);
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    if (!res.ok) throw new Error(`Notion API error ${res.status}`);
    const data = await res.json();
    results.push(...data.results);
    cursor = data.has_more ? data.next_cursor : undefined;
  } while (cursor);
  return results;
}

API’ning yangi versiyalarida bazalar data sources’ga ajratilgan va so‘rov endpoint’i boshqacha. Yangi Notion-Version’ni tanlasangiz, rasmiy hujjatlarni tekshiring.

Misol: Notion blog uchun CMS sifatida

Name (title), Slug (text), Status (select) va Date (date) xususiyatlari bilan baza yarating. Faqat chop etilgan postlarni olamiz:

const pages = await queryAll(process.env.NOTION_POSTS_DB, {
  filter: { property: "Status", select: { equals: "Published" } },
  sorts: [{ property: "Date", direction: "descending" }],
});

const text = (arr) => arr.map((t) => t.plain_text).join("");

const posts = pages.map((p) => ({
  id: p.id,
  title: text(p.properties.Name.title),
  slug: text(p.properties.Slug.rich_text),
  date: p.properties.Date.date?.start,
}));

Agar Status select emas, status turidagi xususiyat bo‘lsa, filtr status: { equals: "Published" } ko‘rinishida yoziladi.

Maqola matni esa bloklardan iborat: GET /v1/blocks/{page_id}/children. Ular ham 100 tadan qaytadi, ichma-ich bloklar (has_children: true) uchun alohida so‘rov kerak.

Yozish: botdan arizalarni bazaga saqlash

Yangi yozuv — bu ota-onasi baza bo‘lgan yangi sahifa:

await fetch("https://api.notion.com/v1/pages", {
  method: "POST",
  headers,
  body: JSON.stringify({
    parent: { database_id: process.env.NOTION_LEADS_DB },
    properties: {
      Name: { title: [{ text: { content: name } }] },
      Phone: { phone_number: phone },
      Source: { select: { name: "Telegram" } },
    },
  }),
});

Yozuvni o‘zgartirish uchun xuddi shu xususiyat obyektlari bilan PATCH /v1/pages/{page_id} yuboring.

Ko‘p uchraydigan xatolar

• Har bir sahifa ko‘rilishida Notion’ga so‘rov. Limitlar tez tugaydi. Natijani keshlang yoki sahifalarni davriy yangilanish bilan statik generatsiya qiling.
• Xususiyat nomlariga bog‘lanish. Ustun nomini o‘zgartirdingiz — integratsiya buziladi. Ishonchlilik uchun xususiyat ID’laridan foydalaning.
• Fayl havolalari. Notion’ga yuklangan fayllarning URL’lari vaqtinchalik. Sayt uchun fayllarni o‘z xotirangizga ko‘chiring.
• Bitta obyektda uzun matn. Rich text’da bitta matn obyekti uchun uzunlik cheklovi bor — uzun matnni qismlarga bo‘ling.
• 429 va 5xx ishlov berilmagan. Pauza bilan qayta urinishlar har qanday integratsiya uchun shart.

Notion qachon mos keladi, qachon yo‘q