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": {...}
}]
}
부하 직원 일치
부하 직원 일치를 사용하면 사용자가 특정 사용자의 부하 직원을 볼 수 있습니다. 응답에는 cardType이 RELATED_PEOPLE_ANSWER_CARD인 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...
메타데이터 표시
metadata
필드를 createTime, updateTime 구조화된 데이터와 같은 정보에 사용합니다.
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를 사용합니다.