سيساعدك هذا المستند في الإلمام بواجهة Custom Search JSON API واستخدامها.
قبل البدء
إنشاء محرك بحث مبرمج
من خلال استدعاء واجهة برمجة التطبيقات التي يصدر عنها طلبات بشأن مثيل حالي من "محرك البحث المبرمَج".
لذلك، قبل استخدام واجهة برمجة التطبيقات، عليك إنشاء واجهة في لوحة التحكم
. اتّبِع البرنامج التعليمي
لمعرفة المزيد من المعلومات حول خيارات الضبط المختلفة.
وبعد إنشائه، يمكنك العثور على رقم تعريف محرك البحث في القسم أساسي من صفحة نظرة عامة. هذه هي المَعلمة cx التي تستخدمها واجهة برمجة التطبيقات.
تحديد تطبيقك لدى Google باستخدام مفتاح واجهة برمجة التطبيقات
تتطلب واجهة برمجة التطبيقات Custom Search JSON API استخدام مفتاح واجهة برمجة التطبيقات. يمثّل مفتاح واجهة برمجة التطبيقات طريقة تعرّف Google على عميلك.
- مستخدمو محرك البحث المبرمج (الإصدار المجاني): الحصول على مفتاح
بعد الحصول على مفتاح واجهة برمجة التطبيقات، يمكن لتطبيقك إلحاق معلَمة طلب البحث
key=yourAPIKey بجميع عناوين URL للطلبات. ويمكن تضمين مفتاح واجهة برمجة التطبيقات بأمان في عناوين URL،
ولا يحتاج إلى أي ترميز.
نظرة عامة على واجهة برمجة التطبيقات
عمليات واجهة برمجة التطبيقات
هناك طريقة واحدة فقط للاستدعاء في واجهة برمجة التطبيقات Custom Search JSON API:
| العملية | الوصف | تعيين REST HTTP |
|---|---|---|
| list | تعرض نتائج البحث المطلوبة من "محرك البحث المبرمَج". | GET |
نموذج بيانات واجهة برمجة التطبيقات
نتيجة طلب البحث لواجهة Custom Search JSON API هي كائن JSON يتضمن ثلاثة أنواع من البيانات:
- البيانات الوصفية التي تصف البحث المطلوب (وربما طلبات البحث ذات الصلة)
- البيانات الوصفية التي تصف "محرك البحث المبرمَج"
- نتائج البحث
للحصول على مزيد من التفاصيل، راجِع قسم بيانات الاستجابة حول استخدام REST.
يستند نموذج البيانات إلى مواصفات OpenSearch 1.1. بالإضافة إلى خصائص OpenSearch العادية، تحدّد واجهة برمجة التطبيقات Custom Search JSON API خاصيتَين مخصّصتَين ودورَين مخصّصَين لطلب البحث:
- الخصائص المخصّصة
cx: معرّف "محرك البحث المبرمَج"safe: وصف لمستوى البحث الآمن لفلترة النتائج المعروضة.
- الأدوار المخصّصة لطلبات البحث
nextPage: دور يشير إلى إمكانية استخدام طلب البحث للوصول إلى الصفحة المنطقية التالية من النتائج، إن توفّرت.previousPage: دور يشير إلى إمكانية استخدام طلب البحث للوصول إلى صفحة النتائج المنطقية السابقة، إن توفّرت.
تجربة الميزة
للتعرّف على الإجراءات التي يمكن لواجهة برمجة التطبيقات تنفيذها بدون كتابة أي رمز، يُرجى الانتقال إلى أداة"تجربة واجهة برمجة التطبيقات هذه".
للحصول على وصف كامل للمعلَمات، يُرجى الانتقال إلى مرجع cse.list.
للاطّلاع على طريقة استخدام واجهة برمجة التطبيقات عبر طلبات HTTP، يمكنك الانتقال إلى استخدام REST.