W tym dokumencie opisujemy, jak używać interfejsu Custom Search JSON API.
Poproś
REST, czyli Representational State Transfer, w interfejsie Custom Search JSON API różni się nieco od zwykłych interfejsów API typu REST. Zamiast zapewniać dostęp do zasobów, interfejs API zapewnia dostęp do usługi. W efekcie interfejs API udostępnia pojedynczy identyfikator URI, który działa jako punkt końcowy usługi.
Wyniki konkretnego wyszukiwania możesz pobrać, wysyłając żądanie HTTP GET na jego identyfikator URI. Szczegóły żądania wyszukiwania przekazujesz jako parametry zapytania. Format identyfikatora URI interfejsu Custom Search JSON API to:
https://www.googleapis.com/customsearch/v1?[parameters]
Z każdym żądaniem wyszukiwania wymagane są 3 parametry zapytania [parameters]:
Klucz interfejsu API – użyj parametru zapytania
key, aby zidentyfikować swoją aplikację.- Identyfikator wyszukiwarki niestandardowej – użyj
cx, aby określić wyszukiwarkę niestandardową, której chcesz użyć do przeprowadzenia wyszukiwania. Wyszukiwarkę należy utworzyć w Panelu sterowania. Uwaga: identyfikator wyszukiwarki (cx) może mieć inny format (np. 8ac1ab64606d234f1).
- Identyfikator wyszukiwarki niestandardowej – użyj
Zapytanie – użyj parametru zapytania
q, aby określić wyrażenie wyszukiwania.
Wszystkie pozostałe parametry zapytania są opcjonalne.
Oto przykład żądania, które wyszukuje wykłady w testowej Wyszukiwarce niestandardowej:
GET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lecturesParametry zapytania
W żądaniu możesz przekazywać 2 rodzaje parametrów:
- Parametry interfejsu API – definiują właściwości wyszukiwania, takie jak wyrażenie wyszukiwania, liczba wyników, język itp.
- Standardowe parametry zapytania – określają techniczne aspekty żądania, takie jak klucz interfejsu API.
Wszystkie wartości parametrów muszą być zakodowane na potrzeby adresu URL.
Parametry zapytania dotyczące interfejsu API
Parametry żądania, które dotyczą interfejsu Custom Search JSON API i definiują żądanie wyszukiwania, są podsumowane w dokumentacji.
Standardowe parametry zapytania
Parametry zapytania, które mają zastosowanie do wszystkich operacji interfejsu Custom Search JSON API, są opisane w sekcji Parametry systemowe.
Dane odpowiedzi
Jeśli żądanie się powiedzie, serwer odpowie kodem stanu HTTP 200 OK i danymi odpowiedzi w formacie JSON. Strukturę danych odpowiedzi możesz sprawdzić w dokumentacji.
Dane odpowiedzi to obiekt JSON, który zawiera 3 typy właściwości:
- Metadane opisujące żądane wyszukiwanie (i ewentualnie powiązane wyszukiwania)
- Metadane opisujące wyszukiwarkę niestandardową.
- Wyniki wyszukiwania
Szczegółowy opis każdej właściwości znajdziesz w dokumentacji.
Metadane żądania wyszukiwania
Metadane wyszukiwania obejmują:
- Właściwość
url, która zawiera informacje o szablonie OpenSearch używanym do zwracania wyników w tym żądaniu. queries, która jest tablicą obiektów opisujących cechy możliwych wyszukiwań. Nazwa każdego obiektu w tablicy jest nazwą roli zapytania OpenSearch lub jednej z 2 ról niestandardowych zdefiniowanych przez ten interfejs API:previousPageinextPage. Możliwe obiekty roli zapytania:request: metadane opisujące zapytanie dotyczące bieżącego zestawu wyników.- Ta rola jest zawsze obecna w odpowiedzi.
- Zawsze jest to tablica z jednym elementem.
nextPage: metadane opisujące zapytanie, które ma zostać użyte na następnej stronie wyników.- Ta rola nie jest obecna, jeśli bieżące wyniki są ostatnią stroną. Uwaga: ten interfejs API zwraca tylko pierwszych 100 wyników.
- Jeśli jest obecny, zawsze jest tablicą z jednym elementem.
previousPage: metadane opisujące zapytanie, które ma zostać użyte na poprzedniej stronie wyników.- Nie występuje, jeśli bieżące wyniki są pierwszą stroną.
- Jeśli jest obecny, zawsze jest tablicą z jednym elementem.
Metadane wyszukiwarki
Właściwość context zawiera metadane opisujące wyszukiwarkę, która wykonała zapytanie. Zawiera nazwę wyszukiwarki i wszystkie obiekty aspektów, które udostępnia, aby zawęzić wyszukiwanie.
Wyniki wyszukiwania
Tablica items zawiera rzeczywiste wyniki wyszukiwania. Wyniki wyszukiwania zawierają adres URL, tytuł i krótkie opisy tekstowe. Mogą też zawierać informacje o fragmentach rozszerzonych, jeśli są one dostępne.
Jeśli wyniki wyszukiwania zawierają właściwość promotions, zawiera ona zestaw promocji.
REST z JavaScriptu
Interfejs Custom Search JSON API możesz wywołać za pomocą REST z JavaScriptu, używając parametru zapytania callback i funkcji wywołania zwrotnego. Dzięki temu możesz tworzyć rozbudowane aplikacje, które wyświetlają dane z Wyszukiwarki niestandardowej, bez konieczności pisania kodu po stronie serwera.
W tym przykładzie użyto tego podejścia do wyświetlenia pierwszej strony wyników wyszukiwania dla zapytania lecture:
<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>