이 페이지는 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 Functions의 Google 검색의 사용자 검색 기능 및 이러한 검색어에 대한 결과는 structuredResults 쿼리 API 응답 필드:

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

직속 보고자 일치

직속 보고서 일치는 Cloud Search의 사용자 검색 기능으로 조직 내 특정 직원의 직속 보고자를 볼 수 있습니다. 결과는 structuredResults 필드 내에 제공됩니다.

개인의 관리자 또는 부하 직원에 대한 쿼리의 경우 응답에 structuredResults 내 assistCardProtoHolder 이 assistCardProtoHolder에는 다음과 같은 cardType 필드가 있습니다. RELATED_PEOPLE_ANSWER_CARD입니다. 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는 검색 애플리케이션과 쿼리 요청에 모두 패싯이 없는 경우 스키마 옵션을 정의했습니다. 쿼리에 정의된 패싯이 정의된 패싯보다 우선합니다. 검색 애플리케이션에 정의된 패싯은 스키마에 정의된 패싯보다 우선합니다

이때 예약 연산자 문서의 파일 크기(바이트 단위) 또는 문서가 생성 또는 수정된 경우 커스텀 스키마를 정의할 필요는 없지만 검색 애플리케이션의 operatorName 값을 FacetOptions

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

패싯 버킷 해석

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

정수를 기반으로 하지 않는 패싯의 경우 facetResults에는 다음에 대한 항목이 포함됩니다. 확인할 수 있습니다 각 속성에 대해 buckets가 제공됩니다. 가장 자주 발생하는 값이 제일 먼저 표시됩니다.

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

제안 추가

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

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

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

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