Wywoływanie interfejsu API za pomocą protokołu REST

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).
  • 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=lectures

Parametry 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: previousPage i nextPage. 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>