ترقيم الصفحات

متاح فيProResearch

المسارات التي قد تعيد بيانات كثيرة تعيدها على صفحات. تستخدم الواجهة ثلاثة أنواع من الترقيم، ويستخدم كل مسار نوعًا واحدًا منها. النوع نفسه في كل موضع يظهر فيه، وتخبرك الاستجابة دائمًا ما إذا كان هناك المزيد. البحث ليس مرقّمًا: يعيد أفضل limit من النتائج.

ترقيم بالإزاحة: نص المستند

يعيد GET /documents/:id نص المستند على قطع بحجم يصل إلى maxChars حرف (الافتراضي 12,000 والحد الأقصى 20,000). مرّر nextOffset من استجابة ما بصفته offset في التالية، حتى تصبح nextOffset هي null.

async function readDocument(id) {
  let offset = 0;
  let text = '';
  while (offset !== null) {
    const res = await fetch(
      `https://api.readsira.com/rest/v2/documents/${id}?offset=${offset}&maxChars=20000`,
      { headers: { Authorization: `Bearer ${process.env.READSIRA_KEY}` } },
    );
    const { data } = await res.json();
    text += data.text;
    offset = data.nextOffset;
  }
  return text;
}

وفي الاستجابة أيضًا: totalChars (الطول الكامل) وtruncated، وهي true ما دام هناك نص متبقٍّ.

ترقيم بالمؤشر: المقاطع والنصوص المفرغة والمشاريع

المؤشر (cursor) علامة تعطيها لك الواجهة. لا تبنِه بنفسك. أعده كما هو.

المسار	المؤشر الذي ترسله	من أين يأتي التالي	الحد
GET /documents/:id/chunks	cursor (رقم)	nextCursor	limit، بحد أقصى 100
GET /documents/:id/transcript	cursor (نص)	nextCursor	limit، بحد أقصى 500
GET /projects	cursor (نص)	nextCursor	limit، بحد أقصى 50

لا يحمل الاستدعاء الأول مؤشرًا. واصل الاستدعاء بآخر nextCursor حتى يصبح null أو يغيب.

curl -G "https://api.readsira.com/rest/v2/projects" \
  -H "Authorization: Bearer $READSIRA_KEY" \
  --data-urlencode "limit=20"

تحتوي الاستجابة على صفحة المشاريع، وعند وجود المزيد تحتوي على nextCursor (مختصرة هنا):

{
  "success": true,
  "data": {
    "projects": ["..."],
    "nextCursor": "VALUE_FROM_THE_ANSWER"
  }
}

ترسل الصفحة التالية تلك القيمة نفسها بصفتها cursor:

curl -G "https://api.readsira.com/rest/v2/projects" \
  -H "Authorization: Bearer $READSIRA_KEY" \
  --data-urlencode "limit=20" \
  --data-urlencode "cursor=$NEXT_CURSOR"

أرقام الصفحات: الإشارات المرجعية والمجموعات

تستخدم المسارات الأقدم /api/v1/bookmarks و/api/v1/collections المعاملين page (بدءًا من 1) وlimit (بحد أقصى 100، والافتراضي 20). تجيب قائمة الإشارات المرجعية بـ bookmarks وtotal وpage وlimit وhasMore. اطلب page التالية ما دامت hasMore هي true.

curl -G "https://api.readsira.com/api/v1/bookmarks" \
  -H "Authorization: Bearer $READSIRA_KEY" \
  -d page=2 -d limit=100

نصائح

• كل صفحة طلب وتُحتسب ضمن حدودك. استخدم أكبر limit يسمح به المسار عندما تحتاج كل شيء.
• تُقرأ الصفحات واحدة تلو الأخرى. لا ترسلها بالتوازي بالمؤشر نفسه.
• توقف عندما يكون المؤشر أو nextOffset هو null، أو عندما تكون hasMore هي false.

ذات صلة

• حدود المعدل والأخطاء
• أمثلة
• مرجع REST API v2