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

سير العمل

دوال مساعدة مركبة تنفّذ عدة استدعاءات لحزمة SDK وتُعيد نتيجة واحدة مجمّعة عبر client.workflows.

جميع أساليب سير العمل موجودة ضمن client.workflows. يحل كل منها محل سلسلة من استدعاءات SDK العادية التي كنت ستكتبها بنفسك، ويُرجع نتيجة موحدة تُجمَّع على جانب العميل. لا توجد نقطة نهاية REST واحدة وراء سير العمل، لذا فإن مفاتيح النتيجة هي الأسماء الخاصة بـ SDK، وليست أسماء الحقول المنقولة في استجابة REST.

لأن سير العمل يُجري عدة استدعاءات، يحتاج مفتاح API الذي يعمل به إلى صلاحية الوصول إلى كل مورد يستخدمه سير العمل، ويُحتسب استدعاء سير العمل ضمن حد معدل الطلبات مرة واحدة لكل طلب يُجريه داخليًا. تقبل الأساليب المعامل location_id، الذي يقبل معرّفات رقمية أو مرمّزة بصيغة base64، راجع معرّفات المواقع.

workflows.auto_reply_to_reviews

رُدّ على تقييمات موقع باستخدام قالب، في استدعاء واحد. استخدمه للحفاظ على ارتفاع معدلات الرد على التقييمات الإيجابية بينما تتولى الرد على البقية يدويًا.

Python
client.workflows.auto_reply_to_reviews(    location_id: str | int,    *,    template: str = "Thank you for your feedback!",    min_rating: int = 4,    only_unanswered: bool = True,    dry_run: bool = False,) -> list[dict[str, Any]]
المعاملالنوعالوصف
location_idstr | intالموقع المطلوب معالجته.
templatestrنص الرد على التقييمات المطابقة. يُستبدل {rating} بعدد النجوم في التقييم.
min_ratingintالرد فقط على التقييمات التي تحمل هذا التقييم أو تقييمًا أعلى. القيمة الافتراضية هي 4.
only_unansweredboolتخطي التقييمات التي لها رد بالفعل. القيمة الافتراضية هي True.
dry_runboolإرجاع التقييمات التي سيُردّ عليها دون نشر الردود. القيمة الافتراضية هي False.

يحل محل reviews.list مع التنقل بين الصفحات باستخدام auto_paging_iter()، ثم استدعاء واحد لـ reviews.respond لكل تقييم يستوفي شرطي التصفية.

Python
# See what would be sent, without postingplan = client.workflows.auto_reply_to_reviews(  16808,  template="Thanks for the {rating}-star review!",  min_rating=4,  dry_run=True,)for entry in plan:  print(entry["id"], entry["rating"], entry["status"]) # Then post for realresults = client.workflows.auto_reply_to_reviews(16808, min_rating=4)print(f"Replied to {len(results)} reviews")

يُرجع قائمة عادية من القواميس، قاموسًا واحدًا لكل تقييم عالجه، ويحتوي كل منها على id وrating وreply وstatus. شغّله أولًا باستخدام dry_run=True: تُرجع العناصر مع تعيين status إلى dry_run حتى تتمكن من التحقق من التقييمات المحددة قبل نشر أي رد.

workflows.listings_health_audit

اجلب نظرة عامة على إدراجات الأنشطة التجارية لموقع في استدعاء واحد: الإدراجات المميزة، والإدراجات الصوتية، والإدراجات المكررة، ودرجة التقييم. استخدمه لإنشاء لوحة لحالة إدراجات الأنشطة التجارية لكل موقع بدلًا من إجراء 3 استدعاءات منفصلة.

Python
client.workflows.listings_health_audit(location_id: str | int) -> APIObject

يحل محل listings.premium وlistings.voice وlistings.duplicates للموقع نفسه، مع حساب عدد النتائج المميزة بحسب syncStatus.

Python
audit = client.workflows.listings_health_audit(16808)print(f"Health score: {audit.health_score}%")print(f"Synced: {audit.synced_count} of {len(audit.premium)}")print(f"Duplicates found: {len(audit.duplicates)}")for issue in audit.issues:  print(issue.get("site"), issue.get("syncStatus"))

يُرجع كائنًا من النوع APIObject يحتوي على location_id وpremium وvoice وduplicates وsynced_count وissue_count وissues وhealth_score. يمثّل health_score نسبة إدراجات الأنشطة التجارية المميزة التي تكون قيمة syncStatus فيها هي SYNCED، كنسبة مئوية بعدد صحيح، وتكون قيمته 0 عند عدم وجود إدراجات أنشطة تجارية مميزة. يحتوي issues على إدراجات الأنشطة التجارية المميزة التي يوجد فيها syncStatus ولا يساوي SYNCED.

workflows.weekly_reputation_report

استرجع التقييمات وتحليلات التقييمات وتحليلات الملف التعريفي وحالة مزامنة إدراجات الأنشطة التجارية لموقع واحد خلال فترة زمنية. استخدمه لتقرير دوري بدلًا من لوحة تحكم مباشرة، لأنه يُجري 5 استدعاءات.

Python
client.workflows.weekly_reputation_report(    location_id: str | int,    *,    start_date: str | None = None,    end_date: str | None = None,) -> APIObject

كل من start_date وend_date سلسلة نصية بصيغة YYYY-MM-DD، وكلاهما اختياري. يحل محل reviews.analytics.overview وreviews.list مع first=50 وanalytics.google وanalytics.bing وlistings.premium، مع تمرير الفترة الزمنية إلى كل استدعاء يقبلها.

Python
report = client.workflows.weekly_reputation_report(  16808,  start_date="2026-09-01",  end_date="2026-09-07",)print(report.review_summary.get("averageRating"))print(report.analytics.get("google", {}).get("views"))print(report.listings_health.get("sync_rate"))

يُرجع كائنًا من النوع APIObject يحتوي على location_id وreview_summary (نظرة عامة على تحليلات التقييمات) وrecent_reviews (ما يصل إلى 50 تقييمًا خلال الفترة) وanalytics (قاموس يحتوي على google وbing) وlistings_health (قاموس يحتوي على total وsynced وsync_rate). يمثّل sync_rate سلسلة نصية منسقة كنسبة مئوية، وتكون قيمته N/A عندما لا يكون للموقع أي إدراجات أنشطة تجارية مميزة.

انظر أيضًا