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

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

İstekte bulunma

Custom Search JSON API'deki REST veya Representational State Transfer (Temsili Durum Aktarımı) işlevi geleneksel REST'den 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ı, sorgunun URI'sına HTTP GET isteği göndererek alabilirsiniz. Arama isteğinin ayrıntılarını sorgu parametreleri olarak aktarırsınız. Custom Search JSON API URI'sının biçimi şu şekildedir:

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

Her arama isteğinde üç adet [parameters] sorgusu gereklidir:

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

• Programlanabilir Arama Motoru Kimliği - Bu aramayı gerçekleştirmek istediğiniz Programlanabilir Arama Motoru'nu belirtmek için cx kullanın. Arama motoru, Denetim Masası ile oluşturulmalıdır Not: Arama Motoru Kimliği (cx) farklı biçimde (ör. 8ac1ab64606d234f1) olabilir

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

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

Test Programlanabilir Arama Motoru'nda dersler için arama yapan bir istek örneğini burada görebilirsiniz:

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 - arama ifadesi, sonuç sayısı, dil gibi aramanızın özelliklerini tanımlayın.
• Standart sorgu parametreleri - İsteğinizin API anahtarı gibi teknik yönlerini tanımlayın.

Tüm parametre değerlerinin URL olarak kodlanmış olması gerekir.

API'ye özel sorgu parametreleri

Özellikle Custom Search JSON API için geçerli olan ve arama isteğinizi tanımlayan istek parametreleri referansta ö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çiminde yanıt verileriyle yanıt verir. Yanıt veri yapısını referansta bulabilirsiniz.

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

• İ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 referansa göz atın.

Arama isteği meta verileri

Arama meta verileri şunları içerir:

• url özelliği bulunur.
• queries özelliğini kullanabilirsiniz. Bu, olası aramaların özelliklerini açıklayan bir nesne dizisidir. Dizideki her bir nesnenin adı, bir OpenSearch sorgu rolünün veya bu API tarafından tanımlanan şu iki özel rolden birinin adıdır: previousPage ve nextPage. Olası sorgu rolü nesneleri şunlardır:
  • request: Geçerli sonuç kümesine ilişkin sorguyu açıklayan meta veriler.
    • Bu rol yanıtta her zaman mevcuttur.
    • Her zaman tek bir öğesi olan bir dizidir.
    • nextPage: Bir 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 tek bir öğesi olan bir dizidir.
  • previousPage: Önceki sonuç sayfası için kullanılacak sorguyu açıklayan meta veri.
    • Mevcut sonuçlar ilk sayfaysa mevcut değildir.
    • Mevcut olduğunda her zaman yalnızca tek bir öğesi olan bir dizidir.

Arama motoru meta verileri

context özelliği, arama sorgusunu gerçekleştiren arama motorunu açıklayan meta verilere sahiptir. Arama motorunun adını ve aramayı hassaslaştırmak için sağladığı özellik nesnelerini içerir.

Arama sonuçları

items dizisi gerçek arama sonuçlarını içerir. Arama sonuçları, sonucu açıklayan URL'yi, başlığı ve metin snippet'lerini içerir. Ayrıca, varsa zengin snippet bilgilerini içerebilir.

Arama sonuçları bir promotions özelliği içeriyorsa bu özellik bir promosyon grubu içerir.

JavaScript'ten REST

Custom Search JSON API'yi, callback sorgu parametresi ve bir geri çağırma işlevi ile JavaScript'teki REST'i kullanarak çağırabilirsiniz. Bu sayede, herhangi bir sunucu tarafı kodu yazmadan Programlanabilir Arama Motoru verilerini görüntüleyen zengin uygulamalar yazabilirsiniz.

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

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