API'yi çağırmak için REST'i kullanma

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

İstekte bulunun

Custom Search JSON API'deki REST veya Representational State Transfer (Temsili Durum Aktarımı), normal RESTful API'lerden biraz farklıdır. API, kaynaklara erişim sağlamak yerine bir hizmete erişim sağlar. Sonuç olarak API, hizmet uç noktası olarak işlev gören tek bir URI sağlar.

URI'sine HTTP isteği göndererek belirli bir aramanın sonuçlarını alabilirsiniz.GET Arama isteğinin ayrıntılarını sorgu parametreleri olarak iletirsiniz. Custom Search JSON API URI'sinin biçimi şudur:

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

Her arama isteği için üç sorgu [parameters] gereklidir:

• API anahtarı: Uygulamanızı tanımlamak için key sorgu parametresini kullanın.

  • Programlanabilir Arama Motoru Kimliği: Bu aramayı gerçekleştirmek için kullanmak istediğiniz Programlanabilir Arama Motoru'nu belirtmek üzere cx öğesini kullanın. Arama motoru Denetleme Masası ile oluşturulmalıdır. Not: Arama Motoru Kimliği (cx), farklı bir 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.

Aşağıda, test amaçlı bir Programlanabilir Arama Motoru'nda dersler için arama yapan bir istek örneği verilmiştir:

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

Sorgu parametreleri

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

• API'ye özgü parametreler: Arama ifadesi, sonuç sayısı, dil vb. gibi aramanızın özelliklerini tanımlar.
• Standart sorgu parametreleri: İsteğinizin teknik yönlerini (ör. API anahtarı) tanımlar.

Tüm parametre değerlerinin URL olarak kodlanması gerekir.

API'ye özel sorgu parametreleri

Özellikle Custom Search JSON API için geçerli olan ve arama isteğinizi tanımlayan istek parametreleri referans bölümünde özetlenmiştir.

Standart sorgu parametreleri

Tüm Custom Search JSON API işlemleri için geçerli olan sorgu parametreleri Sistem Parametreleri bölümünde açıklanmıştır.

Yanıt verileri

İstek başarılı olursa sunucu, 200 OK HTTP durum kodu ve JSON biçimindeki yanıt verileriyle yanıt verir. Yanıt veri yapısını referans bölümünde bulabilirsiniz.

Yanıt verileri, üç tür özellik içeren bir JSON nesnesi şeklindedir:

• İ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 bölümüne bakın.

Arama isteği meta verileri

Arama meta verileri şunları içerir:

• url mülkünde bulunur. Bu mülk, bu istekte döndürülen sonuçlar için kullanılan OpenSearch şablonu hakkında bilgi içerir.
• Olası aramaların özelliklerini açıklayan bir nesne dizisi olan queries mülkü. Dizideki her nesnenin adı, bir OpenSearch sorgusu rolünün adı veya bu API tarafından tanımlanan iki özel rolden biri (previousPage ve nextPage) olur. Olası sorgu rolü nesneleri şunlardır:
  • request: Geçerli sonuç kümesi için sorguyu açıklayan meta veriler.
  • Bu rol yanıtta her zaman mevcuttur.
    • Her zaman yalnızca bir öğe içeren bir dizidir.
    • nextPage: Sonraki sonuç sayfasında kullanılacak sorguyu açıklayan meta veri.
      • 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 öğe içeren bir dizidir.
  • previousPage: Sonuçların önceki sayfası için kullanılacak sorguyu açıklayan meta veriler.
    • Geçerli sonuçlar ilk sayfaysa mevcut değildir.
    • Mevcut olduğunda her zaman yalnızca bir öğe içeren bir dizidir.

Arama motoru meta verileri

context mülkünde, arama sorgusunu gerçekleştiren arama motorunu açıklayan meta veriler bulunur. Arama motorunun adını ve aramayı hassaslaştırmak için sağladığı tüm yön objelerini içerir.

Arama sonuçları

items dizisi, gerçek arama sonuçlarını içerir. Arama sonuçlarında URL, başlık ve sonucu açıklayan metin snippet'leri yer alır. Ayrıca, geçerliyse zengin snippet bilgileri de içerebilirler.

Arama sonuçlarında promotions mülkü varsa bu mülkte bir dizi promosyon bulunur.

JavaScript'ten REST

callback sorgu parametresini ve bir geri çağırma işlevini kullanarak JavaScript'den REST kullanarak Custom Search JSON API'yi çağırabilirsiniz. Bu sayede, sunucu tarafı kod yazmadan Programlanabilir Arama Motoru verilerini gösteren zengin uygulamalar yazabilirsiniz.

Aşağıdaki örnekte, ders sorgusu için arama sonuçlarının ilk sayfasını görüntülemek amacıyla bu yaklaşım kullanılır:

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