이 페이지는 Cloud Translation API를 통해 번역되었습니다.

REST를 사용하여 API 호출

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

요청 만들기

Custom Search JSON API의 REST(Representational State Transfer)는 기존 REST와 다소 다릅니다. 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를 호출할 수 있습니다. 이를 통해 서버 측 코드를 작성하지 않고도 프로그래밍 검색 엔진 데이터를 표시하는 다양한 애플리케이션을 작성할 수 있습니다.

다음 예에서는 이 방법을 사용하여 cars라는 검색어에 대한 검색결과의 첫 번째 페이지를 표시합니다.

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