سقف الحصص

لضمان الاستخدام العادل وحماية استقرار النظام، تفرض واجهات برمجة التطبيقات الخاصة بـ "الملف التجاري على Google" حصصًا على طلبات واجهة برمجة التطبيقات. إذا تجاوز طلبك حد الحصة المسموح بها، ستردّ واجهة برمجة التطبيقات برمز حالة HTTP‏ 429 Too Many Requests (أو RESOURCE_EXHAUSTED لبروتوكول gRPC).

حدود الحصة التلقائية

يعرض الجدول التالي حدود الحصة العادية لواجهات برمجة التطبيقات للملفات التجارية على Google. يتم تحديد الحدود على مستوى سمتَين:

• طلبات البحث في الدقيقة (QPM): تحمي استقرار الخلفية من خلال الحدّ من الزيارات المفاجئة القصيرة الأجل.
• طلبات البحث في اليوم: تدير الاستخدام اليومي العام للمنصة.

أفضل الممارسات لتجنُّب أخطاء الحصة

يؤدي توزيع الطلبات بشكل مستمر ومتساوٍ على مدار اليوم إلى تجنُّب معظم أخطاء الحصة. اتّبِع أفضل الممارسات التالية لضمان مزامنة تطبيقك للبيانات بشكل موثوق.

توزيع طلباتك بالتساوي

بدلاً من إرسال مجموعة كبيرة من الطلبات في الوقت نفسه، وزِّع طلباتك على فترة زمنية أطول. على سبيل المثال، يعني الحدّ الأقصى البالغ 300 طلب في الدقيقة الواحدة متوسط 5 طلبات في الثانية. يؤدي تقديم تأخير قصير بين الطلبات إلى منع الارتفاعات المفاجئة في عدد الزيارات.

Traffic distribution patterns:

Spiky traffic (Discouraged): High burst of requests followed by an idle period
Requests |   |||                 |||
         |   |||                 |||
         +---------------------------------
           Time ──>

Even traffic (Recommended): Consistent rate of requests over time
Requests |  |  |  |  |  |  |  |  |  |
         |  |  |  |  |  |  |  |  |  |
         +---------------------------------
           Time ──>

import time

# Pace requests to stay within the 300 QPM limit (5 requests/sec)
for request in batch_requests:
    send_request(request)
    time.sleep(0.2)  # 200ms delay ensures a smooth distribution

تنفيذ خوارزمية الرقود الأسي الثنائي مع التشويش

عند تلقّي الخطأ 429 Too Many Requests، استخدِم الرقود الأسي الثنائي مع التشويش لإعادة محاولة الطلب تلقائيًا. تتضمّن هذه الممارسة المعيارية الانتظار لفترة قصيرة عشوائية قبل إعادة المحاولة، وزيادة التأخير تدريجيًا في المحاولات اللاحقة.

import random
import time
from googleapiclient.errors import HttpError

def call_api_with_retry(api_method, max_retries=5):
    base_delay = 1.0
    for attempt in range(max_retries):
        try:
            return api_method.execute()
        except HttpError as e:
            if e.resp.status == 429:
                if attempt == max_retries - 1:
                    raise e
                # Retry with exponential backoff and jitter
                sleep_time = random.uniform(0, base_delay * (2 ** attempt))
                time.sleep(sleep_time)
            else:
                raise e

تحسين الوصول إلى البيانات

• تخزين البيانات الثابتة مؤقتًا: يمكنك تخزين البيانات التي لا تتغيّر كثيرًا محليًا بدلاً من طلبها بشكل متكرر من واجهة برمجة التطبيقات.
• استخدام إشعارات Pub/Sub: اشترِك في إشعارات Pub/Sub لإبقاء قواعد البيانات محدّثة في الوقت الفعلي بدون طلب البيانات من واجهة برمجة التطبيقات بشكل متكرّر.
• معالجة نقاط النهاية التي تتضمّن عمليات قراءة كثيرة بالتسلسل: تجنَّب تنفيذ طلبات متزامنة متعددة لنقاط النهاية التي تتضمّن عمليات قراءة كثيرة، مثل SearchListings. بدلاً من ذلك، عالِج المهام بالتسلسل باستخدام رموز مميّزة لتقسيم النتائج إلى صفحات.

طلب زيادة الحصة

قبل طلب زيادة الحصة، تحقَّق من أنماط الاستخدام في Google Cloud Console للتأكّد من أنّ عدد الطلبات ليس مجمّعًا بدون داعٍ.

يراقب فريق "الملف التجاري على Google" متوسط استخدامك للحصة المخصّصة للتأكّد من أنّك تستخدم الحدود الحالية بكفاءة. يتم عادةً رفض طلبات زيادة الحصة في الحالات التالية:

• لا يصل تطبيقك باستمرار إلى الحدّ الأقصى الحالي لعدد الطلبات في الدقيقة.
• أن يكون متوسط استخدامك أقل من% 50 من الحدّ الحالي لعدد الطلبات في الدقيقة
• يُظهر تطبيقك نمط طلبات متزايدًا بشكل كبير بدلاً من التوزيع السلس.

إرسال طلب

إذا كنت قد طبّقت أفضل الممارسات هذه وما زلت بحاجة إلى حصة أكبر، أرسِل طلبًا لزيادة الحصة.

1. اختَر طلب زيادة الحصة من القائمة المنسدلة.
2. قدِّم اسم الشركة وعنوان البريد الإلكتروني لجهة الاتصال ورقم المشروع.

بعد إرسال النموذج، سيراجع فريق "الملف التجاري على Google" طلبك ويحدّد ما إذا كانت زيادة الحصة مناسبة. في حال الموافقة على الطلب، ستتم زيادة الحصة. في حال رفض الطلب، ستتلقّى سبب الرفض.