استفاده از REST برای فراخوانی API

این سند نحوه استفاده از جستجوی سفارشی JSON API را شرح می دهد.

درخواست کردن

REST یا Representational State Transfer در جستجوی سفارشی JSON API تا حدودی با REST سنتی متفاوت است. API به جای دسترسی به منابع، دسترسی به یک سرویس را فراهم می کند. در نتیجه، API یک URI واحد را ارائه می دهد که به عنوان نقطه پایانی سرویس عمل می کند.

می توانید با ارسال یک درخواست HTTP GET به URI آن، نتایج را برای یک جستجوی خاص بازیابی کنید. شما جزئیات درخواست جستجو را به عنوان پارامترهای پرس و جو ارسال می کنید. فرمت جستجوی سفارشی JSON API URI این است:

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

با هر درخواست جستجو، سه [parameters] مورد نیاز است:

  • کلید API - از پارامتر پرس و جوی key برای شناسایی برنامه خود استفاده کنید.

  • شناسه موتور جستجوی قابل برنامه ریزی - از cx برای تعیین موتور جستجوی قابل برنامه ریزی که می خواهید برای انجام این جستجو استفاده کنید، استفاده کنید. موتور جستجو باید با کنترل پنل ایجاد شود توجه: شناسه موتور جستجو (cx) می‌تواند با فرمت‌های مختلف باشد (مثلاً 8ac1ab64606d234f1)

  • عبارت جستجو - از پارامتر q query برای مشخص کردن عبارت جستجوی خود استفاده کنید.

سایر پارامترهای پرس و جو اختیاری هستند.

در اینجا نمونه ای از درخواستی است که موتور جستجوی قابل برنامه ریزی آزمایشی را برای سخنرانی ها جستجو می کند:

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

پارامترهای پرس و جو

دو نوع پارامتر وجود دارد که می توانید در درخواست خود ارسال کنید:

  • پارامترهای خاص API - ویژگی های جستجوی شما را تعریف می کند، مانند عبارت جستجو، تعداد نتایج، زبان و غیره.
  • پارامترهای پرس و جو استاندارد - جنبه های فنی درخواست شما را تعریف می کند، مانند کلید API.

همه مقادیر پارامتر باید URL کدگذاری شوند.

پارامترهای پرس و جو مخصوص API

پارامترهای درخواستی که به طور خاص برای جستجوی سفارشی JSON API اعمال می‌شوند و درخواست جستجوی شما را تعریف می‌کنند در مرجع خلاصه می‌شوند.

پارامترهای پرس و جو استاندارد

پارامترهای پرس و جو که برای همه عملیات جستجوی سفارشی JSON API اعمال می‌شوند در پارامترهای سیستم ثبت می‌شوند.

داده های پاسخ

اگر درخواست با موفقیت انجام شود، سرور با یک کد وضعیت HTTP 200 OK و داده‌های پاسخ در قالب JSON پاسخ می‌دهد. می توانید ساختار داده پاسخ را در مرجع جستجو کنید.

داده پاسخ یک شی JSON است که شامل سه نوع ویژگی است:

  • فراداده ای که جستجوی درخواستی را توصیف می کند (و احتمالاً درخواست های جستجوی مرتبط)
  • ابرداده که موتور جستجوی قابل برنامه ریزی را توصیف می کند
  • نتایج جستجو

برای توضیح دقیق هر ملک، به مرجع مراجعه کنید.

جستجوی فراداده درخواست

فراداده جستجو شامل:

  • ویژگی url ، که دارای اطلاعاتی درباره الگوی OpenSearch است که برای نتایج بازگردانده شده در این درخواست استفاده شده است.
  • ویژگی queries ، که آرایه ای از اشیاء است که ویژگی های جستجوهای ممکن را توصیف می کند. نام هر شیء در آرایه یا نام یک نقش جستجوی OpenSearch یا یکی از دو نقش سفارشی تعریف شده توسط این API است: previousPage و nextPage . اشیاء نقش احتمالی پرس و جو عبارتند از:
    • request : فراداده ای که پرس و جو را برای مجموعه نتایج فعلی توصیف می کند.
      • این نقش همیشه در پاسخ وجود دارد.
      • همیشه یک آرایه با تنها یک عنصر است.
      • nextPage : فراداده ای که پرس و جو را برای استفاده در صفحه بعدی نتایج توصیف می کند.
        • اگر نتایج فعلی آخرین صفحه باشد، این نقش وجود ندارد. توجه: این API فقط به 100 نتیجه اول برمی گردد.
        • در صورت وجود، همیشه یک آرایه با تنها یک عنصر است.
    • previousPage : فراداده ای که پرس و جو را برای استفاده در صفحه قبلی نتایج توصیف می کند.
      • اگر نتایج فعلی صفحه اول باشد، وجود ندارد.
      • در صورت وجود، همیشه یک آرایه با تنها یک عنصر است.

ابرداده موتور جستجو

ویژگی context دارای ابرداده است که موتور جستجویی را که عبارت جستجو را انجام داده است، توصیف می کند. این شامل نام موتور جستجو، و هر شیء جنبه ای است که برای اصلاح جستجو فراهم می کند.

نتایج جستجو

آرایه items حاوی نتایج جستجوی واقعی است. نتایج جستجو شامل URL، عنوان و تکه‌های متنی است که نتیجه را توصیف می‌کند. علاوه بر این، در صورت وجود، می‌توانند حاوی اطلاعات قطعه غنی باشند.

اگر نتایج جستجو شامل یک ویژگی promotions باشد، شامل مجموعه ای از تبلیغات است.

REST از جاوا اسکریپت

می‌توانید با استفاده از REST از جاوا اسکریپت، با استفاده از پارامتر پرس و جو callback و یک تابع پاسخ به تماس، API JSON جستجوی سفارشی را فراخوانی کنید. این به شما امکان می دهد برنامه های کاربردی غنی بنویسید که داده های موتور جستجوی قابل برنامه ریزی را بدون نوشتن کد سمت سرور نمایش می دهند.

مثال زیر از این روش برای نمایش صفحه اول نتایج جستجو برای ماشین های جستجو استفاده می کند:

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