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

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

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

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

검색 인터페이스 빌드

최소한의 검색 인터페이스를 빌드하려면 다음과 같은 여러 단계를 거쳐야 합니다.

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

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

검색 애플리케이션 구성

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

검색 애플리케이션에 대한 자세한 내용은 Cloud Search에서 검색 환경 맞춤설정을 참조하세요.

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

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

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

OAuth 옵션 및 클라이언트 라이브러리에 대한 자세한 내용은 [Google Identity Platform](https://developers.google.com/identity/choose-auth{: .external target="_blank"})을 참조하세요.

색인 쿼리

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

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

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

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

쿼리 결과 표시

검색 인터페이스에는 최소한 항목 title와 원래 항목의 링크가 표시되어야 합니다. 검색결과에 표시되는 추가 정보(예: 스니펫, 메타데이터)를 활용하여 검색결과 표시를 개선할 수 있습니다.

추가 결과 처리

기본적으로 Cloud Search는 사용자 쿼리에 대한 결과가 충분하지 않은 경우 보조 결과를 반환합니다. 응답의 queryInterpretation 필드는 추가 결과가 반환되는 시기를 나타냅니다. 추가 결과만 반환되면 InterpretationType이 REPLACE로 설정됩니다. 원래 쿼리의 결과가 추가 결과와 함께 반환되면 InterpretationType가 BLEND로 설정됩니다. 두 경우 모두 QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY입니다.

일부 보조 결과가 반환되면 보충 결과가 반환되었음을 나타내는 텍스트를 제공하는 것이 좋습니다. 예를 들어 REPLACE의 경우 '원래 검색어와 일치하는 결과가 없습니다. 유사한 검색어의 검색결과를 표시합니다.'

BLEND의 경우 '원래 검색어와 일치하는 결과가 충분하지 않습니다. 유사한 쿼리의 결과를 포함합니다."

사용자 검색결과 처리

Cloud Search는 두 가지 유형의 '인물 결과'를 반환합니다. 즉, 쿼리에 이름이 사용된 사람과 관련된 문서와 쿼리에 이름이 사용된 사람의 직원 정보가 반환됩니다. 후자의 결과는 Cloud Search 사용자 검색 기능의 기능이며 이러한 쿼리의 결과는 쿼리 API 응답의 structuredResults 필드에서 찾을 수 있습니다.

{
  "results": [...],
  "structuredResults": [{
    "person": {...}
  }]
}

직접 보고서 매칭

직접 보고서 매칭은 사용자가 조직 내 개인의 직속 보고자를 볼 수 있는 Cloud Search의 사용자 검색 기능입니다. 결과는 structuredResults 필드에서 확인할 수 있습니다.

사용자의 관리자 또는 직속 부하 직원에 관한 쿼리의 경우 응답의 structuredResults 내에 assistCardProtoHolder가 있습니다. assistCardProtoHolder에는 RELATED_PEOPLE_ANSWER_CARD와 동일한 cardType 필드가 있습니다. assistCardProtoHolder에는 실제 응답이 포함된 relatedPeopleAnswerCard이라는 카드가 포함되어 있습니다. 여기에는 subject (쿼리에 포함된 사람)와 주제와 관련된 사람 집합인 relatedPeople가 포함됩니다. relationType 필드는 MANAGER 또는 DIRECT_REPORTS 값을 반환합니다.

다음 코드는 검색어와 일치하는 직속 보고자의 응답 예를 보여줍니다.

{
  "results": [],
  "structuredResults": [{
    "assistCardProtoHolder": {
      "extensions": {
        "@type": "type.googleapis.com/enterprise.topaz.sidekick.AssistCardProto",
        "cardMetadata": {
          "cardCategory": "ANSWER"
        },
        "cardType": "RELATED_PEOPLE_ANSWER_CARD",
        "relatedPeopleAnswerCard": {
          "subject": {
            "email": "AdamStanford@psincs-test01.newjnj.com",
            "displayName": "Adam Stanford"
            "manager": {
              "email": "simonsais@psincs-test01.newjnj.com"
            }
          },
          "relatedPeople": [{
            "email": "EdgarMountainRamirez@psincs-test01.newjnj.com",
            "displayName": "Edgar Mountain Ramirez"
          }, {
            "email": "FranciscoJoseMartinez@psincs-test01.newjnj.com",
            "displayName": "Francisco Jose Martinez"
          }],
          "relationType": "DIRECT_REPORTS",
        }
      }
    }
  }]
}

추가 결과를 포함한 최적화 사용 중지

기본적으로 추가 결과와 같은 최적화가 사용 설정됩니다. 그러나 검색 애플리케이션과 쿼리 수준 모두에서 모든 최적화를 사용 중지하거나 보충 결과만 사용 중지할 수 있습니다.

추가 결과, 동의어, 맞춤법 수정을 포함하여 검색 애플리케이션 수준에서 모든 최적화를 사용 중지하려면 검색 애플리케이션에서 QueryInterpretationConfig.force_verbatim_mode를 true로 설정합니다.
추가 결과, 동의어, 맞춤법 수정을 포함하여 검색어 수준에서 모든 최적화를 사용 중지하려면 검색어에서 QueryInterpretationOptions.enableVerbatimMode를 true로 설정합니다.
검색 애플리케이션 수준에서 보조 결과를 사용 중지하려면 검색어에서 QueryInterpretationOptions.forceDisableSupplementalResults를 true로 설정합니다.
검색어 수준에서 보조 결과를 사용 중지하려면 검색어에서 QueryInterpretationOptions.disableSupplementalResults를 true로 설정합니다.

본문 미리보기 강조 표시

색인이 생성된 텍스트 또는 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 필드에는 항목의 createTime 및 updateTime와 항목과 연결된 반환 가능한 구조화된 데이터가 포함됩니다.

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

추가 결과 검색

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

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

결과 정렬

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

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는 일치하는 항목 중 요청된 속성에서 가장 빈번하게 사용된 값을 계산합니다. 이 값은 응답으로 반환됩니다. 후속 쿼리에서 결과를 좁히는 필터를 만들려면 이 값을 사용합니다.

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

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

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

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

정수 기반 필드를 사용하여 결과 패싯을 요청할 수도 있습니다. 예를 들어 book_pages라는 정수 속성을 패싯으로 표시하여 '100~200' 페이지의 도서에 대한 검색 결과를 세분화할 수 있습니다.

정수 속성 필드 스키마를 설정할 때 isFacetable를 true로 설정하고 해당 버케팅 옵션을 integerPropertyOptions에 추가합니다. 이렇게 하면 정수 패싯 생성 가능 속성의 모든 기본 버케팅 옵션이 정의됩니다.

버케팅 옵션 로직을 정의할 때는 범위를 나타내는 증분 값의 배열을 제공합니다. 예를 들어 최종 사용자가 범위를 2, 5, 10, 100로 지정하면 <2, [2-5), [5-10), [10-100), >=100의 패싯이 계산됩니다.

요청에서 동일한 버케팅 옵션을 facetOptions로 정의하여 정수 기반 패싯을 재정의할 수 있습니다. 필요한 경우 검색 애플리케이션 및 쿼리 요청에 모두 패싯 옵션이 정의되어 있지 않으면 Cloud Search는 스키마에 정의된 버케팅 옵션을 사용합니다. 쿼리에 정의된 패싯은 검색 애플리케이션에 정의된 패싯보다 우선하며, 검색 애플리케이션에 정의된 패싯은 스키마에 정의된 패싯보다 우선합니다.

예약 연산자를 사용하여 문서의 파일 크기(바이트 단위) 또는 문서가 생성되거나 수정된 시점을 기준으로 검색결과를 세분화할 수 있습니다. 커스텀 스키마를 정의할 필요는 없지만 검색 애플리케이션의 FacetOptions에 operatorName 값은 지정해야 합니다.

문서 크기별 패싯 생성의 경우 itemsize을 사용하고 버케팅 옵션을 정의합니다.
문서 생성 날짜별 패싯 생성에는 createddatetimestamp를 사용합니다.
문서 수정 날짜별로 패싯 생성하려는 경우 lastmodified를 사용합니다.

패싯 버킷 해석

검색어 응답의 facetResults 속성은 각 bucket의 filter 필드에 사용자의 정확한 필터 요청을 포함합니다.

정수를 기반으로 하지 않는 상품 속성의 경우 facetResults에는 요청된 각 속성의 항목이 포함됩니다. 각 속성에는 buckets이라는 값 또는 범위의 목록이 제공됩니다. 가장 자주 발생하는 값이 제일 먼저 표시됩니다.

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

제안 추가

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

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

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

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