עימוד

זמין בתוכניותProResearch

נתיבים שיכולים להחזיר הרבה נתונים מחזירים אותם בעמודים. ה-API משתמש בשלושה סוגי עימוד, וכל נתיב משתמש באחד מהם. הסוג זהה בכל מקום שבו הוא מופיע, והתשובה תמיד אומרת אם יש עוד. החיפוש אינו מעומד: הוא מחזיר את 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) הוא סימנייה שה-API נותן לכם. אל תבנו אותו בעצמכם. שלחו אותו חזרה כמות שהוא.

נתיב	הסמן שאתם שולחים	מאיפה בא הבא	מגבלה
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