صفحهبندی
اندپوینتهای فهرستی API دادهها را بهصورت صفحهای برمیگردانند. در پلتفرم بهطور تاریخی دو طرح صفحهبندی وجود دارد؛ طرح مشخص در مرجع تعاملی برای هر اندپوینت ذکر شده است.
طرح ۱ — offset و X-Total-Count
صفحهبندی کلاسیک بر اساس offset. درخواست پارامترهای query limit (اندازه صفحه) و offset (تعداد رکورد برای رد کردن) را میپذیرد:
curl -H "Authorization: Bearer mbp_TOKEN_SHOMA" "https://your-domain/api/bots/BOT_ID/subscribers?limit=50&offset=100"
تعداد کل رکوردها در هدر پاسخ X-Total-Count برمیگردد. از آن تعداد صفحات محاسبه میشود: با افزایش offset به اندازه limit صفحه بزنید، تا زمانی که offset کمتر از مقدار X-Total-Count باشد. بدنه پاسخ آرایهای از عناصر صفحه جاری است.
طرح ۲ — cursor با before و has_more
صفحهبندی مبتنی بر cursor برای فیدهای مرتبشده بر اساس زمان (مثلاً پیامهای مکالمه). درخواست limit و cursor اختیاری before — شناسه یا نشانگر آخرین عنصر دریافتشده — را میپذیرد:
curl -H "Authorization: Bearer mbp_TOKEN_SHOMA" "https://your-domain/api/bots/BOT_ID/users/USER_ID/dialog?limit=50&before=CURSOR"
پاسخ شامل صفحهای از عناصر و فلگ has_more است. تا زمانی که has_more برابر true است، درخواست را با cursor آخرین عنصر دریافتشده در before تکرار کنید. وقتی has_more برابر false شد — این آخرین صفحه است.
کدام طرح را انتخاب کنید
شما طرح را انتخاب نمیکنید — اندپوینت آن را تعیین میکند. فهرستهای مرجع معمولاً از offset و X-Total-Count استفاده میکنند؛ فیدهای زمانی از cursor با before و has_more. همیشه صفحه اندپوینت را در مرجع بررسی کنید.
بیشتر بخوانید
- شروع سریع API — اولین درخواستها.
- خطاها — کدهای وضعیت.
- محدودیتها و اندازهها — محدودیتهای درخواست.