سقف‌ها و محدودیت نرخ

هر عددی که سرور به آن پایبند است، و اینکه کدام‌یک را می‌شود در زمان اجرا از خود سرور پرسید.

هر عددی که در این صفحه هست از همان کدی می‌آید که اعمالش می‌کند. هرجا یک سقف به‌جای رد کردن، داده شما را کوتاه می‌کند، همان‌جا صریح گفته شده است، چون کوتاه شدن بی‌صدا همان خرابی‌ای است که ماه‌ها بعد از یک گزارش بی‌معنی می‌فهمید.

#سقف‌ها را از سرور بخوانید

مسیر GET /v1/capabilities پنج تا از این عددها را در زمان اجرا منتشر می‌کند. یک واحد بودجه خرج دارد و هیچ مجوزی نمی‌خواهد.

curl -s https://api.segmentic.net/v1/capabilities \
  -H "Authorization: Bearer sk_seg_..."

{
  "version": "v1",
  "features": {
    "segments": true,
    "campaigns": true,
    "analytics": true,
    "transactional": true,
    "export": true,
    "import": true,
    "journeys": true,
    "ingest": true,
    "async_exports": true,
    "campaign_approval": true
  },
  "limits": {
    "max_page_size": 100,
    "max_preview_rows": 100,
    "max_batch_size": 500,
    "estimate_sample": 100,
    "query_timeout_sec": 30
  }
}

مقدارهای max_page_size و max_batch_size را از همین‌جا بخوانید، نه اینکه ۱۰۰ و ۵۰۰ را در کد بنویسید. هر پرچم در features می‌گوید همین استقرار در عمل چه چیزی سرو می‌کند، پس نصب خودمیزبانی که موتور تحلیل ندارد "analytics": false می‌دهد و کلاینت شما می‌تواند موقع بالا آمدن شکست بخورد به‌جای وسط کار.

چهار هشدار درباره این پاسخ، هر چهار چیزی که خواننده فرض می‌گیرد و نباید بگیرد.

• مقدارهای max_preview_rows و estimate_sample روی میزبان مدیریتی هیچ‌چیز را محدود نمی‌کنند. مال دو نقطه در پنل‌اند که اینجا ثبت نشده‌اند. نادیده بگیریدشان.
• مقدار query_timeout_sec برابر ۳۰ است و مهلت خواندن‌ها و نوشتن‌ها و POST /v1/audiences/count است. مهلتی که دو مسیر گزارش استفاده می‌کنند نیست، آن ۴۵ ثانیه است. مهلت‌ها را ببینید.
• کلیدهای ingest و import یک بولین‌اند با دو اسم، همانی که POST /v1/events را روشن می‌کند.
• پرچم export هیچ مسیری را روی این میزبان کنترل نمی‌کند. دو مسیر خروجی را async_exports روشن و خاموش می‌کند. حسابی که "export": false می‌بیند ممکن است هر دو مسیر خروجی را داشته باشد، و برعکس. برای خروجی به async_exports نگاه کنید.

بقیه چیزهای این صفحه را ناچارید در کد بنویسید، چون جایی برای خواندنشان نیست. نه GET /v1/reports/limits وجود دارد و نه نقطه‌ای که سقف رویداد حساب شما یا مصرف فعلی‌اش را بگوید.

#سقف‌های ورود داده

این‌ها روی هر دو در اعمال می‌شوند: میزبان ورود داده، و POST /v1/events روی میزبان مدیریتی.

فقط یکی از این‌ها کلید پیکربندی دارد. کلید MAX_BODY_BYTES سقف بدنه را می‌گذارد و پیش‌فرضش 5242880 است. بقیه در کد کامپایل شده‌اند، پس نصب خودمیزبان هم نمی‌تواند بالاترشان ببرد.

ترتیب مهم است. رد کردن قبل از کوتاه کردن رخ می‌دهد و کوتاه کردن قبل از ذخیره، پس رویدادی با user_id سیصدبایتی کامل رد می‌شود، نه اینکه با شناسه کوتاه‌شده ذخیره شود.

#سقف‌های بی‌صدا

هر فیلد دیگری داخل context بدون هیچ هشدار و هیچ خطایی کوتاه می‌شود. اینجا آورده شده‌اند چون راه دیگر فهمیدنشان این است که یک سگمنت آدم‌هایی را که انتظار داشتید نگیرد.

کشور و استان و شهر و عنوان صفحه و هر نام رویداد پیش از کوتاه شدن از نرمال‌سازی فارسی هم رد می‌شوند، پس ی و ک عربی به ی و ک فارسی تبدیل می‌شوند. همین است که می‌گذارد سگمنت روی city = تهران مشتری‌هایی را بگیرد که اپ‌هایشان سر املا با هم اختلاف دارند.

