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