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

يوضِّح هذا المستند طريقة استخدام واجهة برمجة التطبيقات Custom Search JSON API.

تقديم طلب

تختلف واجهة برمجة التطبيقات REST أو Representational State Transfer في Custom Search JSON API إلى حدّ ما عن واجهات برمجة التطبيقات RESTful المعتادة. بدلاً من إتاحة الوصول إلى الموارد، توفّر واجهة برمجة التطبيقات إمكانية الوصول إلى خدمة. نتيجةً لذلك، توفّر واجهة برمجة التطبيقات معرّف موارد منتظمًا واحدًا يعمل كنقطة نهاية للخدمة.

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

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. يمكنك البحث عن بنية data في المرجع.

بيانات الاستجابة هي عنصر 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>
    <p id="demo"></p>
    <script>
    function hndlr(response) {
      if (response.items == null) {
        document.getElementById("demo").innerHTML +=`<h3> No Results Found </h3>`;
      } else {
        for (var i = 1; 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=lecture&callback=hndlr">
    </script>
  </body>
</html>