اگر مقداری برای یک سگمنت یا یک گزارش مهم است، خودتان داخل این کرانه‌ها نگهش دارید.

#پنجره زمانی رویداد

هر رویداد timestamp خودش را دارد. اینکه چقدر می‌تواند به عقب برسد، نگهداشت رویداد حساب خودتان است، نه یک ثابت.

در ورود داده زنده، زمانی قدیمی‌تر از پنجره به لبه پنجره چسبانده می‌شود و رویداد با هشدار timestamp_too_old پذیرفته می‌شود. رد نمی‌شود.

این تنها رفتار پلتفرم است که بیشترین احتمال را دارد یک هفته از شما بگیرد. پیش‌تر همان ۳۰ روز کل پنجره بود، هرچه نگهداشت شما می‌گفت، و نشانه‌اش نامرئی بود: حسابی که دو سال تاریخچه را مهاجرت می‌داد، هر رویداد قدیمی‌تر از سی روز را بی‌صدا درست روی «سی روز پیش» می‌دید، پذیرفته‌شده با یک هشدار و کد ۲۰۰. هیچ‌چیز شکست نخورد. داده فقط غلط بود، همه‌اش روی یک زمان تلنبار، و اولین نشانه‌اش ماه‌ها بعد قیفی بود که هیچ معنی نمی‌داد. حالا پنجره از سیاست نگهداشت شما می‌آید، همان چیزی که این چسباندن همیشه ادعا می‌کرد اعمالش می‌کند.

خواندن نگهداشت یک دقیقه کش می‌شود و وقتی خوانده نشود نرم به ۳۰ روز برمی‌گردد.

در backfill همین شرط به‌جای چسباندن رد می‌کند، با timestamp_too_old، چون در backfill جابه‌جا کردن یک زمان بدتر از رد کردنش است. سطر backfill که هیچ زمانی نداشته باشد هم رد می‌شود.

#نگهداشت پنجره ورود است، نه عمر داده

این دو عدد یکی نیستند و اشتباه گرفتنشان گران است. سیاست نگهداشت تا ۳۶۵۰ روز اعتبارسنجی می‌شود و کف غیرصفرش ۳۰ روز است. ولی جدول رویدادها در کلیک‌هاوس یک TTL ثابت چهارصد روزه روی event_time دارد که به سیاست حساب کار ندارد و هر سطری را می‌اندازد.

پس نگهداشت ده ساله را می‌شود ذخیره کرد و در عمل هیچ رویدادی بیشتر از چهارصد روز از زمان خودش زنده نمی‌ماند. سیاست فقط می‌گوید چه زمانی را موقع ورود می‌پذیریم و کی زودتر از چهارصد روز پاک می‌شود؛ بالا بردنش عمر داده را زیاد نمی‌کند.

اگر تاریخچه بلندتر از چهارصد روز لازم دارید، پیش از رسیدن به آن مرز خودتان خروجی بگیرید. جای دیگری برای گرفتنش نیست.

#سقف‌های میزبان مدیریتی

سه سقف مختلف بدنه اشتباهی نیست که کسی درستش کرده باشد. مسیر POST /v1/messages سهمش 256 KiB است چون payload تراکنشی یک شناسه قالب است و چند متغیر، و آن چهار مسیری که هندلر پنل را قرض می‌گیرند همان 1 MiB هندلر را می‌گیرند.

#صفحه‌بندی

پارامتر limit بریده می‌شود، هرگز رد نمی‌شود. مقدار limit=500 به شما ۱۰۰ می‌دهد. مقدارهای limit=0 و limit=banana هر دو ۲۵ می‌دهند. خطایی نمی‌گیرید که سقف را بگوید؛ آن را از GET /v1/capabilities بخوانید.

کرسر یک رشته مبهم base64url است. کرسری که دیکد نشود بی‌صدا ابتدای فهرست فرض می‌شود، نه خطا، پس کلاینتی که کرسرش را خراب کند تا ابد روی صفحه یک می‌چرخد به‌جای اینکه شکست بخورد. شناسه‌هایی را که می‌گیرید با آنچه دارید مقایسه کنید.

مسیرهای GET /v1/segments و GET /v1/campaigns با شکل خود هندلر پنل جواب می‌دهند، یعنی {"segments":[...]} و {"campaigns":[...]}، نه با پاکت صفحه‌بندی. شکل data و next_cursor فقط روی GET /v1/exports ظاهر می‌شود.

