Listings APIListings API
تسجيل الدخول

الإعدادات

اضبط إعدادات عميل Listings API بلغة Python: مفتاح API، وعنوان URL الأساسي، والمهلة، وإعادة المحاولة، وتسجيل السجلات.

توقيع الدالة البانية

Python
listingsapi.ListingsAPI(    api_key: str | None = None,    *,    base_url: str | None = None,    timeout: float = 240.0,    max_retries: int = 2,)

جميع الوسائط اختيارية. إذا لم يُمرَّر api_key، يقرأ العميل LISTINGSAPI_KEY من البيئة ويُطلق الاستثناء AuthenticationError عند إنشاء الكائن إذا لم تُحدَّد قيمة لأيٍّ منهما.

الخيارات

الخيارالنوعالقيمة الافتراضيةالوصف
api_keystr | NoneNoneمفتاح API. يُستخدم متغير البيئة LISTINGSAPI_KEY إذا لم يُحدَّد المفتاح.
base_urlstr | Nonehttps://listingsapi.comعنوان الأصل لواجهة API. تُزال الشرطة المائلة الختامية تلقائيًا.
timeoutfloat240.0مهلة كل طلب بالثواني (تُطبَّق على كل طلب HTTP على حدة).
max_retriesint2إعادة المحاولة تلقائيًا عند تلقي استجابات 429 و5xx. عيّن القيمة إلى 0 لتعطيل إعادة المحاولة.

مفتاح API

bash
export LISTINGSAPI_KEY="your-api-key"
Python
import listingsapi # From environment (recommended)client = listingsapi.ListingsAPI() # Explicit keyclient = listingsapi.ListingsAPI(api_key="your-api-key")

المهلة

القيمة الافتراضية هي 240.0 ثانية. بالنسبة إلى البرامج النصية التي تعمل لمدة قصيرة أو الاستخدام التفاعلي، قد تحتاج إلى مهلة أقصر:

Python
client = listingsapi.ListingsAPI(timeout=30.0)

تُطبَّق المهلة على كل طلب HTTP على حدة. تلتزم استدعاءات جلب الصفحات دفعة واحدة (auto_paging_iter) بمهلة كل طلب بصورة مستقلة.

إعادة المحاولة

تُثبّت حزمة SDK مُهايئ urllib3 Retry على جلسة requests الخاصة بها، ويُعيد هذا المُهايئ المحاولة تلقائيًا عند تلقي استجابات 429 و500 و502 و503 و504، ولكن لطرق HTTP الآمنة فقط: GET وHEAD وOPTIONS. تُرسَل عمليات الكتابة (POST وDELETE) مرة واحدة فقط، ويُطلَق استثناء الفشل فورًا. العدد الافتراضي لإعادات المحاولة هو 2، مع عامل تأخير أُسّي قدره 0.5 ثانية. تُراعى ترويسات Retry-After، لذا تُعاد المحاولة عند تلقي 429 يُحدِّد مدة انتظار بعد انقضاء تلك المدة بالضبط.

لا تدعم واجهة API بالإصدار v4 الميزة Idempotency-Key ولا تكتشف عمليات الكتابة المتكررة، لذا قد تكون عملية الكتابة التي تنتهي مهلتها أو تُرجع 5xx قد حُفظت بالفعل. قد تؤدي إعادة المحاولة دون تحقق إلى إنشاء موقع أو منشور أو رد على تقييم مرة ثانية. اقرأ السجل مجددًا باستخدام مفتاح تتحكم فيه قبل تكرار عملية الكتابة.

Python
# More aggressive retry for long-running batch jobsclient = listingsapi.ListingsAPI(max_retries=5) # Disable retries entirely (e.g. when you want fast failures)client = listingsapi.ListingsAPI(max_retries=0)

إذا استمر 429 بعد كل محاولات الإعادة، يُطلَق بوصفه RateLimitError؛ راجع معالجة الأخطاء للاطلاع على طريقة لتطبيق التأخير بين المحاولات يدويًا.

تجاوز عنوان URL الأساسي

مفيد لبيئات الاختبار المرحلي أو الوكلاء الداخليين:

Python
client = listingsapi.ListingsAPI(base_url="https://staging.example.com")

تُزال الشرطة المائلة الختامية تلقائيًا. تُرسَل جميع الطلبات ضمن المسار /api/v4/ على هذا الأصل.

تسجيل السجلات

تُسجِّل حزمة SDK عبر الوحدة القياسية logging باستخدام المُسجِّل listingsapi. عند المستوى DEBUG، تُسجِّل طريقة HTTP وعنوان URL لكل طلب (ومعاملات الاستعلام لطلبات GET)؛ ولا تُسجَّل أجسام الطلبات ولا مفتاح API الخاص بك مطلقًا.

Python
import logginglogging.basicConfig()logging.getLogger("listingsapi").setLevel(logging.DEBUG) import listingsapiclient = listingsapi.ListingsAPI()client.locations.list(first=1)

الخطوات التالية