REST를 사용하여 API 호출

이 문서에서는 Custom Search JSON API를 사용하는 방법을 설명합니다.

요청하기

Custom Search JSON API의 REST 또는 Representational State Transfer는 일반적인 RESTful API와 다소 다릅니다. API는 리소스에 대한 액세스 권한을 제공하는 대신 서비스에 대한 액세스 권한을 제공합니다. 따라서 API는 서비스 엔드포인트 역할을 하는 단일 URI를 제공합니다.

URI에 HTTP GET 요청을 전송하여 특정 검색의 결과를 검색할 수 있습니다. 검색 요청의 세부정보를 쿼리 매개변수로 전달합니다. Custom Search JSON API URI의 형식은 다음과 같습니다.

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

각 검색 요청에는 세 가지 쿼리 [parameters]가 필요합니다.

  • API 키 - key 쿼리 매개변수를 사용하여 애플리케이션을 식별합니다.

    • 프로그래밍 검색 엔진 ID - cx를 사용하여 이 검색을 실행하는 데 사용할 프로그래밍 검색 엔진을 지정합니다. 검색엔진은 제어판으로 만들어야 합니다.참고: 검색엔진 ID (cx)는 다양한 형식 (예: 8ac1ab64606d234f1)일 수 있습니다.

  • 검색어 - q 쿼리 매개변수를 사용하여 검색 표현식을 지정합니다.

다른 모든 쿼리 매개변수는 선택사항입니다.

다음은 테스트 프로그래밍 검색 엔진에서 강의를 검색하는 요청의 예입니다.

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

쿼리 매개변수

요청에 전달할 수 있는 매개변수에는 두 가지 유형이 있습니다.

  • API별 매개변수 - 검색 표현식, 결과 수, 언어 등 검색의 속성을 정의합니다.
  • 표준 쿼리 매개변수 - API 키와 같은 요청의 기술적 측면을 정의합니다.

모든 매개변수 값은 URL로 인코딩되어야 합니다.

API별 쿼리 매개변수

Custom Search JSON API에만 적용되고 검색 요청을 정의하는 요청 매개변수는 참조에 요약되어 있습니다.

표준 쿼리 매개변수

모든 Custom Search JSON API 작업에 적용되는 쿼리 매개변수는 시스템 매개변수에 설명되어 있습니다.

응답 데이터

요청이 성공하면 서버는 200 OK HTTP 상태 코드와 JSON 형식의 응답 데이터로 응답합니다. 참조에서 응답 데이터 구조를 조회할 수 있습니다.

응답 데이터는 다음 세 가지 유형의 속성을 포함하는 JSON 객체입니다.

  • 요청된 검색어 (및 관련 검색어 요청)를 설명하는 메타데이터
  • 프로그래밍 검색 엔진을 설명하는 메타데이터
  • 검색 결과

각 속성에 관한 자세한 설명은 참조를 참고하세요.

검색 요청 메타데이터

검색 메타데이터에는 다음이 포함됩니다.

  • url 속성: 이 요청에서 반환된 결과에 사용된 OpenSearch 템플릿에 관한 정보가 포함되어 있습니다.
  • queries 속성: 가능한 검색의 특성을 설명하는 객체 배열입니다. 배열의 각 객체 이름은 OpenSearch 쿼리 역할의 이름이거나 이 API에 의해 정의된 두 가지 맞춤 역할(previousPage 및 nextPage) 중 하나입니다. 가능한 쿼리 역할 객체는 다음과 같습니다.
    • request: 현재 결과 집합의 쿼리를 설명하는 메타데이터입니다.
    • 이 역할은 응답에 항상 표시됩니다.
      • 항상 요소가 하나만 있는 배열입니다.
      • nextPage: 결과의 다음 페이지에 사용할 쿼리를 설명하는 메타데이터입니다.
        • 현재 결과가 마지막 페이지인 경우 이 역할은 표시되지 않습니다. 참고: 이 API는 최대 100개의 결과만 반환합니다.
        • 이 속성이 있는 경우 항상 요소가 하나만 있는 배열입니다.
    • previousPage: 이전 결과 페이지에 사용할 쿼리를 설명하는 메타데이터입니다.
      • 현재 결과가 첫 번째 페이지인 경우 표시되지 않습니다.
      • 이 속성이 있는 경우 항상 요소가 하나만 있는 배열입니다.

검색엔진 메타데이터

context 속성에는 검색 쿼리를 실행한 검색엔진을 설명하는 메타데이터가 있습니다. 여기에는 검색엔진의 이름과 검색을 세분화하기 위해 제공하는 모든 측면 객체가 포함됩니다.

검색 결과

items 배열에는 실제 검색 결과가 포함됩니다. 검색 결과에는 결과를 설명하는 URL, 제목, 텍스트 스니펫이 포함됩니다. 또한 해당하는 경우 리치 스니펫 정보를 포함할 수 있습니다.

검색 결과에 promotions 속성이 포함된 경우 프로모션 집합이 포함됩니다.

JavaScript의 REST

callback 쿼리 매개변수와 콜백 함수를 사용하여 JavaScript에서 REST를 사용하여 Custom Search JSON API를 호출할 수 있습니다. 이를 통해 서버 측 코드를 작성하지 않고도 프로그래밍 검색 엔진 데이터를 표시하는 풍부한 애플리케이션을 작성할 수 있습니다.

다음 예에서는 이 접근 방식을 사용하여 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>