سيساعدك هذا المستند في التعرّف على واجهة 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.