API'yi Çağırmak için REST'i Kullanma

Bu dokümanda, Custom Search JSON API'nin nasıl kullanılacağı açıklanmaktadır.

İstekte bulunma

REST veya Representational State Transfer (Temsili Durum Aktarımı) özellikleri, geleneksel REST'ten biraz farklıdır. API, kaynaklara erişim sağlamak yerine bir hizmete erişim sağlar. Sonuç olarak API, hizmet uç noktası görevi gören tek bir URI sağlar.

Belirli bir aramanın sonuçlarını HTTP GET göndererek alabilirsiniz isteğini yerine getirir. Arama isteğinin ayrıntılarını sorgu parametreleridir. Custom Search JSON API URI'sinin biçimi şu şekildedir:

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

Her arama isteğinde üç sorgu [parameters] gerekir:

  • API anahtarı - Aşağıdaki işlemler için key sorgu parametresini kullanın: uygulamanızı tanımlayın.

  • Programlanabilir Arama Motoru Kimliği - cx Bu aramayı yapmak için kullanmak istediğiniz Programlanabilir Arama Motoru. Arama motoru, Denetim Masası ile oluşturulmalıdır Not: Arama Motoru Kimliği (cx) farklı biçimde olabilir (ör. 8ac1ab64606d234f1)

  • Arama sorgusu: Arama ifadenizi belirtmek için q sorgu parametresini kullanın.

Diğer tüm sorgu parametreleri isteğe bağlıdır.

Burada, Dersler için Programlanabilir Arama Motoru'nu test edin:

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

Sorgu parametreleri

İsteğinizde iletebileceğiniz iki tür parametre vardır:

  • API'ye özel parametreler: Aramanızın özelliklerini tanımlayın, örneğin arama ifadesini, sonuç sayısını, dil vb.
  • Standart sorgu parametreleri; isteğinizin teknik özelliklerini tanımlayın; örneğin, API anahtarı.

Tüm parametre değerlerinin URL kodlamalı olması gerekir.

API'ye özel sorgu parametreleri

Özellikle Custom Search JSON API için geçerli olan ve arama istekleri, referans:

Standart sorgu parametreleri

Tüm Custom Search JSON API işlemleri için geçerli olan sorgu parametreleri, Sistem Parametreleri.

Yanıt verileri

İstek başarılı olursa sunucu 200 OK HTTP durum koduyla yanıt verir. ve yanıt verileri JSON biçimindedir. Buradan gösterilen yanıtlarla ilgili verileri referansta yer alan bir yapıya sahip olmalıdır.

Yanıt verileri, üç tür dosya içeren bir JSON nesnesidir özellikler:

  • İstenen aramayı (ve muhtemelen ilgili arama isteklerini) açıklayan meta veriler
  • Programlanabilir Arama Motoru'nu açıklayan meta veriler
  • Arama sonuçları

Her özelliğin ayrıntılı açıklaması için referans:

Arama isteği meta verileri

Arama meta verileri şunları içerir:

  • Aşağıdaki özelliklere sahip url mülkü: OpenSearch şablonu hakkında bilgi bu istekte döndürülen sonuçlar için kullanılır.
  • queries özelliği, olası aramaların özelliklerini açıklayan nesneler. Her birinin adı dizedeki nesne bir OpenSearch sorgu rolü veya bu API tarafından tanımlanan iki özel rolden birini seçin: previousPage ve nextPage. Olası sorgu rolü nesneleri şunlardır:
    • request: Geçerli grup için sorguyu açıklayan meta veri sonuç.
      • Bu rol her zaman yanıtta mevcuttur.
      • Her zaman yalnızca bir öğe içeren bir dizidir.
      • nextPage: Sonraki sorgu için kullanılacak sorguyu açıklayan meta veriler sonuç sayfası.
        • Mevcut sonuçlar son sayfaysa bu rol mevcut değildir. Not: Bu API yalnızca ilk 100 sonucu döndürür.
        • Mevcut olduğunda, her zaman yalnızca bir öğeli bir dizidir.
    • previousPage: sonuç sayfası.
      • Geçerli sonuçlar ilk sayfaysa mevcut değildir.
      • Mevcut olduğunda, her zaman yalnızca bir öğeli bir dizidir.

Arama motoru meta verileri

context özelliği, arama motorunu açıklayan meta veriler içeriyor arama sorgusunu gerçekleştiren kişidir. Arama motorunun adını ve sağladığı özellik nesneleri aramanızın kapsamını daraltmaya yardımcı oluyor.

Arama sonuçları

items dizisi gerçek arama sonuçlarını içerir. Arama sonuçlar, sonucu açıklayan URL, başlık ve metin snippet'lerini içerir. İçinde Ayrıca, zengin snippet bilgileri (varsa) gönderin.

Arama sonuçları bir promotions özelliği içeriyorsa bir dizi promosyon içerir.

JavaScript'ten REST

JavaScript'ten REST kullanarak Custom Search JSON API'yi çağırmak için callback sorgu parametresi ve geri çağırma işlevi. Bu sayede kod yazmadan Programlanabilir Arama Motoru verilerini görüntüleyen zengin uygulamalar yazmak için kullanılır. ekleyebilirsiniz.

Aşağıdaki örnekte, aramanın ilk sayfasını görüntülemek için bu yaklaşım kullanılmaktadır. arabalar sorgusunun sonuçları:

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