#سقف‌های گزارش

برای POST /v1/reports/funnel و POST /v1/reports/retention.

هر کدام از این خرابی‌ها با یک کد برمی‌گردد، invalid_report. پشت آن یک کد سیزده خطای اعتبارسنجی متمایز هست و هیچ راه برنامه‌ای برای جدا کردنشان. نه تای آن‌ها جمله فارسی کاتالوگ را در error می‌گذارند؛ چهار سطر پایینی این جدول، یعنی طول نام رویداد و تعداد فیلتر و طول کلید ویژگی و طول مقدار ویژگی، از شاخه پیش‌فرض رد می‌شوند و متن انگلیسی خود خطا را می‌آورند، مثل analytics: too many filters. اگر لازم دارید روی رشته تطبیق بدهید، و بپذیرید که نه رشته قرارداد است و نه زبانش.

گزارش مسیرها وجود دارد ولی فقط روی mux پنل ثبت شده است. با کلید API دسترس‌پذیر نیست.

#سقف‌های مخاطب و سگمنت

این‌ها تعریفی را می‌بندند که به POST /v1/audiences/validate و POST /v1/audiences/count و POST /v1/segments و PUT /v1/segments/{id} می‌فرستید.

شمارش شرط‌ها گزاره‌های روی ویژگی رویداد را هم شامل می‌شود، نه فقط گره‌های درخت منطقی، پس تعریفی که روی صفحه بیست شرط به نظر می‌رسد می‌تواند اینجا خیلی بیشتر از صد باشد. هر چهارتا با کد filter_invalid و وضعیت ۴۲۲ و جمله خود کامپایلر به‌عنوان متن بیرون می‌آیند.

قبل از ذخیره اعتبارسنجی کنید. مسیر POST /v1/audiences/validate تعریف را بدون دست زدن به پایگاه داده کامپایل می‌کند، یک واحد بودجه خرج دارد، و به‌جای ۲۰۰ با valid: false که پنل می‌دهد، ۴۲۲ می‌دهد.

#سقف‌های ارسال تراکنشی

قالب کلید به‌عمد سخت‌گیر است. کلید بخشی از شناسه پیام می‌شود، و شناسه پیام در دفتر و شمارنده تعداد و مرجع خود ارائه‌دهنده نوشته می‌شود، پس کلیدی که خط جدید یا گیومه داشته باشد راه درازی می‌رفت تا جایی بالاخره ردش کند. شناسه پیام مشتق است نه ساخته‌شده: t<tenant_id>.<کلید شما>، پس یک کلید تا آخر خط همان شناسه را می‌سازد.

فیلد category وقتی نفرستیدش transactional می‌شود. مقدار marketing با ۴۰۰ مستقیم رد می‌شود. این نقطه سقف تعداد و ساعت سکوت را دور می‌زند، پس قبول کردن پیام بازاریابی اینجا یعنی به شما یک راه مستند برای دور زدن قواعد ارسال خودتان بدهیم، و اولین باری که مهم می‌شد یک پیامک تبلیغاتی ساعت سه بامداد به کل فهرست بود.

#بودجه درخواست

هر مسیر میزبان مدیریتی به‌جز GET /v1/status با واحد وزن‌دار سنجیده می‌شود. «درخواست در دقیقه» واحد غلطی است برای سطحی که یک فراخوانی‌اش یک ساختار را می‌خواند و فراخوانی بعدی‌اش یک انبار داده را اسکن می‌کند.

هزینه هر مسیر:

ساز و کارش:

۶۰۰ واحد کم‌وبیش یعنی دو دوجین گزارش سنگین در دقیقه، یا ششصد فراخوانی ارزان. دقیقش: ۲۴ فراخوانی سنگین می‌گذرد و بیست‌وپنجمی رد می‌شود.

بودجه برخلاف محدودیت نرخ پایین‌تر، به کلید API کلید خورده است نه به حساب، و این عمدی است. شما یک کلید باریک به یک ایجنت می‌دهید و کلید یکپارچه‌سازی خودتان را جدا نگه می‌دارید، و ایجنتی که در حلقه افتاده نباید بتواند بودجه‌ای را که خط سفارش شما به آن وابسته است تمام کند. MCP را ببینید.

هزینه POST /v1/messages برابر ۱ است، که برای فراخوانی‌ای که می‌تواند به گوشی یک آدم پیام بفرستد غلط به نظر می‌رسد. غلط نیست: هزینه آن فراخوانی از نظر کوئری ناچیز است و از نظر پیامد عظیم، و چیزی که قرار بود بندش بزند بودجه گیرنده است، که وجود ندارد. آنچه سقف ندارد را ببینید.

