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 쿼리 매개변수를 사용하여 검색 표현식을 지정합니다.

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

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

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>