- HTTP 요청
- 요청 본문
- 응답 본문
- 승인 범위
- QueryInterpretationOptions
- QueryInterpretation
- QueryInterpretation.InterpretationType
- QueryInterpretation.Reason
- SearchResult
- 스니펫
- MatchRange
- 메타데이터
- ResultDisplayMetadata
- ResultDisplayMetadata.ResultDisplayLine
- ResultDisplayMetadata.ResultDisplayField
- ResultDebugInfo입니다.
- 구조화된 검색결과
- SpellResult
- FacetResult
- FacetBucket
- ResponseDebugInfo
- ErrorInfo
- ErrorMessage
- ResultCount
- SourceResultCount
- 실습
Cloud Search Query API는 사용자 쿼리에서 가장 관련성이 높은 결과를 반환하는 검색 메서드를 제공합니다. 결과는 Gmail 또는 Google Drive와 같은 Google Workspace 앱에서 가져오거나 서드 파티에서 색인을 생성한 데이터에서 가져올 수 있습니다.
참고: 이 API를 사용하려면 표준 최종 사용자 계정이 필요합니다. 서비스 계정은 Query API 요청을 직접 수행할 수 없습니다. 서비스 계정을 사용하여 쿼리를 수행하려면 Google Workspace 도메인 전체 권한 위임을 설정합니다.
HTTP 요청
POST https://cloudsearch.googleapis.com/v1/query/search
URL은 gRPC 트랜스코딩 구문을 사용합니다.
요청 본문
요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.
JSON 표현 |
---|
{ "requestOptions": { object ( |
필드 | |
---|---|
requestOptions |
요청 옵션(예: 검색 애플리케이션 및 사용자 시간대) |
query |
원시 쿼리 문자열입니다. 지원되는 검색 연산자를 보려면 연산자로 검색 범위 좁히기를 참고하세요. |
pageSize |
한 페이지에서 반환할 최대 검색결과 수입니다. 유효한 값은 1에서 100 사이입니다. 기본값은 10입니다. 2,000개를 초과하는 결과가 요청되는 경우 최솟값은 50입니다. |
start |
결과의 시작 색인입니다. |
dataSourceRestrictions[] |
쿼리에 사용할 소스입니다. 지정하지 않으면 현재 검색 애플리케이션의 모든 데이터 소스가 사용됩니다. |
facetOptions[] |
|
sortOptions |
검색결과 정렬 옵션 |
queryInterpretationOptions |
사용자 검색어를 해석하는 옵션 |
contextAttributes[] |
검색결과의 순위를 조정하는 데 사용할 요청의 컨텍스트 속성입니다. 요소의 최대 개수는 10개입니다. |
응답 본문
성공할 경우 응답 본문에 다음 구조의 데이터가 포함됩니다.
Search API 응답입니다.
JSON 표현 |
---|
{ "queryInterpretation": { object ( |
필드 | |
---|---|
queryInterpretation |
사용자 검색어에 대한 검색어 해석 결과입니다. 검색어 해석이 사용 중지된 경우 비어 있습니다. |
results[] |
검색어의 검색결과입니다. |
structuredResults[] |
사용자 쿼리의 구조화된 결과입니다. 이러한 결과는 pageSize에 반영되지 않습니다. |
spellResults[] |
추천 검색어의 맞춤법입니다. |
facetResults[] |
상품 속성 결과가 반복되었습니다. |
hasMoreResults |
쿼리와 일치하는 검색결과가 더 있는지 여부 |
debugInfo |
응답에 관한 디버깅 정보입니다. |
errorInfo |
응답에 대한 오류 정보입니다. |
resultCounts |
확장된 결과 수 정보 |
통합 필드
드물지만 시스템이 일부 문서를 검색할 수 없는 경우 쿼리를 다시 실행하세요. |
|
resultCountEstimate |
이 쿼리의 예상 결과 수입니다. |
resultCountExact |
이 쿼리의 정확한 결과 수입니다. |
승인 범위
다음 OAuth 범위 중 하나가 필요합니다.
https://www.googleapis.com/auth/cloud_search.query
https://www.googleapis.com/auth/cloud_search
자세한 내용은 승인 가이드를 참고하세요.
QueryInterpretationOptions 클래스의 생성자
사용자 검색어를 해석하는 옵션
JSON 표현 |
---|
{ "disableNlInterpretation": boolean, "enableVerbatimMode": boolean, "disableSupplementalResults": boolean } |
필드 | |
---|---|
disableNlInterpretation |
쿼리에 대한 자연어 (NL) 해석을 사용 중지하는 플래그입니다. 기본값은 false입니다. 자연어 해석을 사용 중지하려면 true로 설정하세요. NL 해석은 사전 정의된 데이터 소스에만 적용됩니다. |
enableVerbatimMode |
이 플래그를 사용 설정하면 자연어 (NL)로 해석되는 모든 내부 최적화, 추가 결과 검색, 커스텀 동의어를 포함한 동의어 사용이 중지됩니다. 두 플래그 중 하나가 true인 경우 Nl 해석이 사용 중지됩니다. |
disableSupplementalResults |
쿼리의 추가 결과를 사용 중지하려면 이 플래그를 사용합니다. True로 설정하면 SearchApplication 수준에서 선택한 추가 결과 설정이 우선 적용됩니다. |
검색어 해석
JSON 표현 |
---|
{ "interpretedQuery": string, "interpretationType": enum ( |
필드 | |
---|---|
interpretedQuery |
검색에 사용된 검색어의 해석 예를 들어 'email from john'과 같은 자연어 인텐트가 있는 쿼리는 'from:john source:mail'로 해석됩니다. 이유가 NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY인 경우 이 필드가 채워지지 않습니다. |
interpretationType |
|
reason |
검색어가 해석된 이유입니다. 해석 유형이 '없음'인 경우 이 필드는 지정되지 않습니다. |
Query 해석 해독 유형
열거형 | |
---|---|
NONE |
검색결과를 해석하는 데는 자연어 해석이나 더 광범위한 버전의 검색어가 사용되지 않습니다. |
BLEND |
원래 쿼리의 결과가 다른 결과와 혼합됩니다. 이러한 다른 결과를 원본 쿼리 결과와 혼합하는 이유는 아래의 '이유' 필드에 채워집니다. |
REPLACE |
원래 쿼리의 결과가 대체됩니다. 원래 쿼리의 결과를 교체하는 이유는 아래의 '이유' 입력란에 입력되어 있습니다. |
QueryInterpretation.Reason
열거형 | |
---|---|
UNSPECIFIED |
|
QUERY_HAS_NATURAL_LANGUAGE_INTENT |
검색어를 가져오는 데 자연어 자연어 해석이 사용됩니다. |
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY |
검색어 및 문서 유사성은 사용자 검색어에 대한 충분한 결과를 찾을 수 없기 때문에 검색어를 선택적으로 확장하여 추가 검색결과를 가져오는 데 사용됩니다. 이 경우에는 해석된 쿼리가 비어 있습니다. |
검색결과
문서에 대한 색인이 생성된 정보가 포함된 결과입니다.
JSON 표현 |
---|
{ "title": string, "url": string, "snippet": { object ( |
필드 | |
---|---|
title |
검색결과의 제목입니다. |
url |
검색결과의 URL입니다. URL에 실제 항목에 대한 Google 리디렉션이 포함되어 있습니다. 서명된 URL이므로 변경할 수 없습니다. |
snippet |
이 결과에 사용할 수 있는 모든 스니펫 (요약) 연결입니다. |
metadata |
검색결과의 메타데이터입니다. |
clusteredResults[] |
소스가 클러스터링된 경우 클러스터링된 결과 목록을 제공합니다. 클러스터링된 결과는 한 수준만 표시됩니다. 클러스터링에 현재 소스가 사용 설정되지 않은 경우 이 필드는 비어 있습니다. |
debugInfo |
이 검색결과에 대한 디버깅 정보입니다. |
스니펫
검색결과의 페이지 콘텐츠를 요약하는 검색결과의 스니펫입니다.
JSON 표현 |
---|
{
"snippet": string,
"matchRanges": [
{
object ( |
필드 | |
---|---|
snippet |
문서의 스니펫입니다. 문서의 스니펫입니다. 렌더링하기 전에 이스케이프 처리되지 않은 이스케이프 처리된 HTML 문자를 포함할 수 있습니다. |
matchRanges[] |
스니펫에서 일치하는 범위입니다. |
일치 범위
스니펫의 일치하는 범위[시작, 끝)
JSON 표현 |
---|
{ "start": integer, "end": integer } |
필드 | |
---|---|
start |
스니펫에서 일치의 시작 위치입니다. |
end |
스니펫의 일치 항목 끝입니다. |
메타데이터
일치하는 검색결과의 메타데이터입니다.
JSON 표현 |
---|
{ "source": { object ( |
필드 | |
---|---|
source |
Gmail과 같이 이름이 지정된 소스입니다. |
mimeType |
검색결과의 MIME 유형입니다. |
thumbnailUrl |
검색결과의 썸네일 URL입니다. |
owner |
검색결과 문서 또는 객체의 소유자 (일반적으로 작성자) |
createTime |
검색결과에서 이 문서 또는 객체의 생성 시간입니다. RFC3339 UTC 'Zulu' 형식의 타임스탬프(나노초 해상도 및 최대 9자리 소수) 예: |
updateTime |
검색결과에서 마지막으로 객체가 수정된 날짜입니다. 항목에 설정되지 않은 경우 여기에 반환되는 값은 비어 있습니다. RFC3339 UTC 'Zulu' 형식의 타임스탬프(나노초 해상도 및 최대 9자리 소수) 예: |
fields[] |
구조화된 데이터에서 색인이 지정된 필드로, 이름이 지정된 일반 속성으로 반환됩니다. |
displayOptions |
구조화된 데이터 검색결과를 표시하는 방법을 지정하는 옵션입니다. |
objectType |
검색결과의 객체 유형입니다. |
ResultDisplayMetadata 클래스의 생성자
JSON 표현 |
---|
{
"objectTypeLabel": string,
"metalines": [
{
object ( |
필드 | |
---|---|
objectTypeLabel |
객체의 표시 라벨입니다. |
metalines[] |
결과와 함께 표시될 메타라인 콘텐츠입니다. |
ResultDisplayMetadata.ResultDisplayLine 클래스의 생성자
표시된 선을 구성하는 필드 모음
JSON 표현 |
---|
{
"fields": [
{
object ( |
필드 | |
---|---|
fields[] |
ResultDisplayMetadata.ResultDisplayField
query.search 결과의 필드 표시
JSON 표현 |
---|
{
"label": string,
"operatorName": string,
"property": {
object ( |
필드 | |
---|---|
label |
속성의 표시 라벨입니다. |
operatorName |
속성의 연산자 이름입니다. |
property |
속성의 이름 값 쌍입니다. |
결과 디버그 정보
결과에 관한 디버깅 정보입니다.
JSON 표현 |
---|
{ "formattedDebugInfo": string } |
필드 | |
---|---|
formattedDebugInfo |
디스플레이용으로 형식이 지정된 일반 디버그 정보입니다. |
구조화된 결과
검색 요청의 일부로 반환되는 구조화된 결과입니다.
JSON 표현 |
---|
{
"person": {
object ( |
필드 | |
---|---|
person |
인물의 표현 |
맞춤법 결과
JSON 표현 |
---|
{ "suggestedQuery": string } |
필드 | |
---|---|
suggestedQuery |
추천 검색어의 맞춤법입니다. |
FacetResult
소스별 상품 속성 응답
JSON 표현 |
---|
{
"sourceName": string,
"objectType": string,
"operatorName": string,
"buckets": [
{
object ( |
필드 | |
---|---|
sourceName |
상품 속성 결과가 반환되는 소스 이름입니다. 비어 있지 않습니다. |
objectType |
상품 속성 결과가 반환되는 객체 유형입니다. 비어 있을 수 있습니다. |
operatorName |
패싯 생성에 선택한 연산자의 이름입니다. @see cloudsearch.SchemaPropertyOptions |
buckets[] |
상응하는 필터와 함께 하나 이상의 결과를 포함하는 응답의 FacetBucket입니다. |
패싯 버킷
상품 속성의 버킷은 기본 작업 단위입니다. 버킷은 버케팅된 필드의 유형에 따라 단일 값 또는 연속된 값 범위로 구성될 수 있습니다. FacetBucket은 현재 응답 객체를 반환하는 데만 사용됩니다.
JSON 표현 |
---|
{ "count": integer, "percentage": integer, "filter": { object ( |
필드 | |
---|---|
count |
버킷 값과 일치하는 결과 수입니다. 개수의 정확성이 보장되는 경우에만 검색에 개수가 반환됩니다. Cloud Search는 쿼리에 대한 상품 속성 개수를 보장하지 않으며, 동일한 쿼리에도 상품 속성 수가 간헐적으로 표시될 수 있습니다. 상품 속성 수 존재에 대한 종속성을 빌드하지 말고, 대신 항상 반환되는 상품 속성 비율을 사용합니다. |
percentage |
버킷 값과 일치하는 결과의 비율입니다. 반환되는 값은 (0~100] 사이이며, 소수인 경우 정수로 반내림됩니다. 값이 명시적으로 반환되지 않은 경우 0으로 반올림한 백분율 값을 나타냅니다. 백분율은 모든 검색에 대해 반환되지만 추정치입니다. 백분율은 항상 반환되므로 개수 대신 비율을 렌더링해야 합니다. |
filter |
해당 버킷이 선택된 경우 검색 요청에 전달할 필터입니다. |
value |
|
응답 디버그 정보
응답에 관한 디버깅 정보입니다.
JSON 표현 |
---|
{ "formattedDebugInfo": string } |
필드 | |
---|---|
formattedDebugInfo |
디스플레이용으로 형식이 지정된 일반 디버그 정보입니다. |
ErrorInfo
응답에 대한 오류 정보입니다.
JSON 표현 |
---|
{
"errorMessages": [
{
object ( |
필드 | |
---|---|
errorMessages[] |
|
ErrorMessage
소스 응답당 오류 메시지입니다.
JSON 표현 |
---|
{
"source": {
object ( |
필드 | |
---|---|
source |
|
errorMessage |
|
결과 수
결과 수 정보
JSON 표현 |
---|
{
"sourceResultCounts": [
{
object ( |
필드 | |
---|---|
sourceResultCounts[] |
결과가 있는 각 소스의 결과 수 정보 |
소스 결과 수
소스별 결과 수 정보.
JSON 표현 |
---|
{ "source": { object ( |
필드 | |
---|---|
source |
결과 수 정보와 연결된 소스입니다. |
hasMoreResults |
이 소스에 대한 검색결과가 더 있는지 여부입니다. |
통합 필드
|
|
resultCountEstimate |
이 소스의 예상 결과 수입니다. |
resultCountExact |
이 소스의 정확한 결과 수입니다. |