دليل المطوّرين لواجهة Play Catalog API

ملاحظة: سيتم إطلاق واجهة برمجة التطبيقات Play Catalog API في 22 يوليو 2026

تتيح واجهة برمجة التطبيقات Play Catalog لمتاجر التطبيقات الخارجية (3PAS) المسجّلة على Google Play إمكانية طلب البحث عن تحديثات لكتالوج تطبيقات Google Play. يمكن لمقدّمي الطلبات استرداد تفاصيل الكتالوج للتطبيقات التي تم تعديلها أو إزالتها منذ آخر عملية تصدير يومية للكتالوج.

ملاحظة: واجهة Play Catalog API هي إضافة اختيارية إلى عملية تصدير الكتالوج اليومية، وتوفّر مجموعة المعلومات نفسها. إذا لم تكن بحاجة إلى بيانات أحدث من 24 ساعة، ليس من الضروري إجراء عملية الدمج مع واجهة برمجة التطبيقات هذه.

ملاحظة: لا يمكن استخدام Play Catalog API إلا لاسترداد البيانات التي تم تغييرها مؤخرًا. ولا يمكن استخدامه لاسترداد فهرس كامل. يجب استخدام عملية تصدير الكتالوج للحصول على الكتالوج الكامل لجميع التطبيقات.

للاطّلاع على قائمة كاملة بنقاط النهاية والطُرق ومخططات الموارد، يُرجى الرجوع إلى مرجع واجهة برمجة التطبيقات Play Catalog.

قبل البدء

يجب إكمال دليل البدء الرئيسي لإعداد إذن الوصول إلى واجهة برمجة التطبيقات وبيانات اعتماد الخدمة ومشروع Google Cloud قبل إجراء طلبات إلى Play Catalog API.

---

تصميم واجهات برمجة التطبيقات وبنيتها

يتم إنشاء عملية تصدير "كتالوج Play" كل 24 ساعة. توفّر واجهة برمجة التطبيقات Play Catalog API آلية استطلاع خلال اليوم لاسترداد التعديلات التي تم إجراؤها منذ آخر عملية تصدير:

1. التحقّق من أحداث التعديل: يمكنك طلب البحث باستخدام appstorecatalog.recentUpdateEvents.list مع startTime وendTime للعثور على أسماء الحِزم التي تم تعديلها أو حذفها.
2. استرداد طرق العرض التفصيلية: لكل اسم حزمة تم تعديله، عليك استدعاء appstorecatalog.recentAppViews.get لاسترداد البيانات الوصفية التفصيلية CatalogAppView.

تكون واجهة برمجة التطبيقات للقراءة فقط، ويقتصر عملها على عرض الأحداث التي وقعت خلال آخر 36 ساعة. تفرض واجهة برمجة التطبيقات حدًا أقصى يبلغ 2 طلب في الثانية على الطريقتَين معًا.

---

1. التحقّق من أحداث تعديل الكتالوج

لاسترداد قائمة الحِزم التي تم تغييرها خلال فترة زمنية محدّدة، استدعِ طريقة appstorecatalog.recentUpdateEvents.list.

ولا يتم عرض سوى أحداث التحديث للتطبيقات المؤهَّلة. يجب أن تكون التطبيقات المؤهَّلة:

• تمت الموافقة على إدراج التطبيق في كتالوج متجر تطبيقات الاتصال.
• أن يكون منشورًا ومتاحًا في الولايات المتحدة على "متجر Google Play"

ملاحظة: يُنصح بالبحث عن أحداث التحديث بشكل متكرر، مثلاً كل دقيقة. قد يؤدي إجراء الاستطلاع بشكل غير متكرر إلى عرض عدد كبير من أحداث التعديل في وقت واحد، ما قد يصعّب معالجتها في الوقت المناسب.

فهم أنواع التحديثات

• MODIFICATION: يتم تشغيلها عند تعديل تطبيق مؤهَّل أو نشره للمرة الأولى أو عندما يبدأ في استهداف الولايات المتحدة أو عندما يوافق التطبيق حديثًا على الانضمام إلى كتالوجك.
• ‫DELETION: يتم تشغيل هذا الإشعار عندما يتم إلغاء نشر تطبيق أو إيقاف مشاركته في الكتالوج أو تعليقه أو حظره أو عندما يتوقف عن استهداف الولايات المتحدة.

---

2. استرداد مشاهدات التطبيقات في الكتالوج

بالنسبة إلى كل حزمة يتم عرضها مع حدث MODIFICATION، يمكنك استرداد تفاصيل الكتالوج المعدَّلة من خلال استدعاء الطريقة appstorecatalog.recentAppViews.get.

ملاحظة: أخطاء "لم يتم العثور على"
تعرض الطريقة appstorecatalog.recentAppViews.get الخطأ NOT_FOUND (404) إذا لم تحدث أي أحداث تحديث لاسم الحزمة المطلوب خلال آخر 36 ساعة. في هذه الحالة، عليك الرجوع إلى استخدام عملية التصدير اليومية الكاملة للكتالوج.

---

3- أفضل الممارسات والمزامنة

للحفاظ على اتساق قاعدة بيانات الكتالوج في متجرك، اتّبِع إرشادات الدمج التالية:

• مزامنة التصدير اليومي: استورِد القائمة الكاملة للتطبيقات المؤهَّلة باستخدام تصدير الكتالوج اليومي.
• (اختياري) المزامنة خلال اليوم: يمكنك إرسال طلبات إلى نقطة النهاية appstorecatalog.recentUpdateEvents.list بانتظام (مثلاً، كل دقيقة) باستخدام نافذة زمنية متحرّكة. تأكَّد من التعامل مع تقسيم المحتوى إلى صفحات باستخدام nextPageToken.
  • تعديلات على العملية:
    • بالنسبة إلى أحداث MODIFICATION، استرجِع CatalogAppView المعدَّل باستخدام appstorecatalog.recentAppViews.get وعدِّل قاعدة البيانات المحلية.
    • بالنسبة إلى أحداث DELETION، عليك إزالة التطبيق من بطاقات بيانات المتجر أو إخفائه عن المستخدمين.
  • التعامل مع أحداث التعديل المتكرّرة: قد تظهر لك أحداث MODIFICATION متعددة للتطبيق نفسه، ما يعني أنّه تم تعديل التطبيق عدة مرات في الفترة الزمنية المحدّدة في طلب البحث. ستعرض السمة appstorecatalog.recentAppViews.get دائمًا طريقة عرض التطبيق التي تتضمّن آخر التعديلات.