Wywoływanie interfejsu API za pomocą REST

Ten dokument opisuje, jak korzystać z interfejsu Custom Search JSON API.

Przesyłanie prośby

REST, czyli Representational State Transfer, w interfejsie Custom Search JSON API różni się nieco od tradycyjnego 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.

Aby pobrać wyniki dla określonego wyszukiwania, wyślij żądanie HTTP GET do jego identyfikatora URI. Szczegóły żądania przekazujesz w postaci parametrów zapytania. Format identyfikatora URI interfejsu Custom Search JSON API:

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

W przypadku każdego żądania wyszukiwania wymagane są 3 zapytania [parameters]:

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

  • Identyfikator wyszukiwarki niestandardowej – w polu cx określ wyszukiwarkę niestandardową Google, której chcesz używać do 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ć wyrażenie wyszukiwania, użyj parametru zapytania q.

Pozostałe parametry zapytania są opcjonalne.

Oto przykład żądania, które przeszuka wykłady w 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 specyficzne dla interfejsu API – określ właściwości wyszukiwania, takie jak wyrażenie wyszukiwania, liczba wyników, język itp.
  • Standardowe parametry zapytania – określ aspekty techniczne żądania, np. klucz interfejsu API.

Wszystkie wartości parametrów muszą być zakodowane na potrzeby adresu URL.

Parametry zapytania specyficzne dla interfejsu API

Podsumowanie parametrów żądań, które mają zastosowanie do interfejsu Custom Search JSON API i definiują żądanie wyszukiwania, znajdziesz w dokumentacji.

Standardowe parametry zapytania

Parametry zapytania, które mają zastosowanie do wszystkich operacji interfejsu API Custom Search JSON, znajdziesz w sekcji Parametry systemu.

Dane odpowiedzi

Jeśli żądanie się powiedzie, serwer odpowie, używając kodu stanu HTTP 200 OK, a danych odpowiedzi w formacie JSON. Struktura 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 żądania wyszukiwania)
  • Metadane opisujące Wyszukiwarka niestandardowa
  • Wyniki wyszukiwania

Szczegółowy opis każdej właściwości znajdziesz w dokumentacji.

Metadane żądania wyszukiwania

Metadane wyszukiwania obejmują:

  • url, która zawiera informacje o szablonie OpenSearch używanym na potrzeby wyników zwracanych w tym żądaniu.
  • queries, która jest tablicą obiektów opisujących cechy możliwych wyszukiwań. Nazwa każdego obiektu w tablicy to nazwa roli w zapytaniu OpenSearch lub jednej z 2 ról niestandardowych zdefiniowanych przez ten interfejs API: previousPage i nextPage. Możliwe obiekty roli zapytania to między innymi:
    • request: metadane opisujące zapytanie dotyczące bieżącego zestawu wyników.
      • Ta rola jest zawsze obecna w odpowiedzi.
      • Jest to zawsze tablica z tylko jednym elementem.
      • nextPage: metadane opisujące zapytanie, które zostaną użyte na następnej stronie wyników.
        • Ta rola nie jest dostępna, jeśli bieżące wyniki to ostatnia strona. Uwaga: ten interfejs API zwraca tylko do 100 pierwszych wyników.
        • Jeśli występuje, jest to zawsze tablica z tylko 1 elementem.
    • previousPage: metadane opisujące zapytanie użyte na poprzedniej stronie wyników.
      • Brak, jeśli bieżące wyniki są wyświetlane na pierwszej stronie.
      • Jeśli występuje, jest to zawsze tablica z tylko 1 elementem.

Metadane wyszukiwarki

Właściwość context zawiera metadane opisujące wyszukiwarkę, która wykonała zapytanie. Obejmuje nazwę wyszukiwarki i wszelkie zawarte w niej obiekty aspektu do zawężenia wyszukiwania.

Wyniki wyszukiwania

Tablica items zawiera rzeczywiste wyniki wyszukiwania. Wyniki wyszukiwania zawierają adres URL, tytuł i fragmenty tekstu, które opisują wynik. Dodatkowo mogą one zawierać informacje o fragmentach rozszerzonych (w odpowiednich przypadkach).

Jeśli wyniki wyszukiwania zawierają właściwość promotions, zawiera ona zestaw promocji.

REST z JavaScriptu

Możesz wywołać interfejs API JSON Twojej wyszukiwarki przy użyciu REST z poziomu JavaScriptu, używając parametru zapytania callback i funkcji wywołania zwrotnego. Dzięki temu możesz pisać zaawansowane aplikacje, które wyświetlają dane Wyszukiwarki niestandardowej bez konieczności pisania kodu po stronie serwera.

W poniższym przykładzie pokazano w ten sposób pierwszą stronę wyników wyszukiwania 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>