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