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

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

تقديم طلب

تختلف REST، أو Representational State Transfer، في واجهة برمجة التطبيقات Custom Search JSON API بعض الشيء عن 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 وتحديد طلب البحث في المرجع.

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

يتم توثيق مَعلمات طلب البحث التي تنطبق على جميع عمليات Custom Search JSON API في معلَمات النظام.

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

إذا نجح الطلب، يستجيب الخادم برمز حالة 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>