Query API를 사용하여 검색 인터페이스 만들기

Query API는 검색 인터페이스를 빌드하거나 검색결과를 애플리케이션에 삽입하기 위한 방법을 검색하고 제안합니다.

요구사항이 많지 않은 웹 애플리케이션은 검색 위젯을 사용하는 것이 좋습니다. 자세한 내용은 검색 위젯으로 검색 인터페이스 만들기를 참조하세요.

검색 인터페이스 빌드

단순한 검색 인터페이스를 빌드하는 경우에도 다음과 같은 여러 단계가 필요합니다.

  1. 검색 애플리케이션 구성
  2. 애플리케이션용 OAuth 사용자 인증 정보 생성
  3. 색인 쿼리
  4. 쿼리 결과 표시

페이징, 정렬, 필터링, 패싯, 자동 제안과 같은 기능을 사용하여 검색 인터페이스를 더욱 향상시킬 수 있습니다.

검색 애플리케이션 구성

생성한 각 검색 인터페이스와 연결할 검색 애플리케이션을 하나 이상 만들어야 합니다. 검색 애플리케이션은 포함할 데이터 소스, 정렬 순서, 필터, 요청할 패싯과 같은 쿼리의 기본 매개변수를 제공합니다. 필요한 경우 Query API를 사용하여 이러한 매개변수를 재정의할 수 있습니다.

검색 애플리케이션에 대한 자세한 내용은 커스텀 검색 환경 만들기를 참조하세요.

애플리케이션용 OAuth 사용자 인증 정보 생성

Google Cloud Search REST API에 대한 액세스 구성 단계 외에도 웹 애플리케이션용 OAuth 사용자 인증 정보를 생성해야 합니다. 생성하는 사용자 인증 정보의 유형은 API가 사용되는 컨텍스트에 따라 다릅니다.

사용자 대신 승인을 요청하려면 사용자 인증 정보를 사용합니다. 승인을 요청할 때는 범위 https://www.googleapis.com/auth/cloud_search.query를 사용합니다.

OAuth 옵션 및 클라이언트 라이브러리에 대한 추가 정보는 Google Identity Platform을 참조하세요.

색인 쿼리

색인에 대한 검색을 수행하려면 search 메서드를 사용합니다.

모든 요청은 2가지 정보를 포함해야 합니다. 하나는 항목과 일치시킬 텍스트 query이고 다른 하나는 사용할 검색 애플리케이션의 ID를 식별하는 searchApplicationId입니다.

다음 스니펫은 영화 Titanic의 영화 데이터 소스에 대한 쿼리입니다.

{
      "query": "titanic",
      "requestOptions": {
        "searchApplicationId": "searchapplications/<search_app_id>"
      },
    }
    

쿼리 결과 표시

검색 인터페이스에는 최소한 항목 title과 원래 항목에 대한 링크가 표시되어야 합니다. 검색결과에 나타나는 추가 정보(예: 본문 미리보기, 메타데이터)를 활용하여 검색결과 표시를 향상시킬 수 있습니다.

본문 미리보기 강조 표시

색인이 생성된 텍스트 또는 HTML 콘텐츠가 포함된 반환된 항목에 대하여 콘텐츠의 본문 미리보기가 반환됩니다. 이 콘텐츠는 사용자가 반환된 항목의 관련성을 확인하는 데 도움이 됩니다.

검색어가 본문 미리보기에 있으면 검색어의 위치를 나타내는 하나 이상의 일치 범위가 함께 반환됩니다.

결과를 렌더링할 때 일치하는 텍스트를 강조표시하려면 matchRanges를 사용하세요. 다음 자바스크립트 예시는 스니펫을 일치하는 각 범위가 <span> 태그로 묶인 HTML 마크업으로 변환합니다.

function highlightSnippet(snippet) {
      let text = snippet.snippet;
      let formattedText = text;
      if (snippet.matchRanges) {
        let parts = [];
        let index = 0;
        for (let match of snippet.matchRanges) {
          let start = match.start || 0; // Default to 0 if omitted
          let end = match.end;
          if (index < start) { // Include any leading text before/between ranges
            parts.push(text.slice(index, start));
          }
          parts.push('<span class="highlight">');
          parts.push(text.slice(start, end));
          parts.push('</span>');
          index = end;
        }
        parts.push(text.slice(index)); // Include any trailing text after last range
        formattedText = parts.join('');
      }
      return formattedText;
    }
    

다음 스니펫을 사용할 경우

{
      "snippet": "This is an example snippet...",
      "matchRanges": [
        {
          "start": 11,
          "end": 18
        }
      ]
    }
    

결과 HTML 문자열은 다음과 같습니다.

This is an <span class="highlight">example</span> snippet...
    

메타데이터 표시

사용자와 관련이 있을 수 있는 반환된 항목에 대한 추가 정보를 표시하려면 metadata 필드를 사용합니다. metadata 필드에는 항목의 createTimeupdateTime과 함께 항목과 관련된 반환 가능한 구조화된 데이터가 포함됩니다.

구조화된 데이터를 표시하려면 displayOptions 필드를 사용합니다. displayOptions 필드에는 객체 유형의 표시 라벨과 metalines 집합이 포함됩니다. 각 메타라인은 스키마에 구성된 대로의 표시 라벨과 값 쌍의 배열입니다.

추가 결과 검색

추가 결과를 검색하려면 요청의 start 필드를 원하는 오프셋으로 설정하세요. pageSize 필드를 사용하여 각 페이지의 크기를 조정할 수 있습니다.

