Query API는 검색 인터페이스를 빌드하거나 결과를 애플리케이션에 삽입하기 위한 방법을 검색하고 제안합니다.
요구사항이 많지 않은 웹 애플리케이션은 검색 위젯을 사용하는 것이 좋습니다. 검색 위젯으로 검색 인터페이스 만들기를 참고하세요.
검색 인터페이스 빌드
단순한 검색 인터페이스를 빌드하는 경우에도 다음과 같은 여러 단계가 필요합니다.
- 검색 애플리케이션을 구성합니다.
- 애플리케이션용 OAuth 사용자 인증 정보를 생성합니다.
- 색인을 쿼리합니다.
- 쿼리 결과를 표시합니다.
페이징, 정렬, 필터링, 패싯, 자동 완성 등의 기능을 사용하여 인터페이스를 개선할 수 있습니다.
검색 애플리케이션 구성
각 검색 인터페이스에 대해 하나 이상의 검색 애플리케이션을 만들어야 합니다. 검색 애플리케이션은 데이터 소스, 정렬 순서, 필터, 패싯과 같은 기본 매개변수를 제공합니다. Query API를 사용하여 이러한 매개변수를 재정의할 수 있습니다.
검색 애플리케이션에 구성된 수보다 많게 쿼리에 사용되는 데이터 소스의 수를 늘릴 수는 없습니다. dataSourceRestrictions를 사용하여 이러한 소스의 하위 집합으로 쿼리를 제한할 수 있습니다.
자세한 내용은 검색 환경 맞춤설정을 참고하세요.
애플리케이션용 OAuth 사용자 인증 정보 생성
Cloud Search API에 대한 액세스 구성 단계 외에도 웹 애플리케이션용 OAuth 사용자 인증 정보를 생성해야 합니다.
사용자 대신 승인을 요청하려면 사용자 인증 정보를 사용합니다. https://www.googleapis.com/auth/cloud_search.query 범위를 사용합니다.
OAuth 옵션에 대한 자세한 내용은 Google Identity Platform을 참고하세요.
색인 쿼리
search 메서드를 사용하여 색인을 검색합니다.
모든 요청에는 텍스트 query와 searchApplicationId가 포함되어야 합니다.
이 예에서는 영화 데이터 소스를 쿼리합니다.
{
"query": "titanic",
"requestOptions": {
"searchApplicationId": "searchapplications/<search_app_id>"
}
}
쿼리 결과 표시
검색 인터페이스에는 항목 title과 원래 항목에 대한 링크가 표시되어야 합니다. 스니펫과 메타데이터를 사용하여 표시를 개선할 수도 있습니다.
보완 결과 처리
Cloud Search는 쿼리와 일치하는 항목이 충분하지 않은 경우 보충 결과를 반환합니다. queryInterpretation 필드에 이 항목이 표시되어 있습니다. 보충 결과만 반환되는 경우 InterpretationType는 REPLACE입니다. 혼합된 경우 BLEND입니다.
보충 결과를 반환할 때는 사용자에게 알리는 것이 좋습니다. REPLACE의 경우 '검색어와 일치하는 결과가 없습니다. 유사한 질문에 대한 검색 결과가 표시됩니다.'
인물 결과 처리
Cloud Search는 인물 검색 기능을 사용하여 인물 및 직원 정보와 관련된 문서를 반환합니다. 결과는 structuredResults 필드에 있습니다.
{
"results": [...],
"structuredResults": [{
"person": {...}
}]
}
부하 직원 매칭
직속 부하 직원 매칭을 사용하면 사용자가 다른 사용자의 직속 부하 직원을 볼 수 있습니다. 응답에는 RELATED_PEOPLE_ANSWER_CARD의 cardType이 있는 assistCardProtoHolder이 포함됩니다.
최적화 사용 중지
보충 결과와 같은 최적화는 기본적으로 사용 설정되어 있습니다. 다음과 같이 사용 중지할 수 있습니다.
- 검색 애플리케이션 수준:
force_verbatim_mode을true로 설정합니다. - 쿼리 수준:
enableVerbatimMode을true로 설정합니다.
본문 미리보기 강조 표시
Cloud Search는 색인이 생성된 텍스트 또는 HTML의 스니펫을 반환합니다. 검색어가 있으면 matchRanges가 위치를 식별합니다. 이 범위를 사용하여 텍스트를 강조 표시합니다.
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...
메타데이터 표시
createTime, updateTime, 구조화된 데이터와 같은 정보에는 metadata 필드를 사용하세요.
displayOptions을 사용하여 구조화된 데이터를 표시합니다.
추가 결과 검색
더 많은 결과를 검색하려면 start 필드를 선택한 오프셋으로 설정하세요. pageSize로 페이지 크기를 조정합니다. resultCount를 사용하여 총 항목 또는 예상 개수를 표시합니다.
결과 정렬
sortOptions을 사용하여 순서를 지정합니다.
operatorName: 정렬할 속성입니다.sortOrder:ASCENDING또는DESCENDING입니다.
관련성은 기본 및 보조 정렬 키입니다.
필터 추가
검색 애플리케이션 또는 요청에서 필터를 사용하여 결과를 제한합니다. 두 필터 모두 소스에 대한 필터를 지정하는 경우 두 필터가 모두 true로 평가되어야 합니다.
dataSourceRestrictions.filterOptions[]에서 필터를 적용합니다.
기본 필터 유형:
- 객체 필터: 일치 항목을 특정 유형으로 제한합니다.
- 값 필터: 연산자와 값을 기준으로 일치 항목을 제한합니다.
복합 필터는 여러 값 필터를 결합합니다.
패싯으로 결과 상세검색
패싯은 사용자가 대화식으로 쿼리를 상세검색하는 데 도움이 됩니다. 패싯을 요청하면 Cloud Search는 해당 속성의 가장 빈번한 값을 계산합니다.
일반적인 패턴: 1. 패싯 속성을 지정하는 쿼리입니다. 1. 검색 및 패싯 결과를 렌더링합니다. 1. 사용자가 패싯 값을 선택합니다. 1. 선택사항을 기반으로 하는 필터를 사용하여 쿼리를 반복합니다.
정수 기반 필드가 있는 패싯 결과
정수 속성을 패싯으로 표시하여 범위별로 결과를 세부적으로 조정합니다 (예:
'100~200' 페이지). isFacetable을 true로 설정하고 스키마에서 기본 버킷팅 옵션을 정의합니다.
문서 크기 또는 날짜별로 패싯 결과
예약된 연산자를 사용합니다.
itemsize: 파일 크기(바이트)createddatetimestamp: 생성 날짜lastmodified: 수정 날짜
제안 추가
쿼리 기록, 연락처, 문서 콘텐츠를 기반으로 자동 완성을 제공하려면 suggest API를 사용합니다.