نتایج گوگل

محدودیت نرخ

سطل توکن در سرویس نتایج گوگل، سه هدر X-RateLimit، رفتار در ۴۲۹ و اینکه چرا باید Retry-After را رعایت کنید نه محاسبهٔ دوباره.

محدودیت نرخ در این سرویس بر اساس هر کلید API است، به شکل سطل توکن، و فقط روی اندپوینت‌های /api/v1/operator اعمال می‌شود.

اگر از مسیرهای قدیمی /api/* استفاده می‌کنید، محدودیت نرخ اعمال نمی‌شود. مهاجرت کنید، ولی تا آن موقع ندانید هدرهای X-RateLimit را می‌گیرید یا نه. جزئیات در مسیرهای قدیمی.

سطل توکن یعنی چه

سطل توکن یعنی هر کلید، ظرفیت انباشتی دارد که به مرور پر می‌شود و با هر درخواست خالی می‌شود.

ویژگی	رفتار
واحد حساب	هر کلید API، جدا از بقیه
سقف	همان چیزی است که `X-RateLimit-Limit` می‌گوید
مصرف	هر درخواست یک توکن
شارژ	پیوسته، تا سقف

سقف‌های دقیق را از GET /capabilities بگیرید — عدد ثابتی در این مستندات نیست.

هدرها

روی پاسخ‌های API منابع:

هدر	یعنی چه
`X-RateLimit-Limit`	سقف سطل، یعنی اندازهٔ جهش (burst)
`X-RateLimit-Remaining`	توکن باقی‌مانده در سطل همین کلید
`X-RateLimit-Reset`	ثانیهٔ epochی که سطل دوباره پر می‌شود

وقتی از بودجه رد شدید

HTTP/1.1 429
Retry-After: 12
X-RateLimit-Remaining: 0

{"detail": "rate limit exceeded"}

Retry-After را رعایت کنید

Retry-After ثانیه است و هرگز 0 نمی‌شود. آن را رعایت کنید، نه اینکه از هدرها دوباره حساب کنید.

چرا محاسبهٔ دوباره کار نمی‌کند: چون این سطل توکن است، نه پنجرهٔ ثابت. اگر از روی هدرها زمان را دوباره حساب کنید، ممکن است درست روی مرز پنجره کل اعتبارتان را در چند درخواست پشت‌سرهم خرج کنید و بعد به 429 بخورید — دقیقاً همان چیزی که سطل برای جلوگیری از آن ساخته شده. Retry-After را بخوانید و صبر کنید.

پیاده‌سازی پیشنهادی

import time

def request_with_backoff(session, method, url, **kw):
    resp = session.request(method, url, **kw)

    if resp.status_code == 429:
        wait = int(resp.headers["Retry-After"])   # ثانیه، هرگز صفر نیست
        time.sleep(wait)
        return session.request(method, url, **kw)

    return resp

تصمیم	چرا
صبر بر اساس `Retry-After`	تنها عددی که سرویس دربارهٔ سطل اعلام می‌کند
بیشینهٔ تلاش را ۲ یا ۳ نگه دارید	یک `429` طولانی یعنی الگوی مصرف شما غلط است، نه اینکه صبر بیشتر جواب دهد
نرخ درخواست را کم کنید	تلاش مجدد فوری فقط زودتر به `429` بعدی می‌رسید
`429` را retry کنید	برخلاف `401` و `403`، با زمان حل می‌شود

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

پیش‌بینی به‌جای واکنش

هدرها کمک می‌کنند پیش از رسیدن به 429 کمی سرعت را کم کنید:

خواندن هدر	معنی
`Remaining` نزدیک صفر	سطل رو به خالی‌شدن است
`Remaining` صفر شد	درخواست بعدی `429` می‌گیرد
`Reset` خیلی دور است	بودجهٔ شما برای این بازه کم است

برای پردازش پس‌زمینه، GET /usage را ببینید، نه فقط هدرها. شمارنده‌های دوره به شما می‌گویند کار پس‌زمینه‌تان در مقیاس چه اندازه است؛ در مصرف توضیح داده شده.

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

Retry-After به ثانیه است، هرگز 0

مصرف

صفحه‌بندی