تنها راه برگشت زمان است. کلید ردیس ۷۰ ثانیه بعد از اولین برداشت در آن پنجره منقضی می‌شود و سطل دقیقه با ساعت دیواری می‌چرخد. نه نقطه‌ای برای صفر کردن هست، نه بازنویسی به ازای کلید، و نه راهی برای بالا بردن سهمیه جز عوض کردن متغیر محیطی و ری‌استارت پروسه.

درخواست ردشده یک حساب قفل‌شده همچنان واحد بودجه‌اش را خرج می‌کند، چون بررسی قفل بعد از برداشت بودجه اجرا می‌شود.

#محدودیت نرخ ارسال تراکنشی

ساز و کار دومی که به‌کلی جداست. به‌جای واحد هزینه، درخواست می‌شمارد، دامنه‌اش حساب است نه کلید، و در جهت مخالف شکست می‌خورد.

به‌عمد باز شکست می‌خورد، و دلیلش ترافیکی است که حمل می‌کند. این نقطه رسید سفارش و کد ورود می‌فرستد. رد کردن همه‌شان چون یک کش پایین است، خرابی ما را تبدیل می‌کند به شکست خوردن پرداخت مشتری شما. محدودیت نرخ هست که جلوی یکپارچه‌سازی در حال فرار را بگیرد، و آن مشکلی است که دیر رسیدن به آن می‌ارزد.

چون پنجره ثابت است، یک فراخوان می‌تواند سر مرز دو پنجره، دو پنجره پیام بفرستد. برای سقفی که کارش متوقف کردن یک حلقه فراری است نه اندازه‌گیری تک‌تک درخواست‌ها، این معامله درستی است.

وقتی سقفی تنظیم شده باشد، دو هدر روی هر پاسخ می‌آیند، حتی پاسخ‌های موفق، تا بتوانید قبل از رد شدن آهسته کنید.

HTTP/1.1 200 OK
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
Content-Type: application/json; charset=utf-8

مقدار X-RateLimit-Remaining هرگز منفی نمی‌شود. هدر X-RateLimit-Reset و هدر X-RateLimit-Resource وجود ندارند. با پیش‌فرض منتشرشده که صفر است، هیچ هدری فرستاده نمی‌شود.

میزبان ورود داده هیچ محدودکننده نرخی ندارد. تنها کنترل‌های حجمش سقف بدنه، سقف دسته و دروازه سهمیه‌اند.

#سهمیه

سهمیه سقف پلن است که روی یک ماه جلالی شمرده می‌شود.

رویدادها فقط بعد از پذیرفته شدن سنجیده می‌شوند، پس payload ردشده صورتحساب نمی‌شود و تلاش دوباره تکراری‌زدایی‌شده هم نمی‌شود. SDK ای که دوباره می‌فرستد برای ما یک جست‌وجوی ردیس خرج دارد، نه یک خط فاکتور که سرش با ما دعوا کنید. پیام‌ها فقط روی ارسال موفق سنجیده می‌شوند.

پلن دو سقف سخت دارد، max_events و max_messages، که از سهمیه شامل جدا هستند. صفر یعنی بی‌سقف: مازاد صورتحساب می‌شود و همه‌چیز کار می‌کند. رد شدن از سهمیه شامل، پول خرج دارد و یک فاکتور است. رد شدن از سقف، شما را متوقف می‌کند و یک قطعی است.

فقط سقف رویداد اعمال می‌شود. هیچ مسیر کدی سنجه پیام را در برابر max_messages بررسی نمی‌کند، پس quota_message_cap هرگز رخ نمی‌دهد. این فیلد تعریف شده، اعتبارسنجی شده، روی فاکتور چاپ می‌شود، و هیچ‌جا اعمال نمی‌شود.

وقتی به سقف برسید چه می‌شود:

• درخواست کامل با ۴۰۲ رد می‌شود، هرگز نیم‌بند پذیرفته نمی‌شود. پذیرش جزئی شما را ناتوان می‌گذاشت از اینکه بفهمید کدام رویدادها را دوباره بفرستید، و به هر حال از سقف رد شده‌اید.
• بررسی یک بار برای کل دسته اجرا می‌شود، پیش از هر کار قلم‌به‌قلم.
• هر SDK دسته‌ای را که نگه داشته دور می‌ریزد، چون هر سه هر ۴xx به‌جز ۴۲۹ را دائمی می‌شمارند. آن رویدادها رفته‌اند.
• تلاش دوباره تا کسی پول ندهد هیچ‌چیز را عوض نمی‌کند.

