Ten dokument opisuje, jak korzystać z interfejsu Custom Search JSON API.
Przesyłanie prośby
REST, Representational State Transfer, w interfejsie Custom Search JSON API różni się nieco od tradycyjnego typu REST. Interfejs API nie zapewnia dostępu do zasobów, tylko zapewnia dostęp do usługi. W rezultacie interfejs API udostępnia pojedynczy identyfikator URI, który działa jako punkt końcowy usługi.
Wyniki dla konkretnego wyszukiwania można pobrać, wysyłając żądanie HTTP GET
do jej identyfikatora URI. Przekazujesz szczegóły żądania wyszukiwania jako
parametrów zapytania. Identyfikator URI API JSON Twojej wyszukiwarki ma format:
https://www.googleapis.com/customsearch/v1?[parameters]
Każde żądanie wyszukiwania wymaga trzech zapytań [parameters]:
- Klucz interfejsu API – użyj parametru zapytania
key, aby zidentyfikować aplikację. Identyfikator wyszukiwarki niestandardowej – użyj
cx, aby określić parametr Wyszukiwarka niestandardowa, której chcesz użyć do przeprowadzenia tego wyszukiwania. Wyszukiwarka należy utworzyć w panelu sterowania Uwaga: identyfikator wyszukiwarki (cx) może mieć inny format (np. 8ac1ab64606d234f1)Wyszukiwane hasło – aby określić wyszukiwane hasło, użyj parametru zapytania
q.
Pozostałe parametry zapytania są opcjonalne.
Oto przykład żądania, które przeszukuje do testowania Wyszukiwarki niestandardowej podczas wykładów:
GET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lecturesParametry zapytania
Istnieją 2 typy parametrów, które można przekazać w żądaniu:
- parametry specyficzne dla interfejsu API – zdefiniuj właściwości wyszukiwania, takie jak wyszukiwane hasło, liczba wyników, język itd.
- Standardowe parametry zapytania – określ techniczne aspekty żądania, takie jak klucz interfejsu API.
Wszystkie wartości parametrów muszą być zakodowane na potrzeby adresu URL.
Parametry zapytania specyficzne dla interfejsu API
Parametry żądania, które mają zastosowanie wprost do interfejsu Custom Search JSON API, i zdefiniuj żądania wyszukiwania są podsumowane w dokumentu referencyjnego.
Standardowe parametry zapytania
Parametry zapytania, które mają zastosowanie do wszystkich operacji w interfejsie API JSON Twojej wyszukiwarki, są wymienione w dokumentacji Parametry systemowe.
Dane odpowiedzi
Jeśli żądanie zostanie zrealizowane, serwer zwróci kod stanu HTTP 200 OK.
oraz dane odpowiedzi w formacie JSON. Dane odpowiedzi możesz wyszukiwać
strukturę w odwołaniu.
Dane odpowiedzi to obiekt JSON zawierający 3 typy właściwości:
- Metadane opisujące żądane wyszukiwanie (i ewentualnie powiązane żądania wyszukiwania)
- Metadane opisujące Wyszukiwarkę niestandardową
- Wyniki wyszukiwania
Szczegółowy opis każdej właściwości znajdziesz w dokumentu referencyjnego.
Metadane żądania wyszukiwania
Metadane wyszukiwania obejmują:
url, która zawiera informacje o szablonie OpenSearch. używane w przypadku wyników zwróconych w tym żądaniu.- Właściwość
queries, która jest tablicą wartości opisujących cechy możliwych wyszukiwań. Nazwy poszczególnych elementów obiekt w tablicy jest nazwą elementu Rola OpenSearch – zapytanie lub jedną z 2 ról niestandardowych zdefiniowanych przez ten interfejs API:previousPageinextPage. Możliwe obiekty roli zapytania uwzględnij:request: metadane opisujące zapytanie dotyczące bieżącego zbioru danych wyników.- Ta rola jest zawsze widoczna w odpowiedzi.
- Jest to zawsze tablica z jednym elementem.
nextPage: metadane opisujące zapytanie, które ma zostać użyte w następnym kroku. z wynikami.- Ta rola jest niedostępna, jeśli bieżące wyniki to ostatnia strona. Uwaga: ten interfejs API zwraca tylko pierwsze 100 wyników.
- Jeśli istnieje, zawsze jest to tablica z tylko jednym elementem.
previousPage: metadane opisujące zapytanie, które ma zostać użyte w atrybucie poprzednia strona wyników.- Nie występuje, jeśli bieżące wyniki dotyczą pierwszej strony.
- Jeśli istnieje, zawsze jest to tablica z tylko jednym elementem.
Metadane wyszukiwarki
Właściwość context zawiera metadane opisujące wyszukiwarkę
w którym wykonano zapytanie. Zawiera nazwę wyszukiwarki oraz
wszystkie udostępnione obiekty aspektów,
zawężenie wyszukiwania.
Wyniki wyszukiwania
Tablica items zawiera rzeczywiste wyniki wyszukiwania. Wyszukiwanie
obejmują adres URL, tytuł i fragmenty tekstu opisujące wynik. W
mogą też zawierać fragment rozszerzony.
informacje (w stosownych przypadkach).
Jeśli wyniki wyszukiwania zawierają właściwość promotions, będzie ona zawierać
zestaw promocji.
REST z JavaScriptu
Interfejs Custom Search JSON API możesz wywołać za pomocą REST z języka JavaScript za pomocą metody
parametru zapytania callback i funkcji wywołania zwrotnego. Dzięki temu możesz:
do pisania zaawansowanych aplikacji wyświetlających dane Wyszukiwarki niestandardowej bez zapisywania
kod po stronie serwera.
W przykładzie poniżej użyto tej metody do wyświetlenia pierwszej strony wyszukiwania wyniki dla zapytania samochody:
<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>