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

W tym dokumencie opisujemy, jak używać interfejsu Custom Search JSON API.

Poproś

Interfejs REST (Representational State Transfer) w interfejsie Custom Search JSON API różni się nieco od zwykłych interfejsów 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 określonego wyszukiwania możesz pobrać, wysyłając żądanie HTTP GET do jego identyfikatora URI. Szczegóły żądania wyszukiwania przekazujesz jako parametry zapytania. Format identyfikatora URI interfejsu Custom Search JSON API:

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

Każde żądanie wyszukiwania musi zawierać 3 zapytania [parameters]:

  • Klucz interfejsu API – użyj parametru zapytania key, aby zidentyfikować swoją aplikację.

    • Identyfikator wyszukiwarki niestandardowej – użyj pola cx, aby określić wyszukiwarkę niestandardową, której chcesz użyć do przeprowadzenia tego wyszukiwania. Wyszukiwarkę należy utworzyć w panelu sterowania. Uwaga: identyfikator wyszukiwarki (cx) może mieć inny format (np. 8ac1ab64606d234f1).

  • Zapytanie wyszukiwania – użyj parametru zapytania q, aby określić wyrażenie wyszukiwania.

Pozostałe parametry zapytania są opcjonalne.

Oto przykład zapytania, które wyszukiwało w testowej Wyszukiwarce niestandardowej informacje o wykładach:

GET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lectures

Parametry zapytania

W żądaniu możesz podać 2 rodzaje parametrów:

  • Parametry specyficzne dla 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, np. 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ą wyłącznie interfejsu Custom Search JSON API i określają żądanie wyszukiwania, są opisane 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 zakończy się powodzeniem, serwer odpowie kodem stanu HTTP 200 OK oraz danymi odpowiedzi w formacie JSON. Strukturę danych odpowiedzi możesz sprawdzić w dokumentacji.

Dane odpowiedzi to obiekt JSON zawierający 3 typy właściwości:

  • Metadane opisujące żądane wyszukiwanie (i ewentualnie powiązane z nim żądania wyszukiwania)
  • Metadane opisujące Wyszukiwarkę niestandardową
  • Wyniki wyszukiwania

Szczegółowe opisy poszczególnych właściwości znajdziesz w materiałach referencyjnych.

Metadane żądania wyszukiwania

Metadane wyszukiwania obejmują:

  • W usłudze url znajdziesz informacje o szablonie OpenSearch używanym do wyników zwróconych w ramach tego żądania.
  • Właściwość queries to tablica obiektów opisujących cechy możliwych wyszukiwań. Nazwa każdego obiektu w tablicy to albo nazwa roli zapytania OpenSearch, albo jedna z 2 ról niestandardowych zdefiniowanych przez ten interfejs API: previousPage i nextPage. Możliwe obiekty ról zapytań:
    • request: metadane opisujące zapytanie dotyczące bieżącego zbioru wyników.
    • Ta rola jest zawsze obecna w odpowiedzi.
      • Jest to zawsze tablica z jednym elementem.
      • nextPage: metadane opisujące zapytanie, którego należy użyć 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 pierwsze 100 wyników.
        • Jeśli jest obecny, to zawsze jest to tablica z jednym elementem.
    • previousPage: metadane opisujące zapytanie do użycia na poprzedniej stronie wyników.
      • Nie występuje, jeśli bieżące wyniki znajdują się na pierwszej stronie.
      • Jeśli jest obecny, to zawsze jest to tablica z jednym elementem.

Metadane wyszukiwarki

Usługa context zawiera metadane opisujące wyszukiwarkę, która wykonała zapytanie. Dotyczy to nazwy wyszukiwarki i wszystkich obiektów, które udostępnia na potrzeby zawężenia wyszukiwania.

Wyniki wyszukiwania

Tablica items zawiera rzeczywiste wyniki wyszukiwania. Wyniki wyszukiwania obejmują adres URL, tytuł i krótkie opisy, które opisują wynik. Dodatkowo mogą one zawierać informacje o fragmentach rozszerzonych (jeśli to konieczne).

Jeśli wyniki wyszukiwania obejmują usługę promotions, zawiera ona zestaw promocji.

REST z JavaScript

Interfejs Custom Search JSON API możesz wywoływać za pomocą protokołu REST z JavaScriptu, używając parametru zapytania callback i funkcji wywołania zwrotnego. Dzięki temu możesz tworzyć rozbudowane aplikacje wyświetlające dane z wyszukiwarki Programmable Search Engine bez konieczności pisania kodu po stronie serwera.

W tym przykładzie zastosowano to podejście, aby wyświetlić pierwszą stronę wyników wyszukiwania dla zapytania lecture (wykład):

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