حکم سهمیه ۱۵ ثانیه به ازای هر حساب کش می‌شود، پس می‌توانید به اندازه هرچه در آن پنجره بفرستید از سقف بزنید بیرون. دروازه باز هم شکست می‌خورد: اگر خواندن اشتراک یا مصرف خطا بدهد، ترافیک پذیرفته می‌شود.

دوره یک ماه جلالی است نه میلادی، و روزهای داخلش به وقت محلی تهران شمرده می‌شوند. دوره درست همان‌جا تمام می‌شود که دوره بعد شروع می‌شود، پس هیچ لحظه‌ای بین دو دوره نمی‌افتد.

اعلان‌ها، که چیزی را رد نمی‌کنند، روی ۳۰۰ و ۱۵۰ و ۱۲۵ و ۱۰۰ و ۸۰ درصد سهمیه شامل رخ می‌دهند، هر ماه جلالی یک بار برای هر سنجه.

#قفل نرم

یک کنترل مالی است، نه محدودیت نرخ.

اول سررسید بررسی می‌شود. حکم ۶۰ ثانیه به ازای هر حساب کش می‌شود و روی هر مسیری که نتواند بخواند، باز شکست می‌خورد. عدد پرونده‌ها تا یک ساعت عقب است، چون یک کار پس‌زمینه می‌نویسدش.

درست چهار مسیر میزبان مدیریتی را می‌بندد: GET /v1/exports و POST /v1/exports و POST /v1/reports/funnel و POST /v1/reports/retention.

بقیه به‌عمد باز می‌مانند: ورود داده، ارسال تراکنشی، ساخت کمپین، ارسال کمپین، و نوشتن سگمنت. سوراخ در داده شما را بعدها نمی‌شود پر کرد و بدهی را بعدها می‌شود وصول کرد.

همین قفل همان دو خانواده را در پنل هم می‌بندد. قفلی که یک نوع اعتبارنامه رعایتش کند و نوع دیگر نکند قفل نیست، یک دور زدن است، و آن دور زدن فاصله‌اش تا شما یک اسکریپت است.

#مهلت‌ها

سطر گزارش‌ها یک تناقض واقعی است، نه اختلاف گردکردن. قیفی که بین ۳۰ و ۴۵ ثانیه طول بکشد را سرور HTTP می‌برد، نه هندلر، پس به‌جای یک خطای تمیز یک پاسخ ناقص می‌بینید. بازه زمانی یا تعداد مراحل را کم کنید.

مهلت ۳۵ ثانیه روی کلاینت هر سقفی که اینجا هست را پوشش می‌دهد. بالاتر رفتن چیزی به شما نمی‌دهد، چون شنونده به هر حال سر ۳۰ ثانیه اتصال را می‌بندد.

#آنچه سقف ندارد

هرکدام از این‌ها سقفی است که خواننده انتظار دارد پیدا کند. هیچ‌کدامشان وجود ندارد.

• سقفی روی تعداد نام رویداد یا کلید ویژگی متمایز نیست. مقدارهای max_properties و max_traits یک payload را می‌بندند، نه اسکیمای شما را. می‌توانید ده هزار نام رویداد متمایز بسازید و هیچ‌چیز جلویتان را نمی‌گیرد. هیچ‌چیز هم مفیدشان نمی‌کند.
• سقف سطر روی خروجی نیست. مسیر POST /v1/exports سه فیلد kind و format و spec می‌گیرد، و نه max_rows دارد، نه سقف سمت سرور، و نه expected_count روی کار.
• محدودیت نرخ به ازای IP هیچ‌جای محصول نیست. نه روی میزبان ورود داده و نه روی میزبان مدیریتی.
• بودجه گیرنده نیست. هیچ‌چیز نمی‌شمارد که یک کلید در روز به چند نفر می‌تواند بفرستد، و برای همین POST /v1/messages یک واحد بودجه خرج دارد و با صد هزار فراخوانی می‌تواند به صد هزار گوشی برسد. خودتان بندش را بگذارید.
• سقف پیام اعمال نمی‌شود. بالاتر گفته شد.
• نقطه import روی میزبان مدیریتی نیست. وارد کردن CSV قابلیت پنل است، با سقف ۵۰۰۰۰۰ سطر و ۶۴ مگابایت، و API ندارد.
• هدر Accept-Language خوانده نمی‌شود. هیچ‌کدام از دو میزبان نمی‌خوانندش. متن سهمیه و قفل همیشه فارسی است.

مرتبط: کدهای خطا، API ورود داده، API مدیریتی.