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

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

تقديم طلب

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

يمكنك استرداد نتائج بحث معيّن من خلال إرسال طلب HTTP GET إلى معرّف الموارد المنتظم (URI) الخاص به. يمكنك تمرير تفاصيل طلب البحث كمعلمات طلب البحث. يكون تنسيق معرّف الموارد المنتظم (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. يمكنك البحث السريع عن بنية بيانات الاستجابة في المرجع.

بيانات الاستجابة هي عنصر JSON يتضمّن ثلاثة أنواع من السمات:

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

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

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

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

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

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

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

نتائج البحث

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

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

REST من JavaScript

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

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

<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>