استخدام REST لاستدعاء واجهة برمجة التطبيقات

يوضّح هذا المستند كيفية استخدام Custom Search JSON API.

تقديم طلب

REST أو النقل التمثيلي للولاية في واجهة برمجة تطبيقات JSON للبحث المخصص إلى حد ما عن REST التقليدي. فبدلاً من توفير الوصول إلى الموارد، توفر واجهة برمجة التطبيقات إمكانية الوصول إلى الخدمات. ونتيجةً لذلك، توفّر واجهة برمجة التطبيقات عنوان URI واحدًا يعمل كنقطة نهاية الخدمة.

يمكنك استرداد نتائج عملية بحث معيّنة من خلال إرسال عنوان HTTP يتضمّن GET. إلى عنوان URI الخاص به. أنت تمرر تفاصيل طلب البحث مَعلمات طلب البحث. يكون تنسيق معرّف الموارد المنتظم (URI) لواجهة برمجة تطبيقات JSON للبحث المخصص:

https://www.googleapis.com/customsearch/v1?[parameters]

يجب إدخال ثلاثة طلبات بحث [parameters] مع كل طلب بحث:

• مفتاح واجهة برمجة التطبيقات - استخدِم معلَمة طلب البحث key من أجل تحديد تطبيقك

• رقم تعريف محرك البحث المبرمَج: استخدِم cx لتحديد محرك البحث المبرمَج الذي تريد استخدامه لإجراء هذا البحث يجب إنشاء محرك البحث باستخدام لوحة التحكم. ملاحظة: يمكن أن يكون تنسيق معرّف محرك البحث (cx) مختلفًا (على سبيل المثال، 8ac1ab64606d234f1).

• طلب البحث - استخدِم معلمة طلب البحث q لتحديد تعبير البحث.

جميع مَعلمات طلب البحث الأخرى اختيارية.

في ما يلي مثال على طلب يبحث في اختبار "محرك البحث المبرمَج" للمحاضرات:

GET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lectures

معامِلات طلب البحث

هناك نوعان من المعلمات التي يمكنك تمريرها في طلبك:

• المعلمات الخاصة بواجهة برمجة التطبيقات - تحديد خصائص البحث، مثل تعبير البحث وعدد النتائج واللغة وما إلى ذلك
• مَعلمات طلب البحث العادية: تحدّد الجوانب الفنية لطلبك، مثل مفتاح واجهة برمجة التطبيقات.

يجب أن يكون عنوان URL مرمّزًا لكل قيم المَعلمات.

مَعلمات طلب البحث الخاصة بواجهة برمجة التطبيقات

اطلب المعلمات التي تنطبق تحديدًا على Custom Search JSON API وحدد طلب البحث في المرجع

مَعلمات طلب البحث العادية

يتم توثيق معلمات طلب البحث التي تنطبق على كل عمليات واجهة برمجة تطبيقات JSON للبحث المخصص على مَعلمات النظام

بيانات الاستجابة

إذا نجح الطلب، يستجيب الخادم برمز حالة HTTP 200 OK. وبيانات الاستجابة بتنسيق JSON. يمكنك البحث عن بيانات الرد في المرجع.

بيانات الاستجابة هي كائن JSON يتضمن ثلاثة أنواع من المواقع:

• البيانات الوصفية التي تصف البحث المطلوب (وربما طلبات البحث ذات الصلة)
• البيانات الوصفية التي تصف محرك البحث المبرمَج
• نتائج البحث

للحصول على وصف تفصيلي لكل موقع، يُرجى الاطّلاع على المرجع

البيانات الوصفية لطلب البحث

تشمل البيانات الوصفية للبحث ما يلي:

• الموقع الإلكتروني url، الذي يضم معلومات عن نموذج OpenSearch المستخدمة للنتائج التي تم إرجاعها في هذا الطلب.
• السمة queries، وهي مصفوفة من تصف خصائص عمليات البحث المحتملة. اسم كل منها في الصفيفة هي إما اسم دور طلب OpenSearch أو أحد الدورَين المخصّصَين المحدّدَين في واجهة برمجة التطبيقات هذه: previousPage وnextPage عناصر الأدوار المحتملة لطلب البحث تشمل:
  • request: البيانات الوصفية التي تصف طلب البحث لمجموعة حالية من نتائجك.
    • ويكون هذا الدور متاحًا دائمًا في الردّ.
    • إنها دائمًا صفيفة تحتوي على عنصر واحد فقط.
    • nextPage: البيانات الوصفية التي تصف طلب البحث المطلوب استخدامه في الإجراء التالي صفحة من النتائج.
      • لا يتوفّر هذا الدور إذا كانت النتائج الحالية هي الصفحة الأخيرة. ملاحظة: تعرض واجهة برمجة التطبيقات هذه أول 100 نتيجة فقط.
      • عند وجودها، تكون دائمًا صفيفًا يشتمل على عنصر واحد فقط.
  • previousPage: البيانات الوصفية التي تصف طلب البحث المطلوب استخدامه الصفحة السابقة من النتائج.
    • لا تظهر إذا كانت النتائج الحالية هي الصفحة الأولى.
    • عند وجودها، تكون دائمًا صفيفًا يشتمل على عنصر واحد فقط.

البيانات الوصفية لمحرّك البحث

تحتوي السمة context على بيانات وصفية تصف محرّك البحث. الذي أجرى طلب البحث. وهو يتضمن اسم محرك البحث وأي كائنات واجهة يوفرها تحسين البحث.

نتائج البحث

تحتوي المصفوفة items على نتائج البحث الفعلية. شبكة البحث تتضمن عنوان URL والعنوان والمقتطفات النصية التي تصف النتيجة. ضِمن بالإضافة إلى ذلك، يمكنها أن تحتوي على مقتطف منسق المعلومات، إذا كان ذلك منطبقًا.

إذا كانت نتائج البحث تتضمّن السمة promotions، هذا يعني أنّها تحتوي على مجموعة من العروض الترويجية.

REST من JavaScript

يمكنك استدعاء Custom Search JSON API باستخدام REST من JavaScript، معلَمة طلب البحث callback ودالة رد اتصال. يتيح لك ذلك كتابة تطبيقات غنية تعرض بيانات "محرك البحث المبرمَج" بدون كتابة أي رمز جهة الخادم.

يستخدم المثال التالي هذا الأسلوب لعرض الصفحة الأولى من نتائج البحث. نتائج طلب البحث السيارات:

<html>
  <head>
    <title>Custom Search JSON API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function hndlr(response) {
      for (var i = 0; i < response.items.length; i++) {
        var item = response.items[i];
        // Make sure HTML in item.htmlTitle is escaped.
        document.getElementById("content").append(
          document.createElement("br"),
          document.createTextNode(item.htmlTitle)
        );
      }
    }
    </script>
    <script src="https://www.googleapis.com/customsearch/v1?key=YOUR-KEY&cx=017576662512468239146:omuauf_lfve&q=cars&callback=hndlr">
    </script>
  </body>
</html>