반환된 항목의 수를 표시하거나 반환된 항목을 통해 페이지에 대한 페이징 컨트롤을 표시하려면 resultCount 필드를 사용합니다. 결과 집합의 크기에 따라 실제 값 또는 추정된 값이 제공됩니다.

결과 정렬

반환된 항목의 순서를 지정하려면 sortOptions 필드를 사용합니다. sortOptions 값은 2개의 필드가 있는 객체입니다.

  • operatorName — 정렬할 구조화된 데이터 속성의 연산자입니다. 연산자가 여러 개인 속성은 기본 등호 연산자를 사용해서만 정렬할 수 있습니다.
  • sortOrder — 정렬 방향(ASCENDING 또는 DESCENDING)

관련성은 보조 정렬 키로도 사용됩니다. 쿼리에 다른 정렬 순서가 지정되지 않았으면 결과의 순위가 관련성으로만 결정됩니다.

"sortOptions": {
      "operatorName": "priority",
      "sortOrder": "DESCENDING"
    }
    

필터 추가

쿼리 표현식 외에도 필터를 적용하여 결과를 추가로 제한할 수 있습니다. 검색 애플리케이션과 검색 요청에서 모두 필터를 지정할 수 있습니다.

요청 또는 검색 애플리케이션에 필터를 추가하려면 dataSourceRestrictions.filterOptions[] 필드에 필터를 추가하세요.

데이터 소스를 추가로 필터링하는 기본적인 방법은 2가지입니다.

  • filterOptions[].objectType 속성을 통한 객체 필터 — 일치하는 항목을 커스텀 스키마에 정의된 대로 지정한 유형으로 제한합니다.
  • 값 필터 — 일치하는 항목을 쿼리 연산자와 제공된 값을 기준으로 제한합니다.

복합 필터를 사용하면 더 복잡한 쿼리를 위해 여러 개의 값 필터를 논리적 표현식으로 결합할 수 있습니다.

영화 스키마 예시에서 현재 사용자를 기준으로 나이 제한을 적용하고 MPAA 등급을 기준으로 이용 가능한 영화를 제한할 수 있습니다.

{
      "query": "adventure",
      "requestOptions": {
        "searchApplicationId": "<search_app_id>"
      },
      "dataSourceRestrictions": [
        {
          "source": {
            "name": "datasources/<data_source_id>"
          },
          "filterOptions": [
            {
              "objectType": "movie",
              "filter": {
                "compositeFilter": {
                  "logicOperator": "AND"
                  "subFilters": [
                    {
                      "compositeFilter": {
                      "logicOperator": "OR"
                      "subFilters": [
                        {
                          "valueFilter": {
                            "operatorName": "rated",
                            "value": {
                              "stringValue": "G"
                            }
                          }
                        },
                        {
                          "valueFilter": {
                            "operatorName": "rated",
                            "value": {
                              "stringValue": "PG"
                            }
                          }
                        }
                      ]
                    }
                  ]
                }
              }
            }
          ]
        }
      ]
    }
    

패싯으로 결과 상세검색

패싯은 검색결과를 상세검색하기 위한 카테고리를 나타내는, 색인이 생성된 속성입니다. 패싯을 사용하면 사용자가 대화식으로 쿼리를 상세검색하고 관련 항목을 더 빠르게 찾는 데 도움이 됩니다.

검색 애플리케이션에서 패싯을 정의하고 쿼리의 설정을 통해 재정의할 수 있습니다.

패싯을 요청할 때 Cloud Search는 일치하는 항목 중 요청된 속성에서 가장 빈번하게 사용된 값을 계산합니다. 이 값은 응답으로 반환됩니다. 후속 쿼리에서 결과를 좁히는 필터를 만들려면 이 값을 사용합니다.

패싯과의 일반적인 상호작용 패턴은 다음과 같습니다.

  1. 패싯 결과에 포함할 속성을 지정하는 초기 쿼리를 작성합니다.
  2. 검색 및 패싯 결과를 렌더링합니다.
  3. 사용자가 하나 이상의 패싯 값을 선택하여 결과를 상세검색합니다.
  4. 선택한 값을 기반으로 하는 필터를 사용하여 쿼리를 반복합니다.

예를 들어 연도와 MPAA 등급으로 영화 쿼리의 상세검색을 사용 설정하려면 쿼리에 facetOptions 속성을 포함합니다.

"facetOptions": [
      {
        "sourceName": "datasources/<data_source_id>",
        "operatorName": "year"
      },
      {
        "sourceName": "datasources/<data_source_id>",
        "operatorName": "rated"
      }
    ]
    

패싯 버킷 해석

응답의 facetResults 속성에는 요청된 각 속성의 항목이 포함됩니다. 각 속성에는 buckets라는 값 또는 범위의 목록이 제공되며 가장 자주 발생하는 값이 제일 먼저 표시됩니다.

사용자가 필터링할 값을 하나 이상 선택하면 선택한 필터를 사용하여 새로운 쿼리를 생성하고 API를 다시 쿼리하세요.

제안 추가

사용자의 개인 쿼리 기록과 연락처 및 문서 자료를 기반으로 쿼리의 자동 완성을 제공하려면 suggest API를 사용합니다.

예를 들어 다음 호출은 부분 문구 jo에 대한 제안을 제공합니다.

{
      "query": "jo",
      "requestOptions": {
        "searchApplicationId": "<search_app_id>",
        "peoplePhotoOptions": {
          "peoplePhotoUrlSizeInPx": 32
        },
        "timeZone": "America/Denver"
      }
    }
    

그런 다음 결과로 나타난 제안을 애플리케이션에 맞게 표시할 수 있습니다.