Query API는 검색 인터페이스를 빌드하거나 검색 결과를 애플리케이션에 삽입하기 위한 방법을 검색하고 제안합니다.
요구사항이 많지 않은 웹 애플리케이션은 검색 위젯을 사용하는 것이 좋습니다. 자세한 내용은 검색 위젯으로 검색 인터페이스 만들기를 참고하세요.
검색 인터페이스 빌드
단순한 검색 인터페이스를 빌드하는 경우에도 다음과 같은 여러 단계가 필요합니다.
- 검색 애플리케이션 구성
- 애플리케이션용 OAuth 사용자 인증 정보 생성
- 색인 쿼리
- 쿼리 결과 표시
페이징, 정렬, 필터링, 패싯, 자동 제안과 같은 기능을 사용하여 검색 인터페이스를 더욱 향상시킬 수 있습니다.
검색 애플리케이션 구성
생성한 각 검색 인터페이스와 연결할 검색 애플리케이션을 하나 이상 만들어야 합니다. 검색 애플리케이션은 사용할 데이터 소스, 정렬 순서, 필터, 요청할 상품 속성 등 쿼리의 기본 매개변수를 제공합니다. 필요한 경우 Query 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 메서드를 사용합니다.
모든 요청은 2가지 정보를 포함해야 합니다. 하나는 항목과 일치시킬 텍스트 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"
}
}
그런 다음 결과로 나타난 제안을 애플리케이션에 맞게 표시할 수 있습니다.