Method: query.search

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": string,
  "pageSize": integer,
  "start": integer,
  "dataSourceRestrictions": [
    {
      object (DataSourceRestriction)
    }
  ],
  "facetOptions": [
    {
      object (FacetOptions)
    }
  ],
  "sortOptions": {
    object (SortOptions)
  },
  "queryInterpretationOptions": {
    object (QueryInterpretationOptions)
  },
  "contextAttributes": [
    {
      object (ContextAttribute)
    }
  ]
}
필드
requestOptions

object (RequestOptions)

검색 애플리케이션 및 사용자 시간대와 같은 옵션을 요청합니다.
query

string

원시 쿼리 문자열입니다. 연산자를 사용하여 검색 범위 좁히기에서 지원되는 검색 연산자를 확인하세요.
pageSize

integer

페이지 하나에 반환할 검색 결과의 최대 수입니다. 유효한 값은 1~100입니다. 기본값은 10입니다. 2,000개를 초과하는 결과를 요청하는 경우 최솟값은 50입니다.
start

integer

결과의 시작 색인입니다.
dataSourceRestrictions[]

object (DataSourceRestriction)

쿼리에 사용할 소스입니다. 지정하지 않으면 현재 검색 애플리케이션의 모든 데이터 소스가 사용됩니다.
facetOptions[]

object (FacetOptions)
sortOptions

object (SortOptions)

검색 결과 정렬 옵션
queryInterpretationOptions

object (QueryInterpretationOptions)

사용자 검색어를 해석하는 옵션
contextAttributes[]

object (ContextAttribute)

검색 결과의 순위를 조정하는 데 사용되는 요청의 컨텍스트 속성입니다. 최대 요소 수는 10개입니다.

응답 본문

성공한 경우 응답 본문은 다음과 같은 구조의 데이터를 포함합니다.

Search API 응답입니다.

JSON 표현 
{
  "queryInterpretation": {
    object (QueryInterpretation)
  },
  "results": [
    {
      object (SearchResult)
    }
  ],
  "structuredResults": [
    {
      object (StructuredResult)
    }
  ],
  "spellResults": [
    {
      object (SpellResult)
    }
  ],
  "facetResults": [
    {
      object (FacetResult)
    }
  ],
  "hasMoreResults": boolean,
  "debugInfo": {
    object (ResponseDebugInfo)
  },
  "errorInfo": {
    object (ErrorInfo)
  },
  "resultCounts": {
    object (ResultCounts)
  },

  // Union field result_count can be only one of the following:
  "resultCountEstimate": string,
  "resultCountExact": string
  // End of list of possible types for union field result_count.
}
필드
queryInterpretation

object (QueryInterpretation)

사용자 검색어의 쿼리 해석 결과입니다. 쿼리 해석이 사용 중지된 경우 비어 있습니다.
results[]

object (SearchResult)

검색어의 검색 결과입니다.
structuredResults[]

object (StructuredResult)

사용자 검색어의 구조화된 결과입니다. 이러한 결과는 pageSize에 포함되지 않습니다.
spellResults[]

object (SpellResult)

검색어의 추천 맞춤법입니다.
facetResults[]

object (FacetResult)

반복된 상품 속성 결과
hasMoreResults

boolean

검색어와 일치하는 검색 결과가 더 있는지 여부입니다.
debugInfo

object (ResponseDebugInfo)

응답에 관한 디버깅 정보입니다.
errorInfo

object (ErrorInfo)

응답에 대한 오류 정보입니다.
resultCounts

object (ResultCounts)

확장된 결과 수 정보

통합 필드 result_count. 요청된 모든 데이터 소스의 총 결과 수입니다. 사전 정의된 소스가 쿼리된 데이터 소스 세트에 포함된 경우 생략됩니다. 다음과 같은 경우에는 결과 수가 정확한 수치가 아닌 추정치로 반환될 수 있습니다.

  • 쿼리의 구문에 2개 이상의 검색어가 있는 경우(예: 따옴표로 묶인 '정확한 결과 수').

  • 평가할 고유 검색 결과 ACL 수가 너무 많아서 적절한 지연 시간 내에 계산할 수 없는 경우

드물지만 시스템에서 모든 문서를 검색할 수 없는 경우 쿼리를 다시 실행합니다. result_count는 다음 중 하나여야 합니다.
resultCountEstimate

string (int64 format)

이 쿼리의 예상 결과 수입니다.
resultCountExact

string (int64 format)

이 쿼리의 정확한 결과 수입니다.

승인 범위

다음 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

boolean

쿼리의 자연어 (NL) 해석을 사용 중지하는 플래그입니다. 기본값은 false입니다. 자연어 해석을 사용 중지하려면 true로 설정하세요. NL 해석은 사전 정의된 데이터 소스에만 적용됩니다.
enableVerbatimMode

boolean

이 플래그를 사용 설정하면 쿼리의 자연어 (NL) 해석, 보조 결과 검색, 맞춤 동의어를 포함한 동의어 사용과 같은 모든 내부 최적화가 사용 중지됩니다. 두 플래그 중 하나라도 true이면 Nl 해석이 사용 중지됩니다.
disableSupplementalResults

boolean

이 플래그를 사용하여 쿼리의 보조 결과를 사용 중지합니다. SearchApplication 수준에서 선택한 보조 결과 설정이 true로 설정된 경우 우선 적용됩니다.

QueryInterpretation

JSON 표현 
{
  "interpretedQuery": string,
  "interpretationType": enum (QueryInterpretation.InterpretationType),
  "reason": enum (QueryInterpretation.Reason)
}
필드
interpretedQuery

string

검색에 사용된 검색어의 해석입니다. 예를 들어 '존의 이메일'과 같은 자연어 의도가 포함된 검색어는 'from:john source:mail'로 해석됩니다. 이유가 NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY인 경우 이 필드는 채워지지 않습니다.
interpretationType

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

쿼리 해석 이유입니다. 해석 유형이 NONE이 아닌 경우 이 필드는 UNSPECIFIED가 아닙니다.

QueryInterpretation.InterpretationType

열거형
NONE 검색 결과를 가져오는 데 자연어 해석이나 더 광범위한 버전의 검색어가 사용되지 않습니다.
BLEND 원래 쿼리의 결과가 다른 결과와 혼합됩니다. 이러한 다른 결과를 원래 쿼리의 결과와 혼합하는 이유는 아래의 '이유' 입력란에 입력됩니다.
REPLACE 원래 쿼리의 결과가 대체됩니다. 원본 쿼리의 결과를 대체하는 이유는 아래의 '이유' 입력란에 입력됩니다.

QueryInterpretation.Reason

열거형
UNSPECIFIED
QUERY_HAS_NATURAL_LANGUAGE_INTENT 검색 결과를 가져오는 데 쿼리의 자연어 해석이 사용됩니다.
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY 검색어 및 문서 검색어 유사성은 사용자 검색어에 대해 충분한 결과를 찾을 수 없으므로 검색어를 선택적으로 확장하여 추가 검색 결과를 가져오는 데 사용됩니다. 이 경우 해석된 쿼리는 비어 있습니다.

SearchResult

문서의 색인 생성된 정보가 포함된 결과입니다.

JSON 표현 
{
  "title": string,
  "url": string,
  "snippet": {
    object (Snippet)
  },
  "metadata": {
    object (Metadata)
  },
  "clusteredResults": [
    {
      object (SearchResult)
    }
  ],
  "debugInfo": {
    object (ResultDebugInfo)
  }
}
필드
title

string

검색 결과의 제목입니다.
url

string

검색 결과의 URL입니다. URL에 실제 상품으로 연결되는 Google 리디렉션이 포함되어 있습니다. 이 URL은 서명되어 있으며 변경해서는 안 됩니다.
snippet

object (Snippet)

이 결과에 사용할 수 있는 모든 스니펫 (요약)의 연결입니다.
metadata

object (Metadata)

검색 결과의 메타데이터를 가져옵니다.
clusteredResults[]

object (SearchResult)

소스가 클러스터링된 경우 클러스터링된 결과 목록을 제공합니다. 클러스터링된 결과는 1개 수준으로 표시됩니다. 현재 소스가 클러스터링에 사용 설정되지 않은 경우 이 필드는 비어 있습니다.
debugInfo

object (ResultDebugInfo)

이 검색 결과에 관한 디버깅 정보입니다.

스니펫

검색 결과 페이지의 콘텐츠를 요약하는 검색 결과 스니펫

JSON 표현 
{
  "snippet": string,
  "matchRanges": [
    {
      object (MatchRange)
    }
  ]
}
필드
snippet

string

문서의 스니펫입니다. 문서의 스니펫입니다. 렌더링하기 전에 이스케이프 처리를 해제해야 하는 이스케이프 처리된 HTML 문자가 포함될 수 있습니다.
matchRanges[]

object (MatchRange)

스니펫에서 일치하는 범위입니다.

MatchRange

스니펫의 일치 범위[start, end)입니다.

JSON 표현 
{
  "start": integer,
  "end": integer
}
필드
start

integer

스니펫에서 일치의 시작 위치입니다.
end

integer

스니펫에서 일치의 끝입니다.

메타데이터

일치하는 검색 결과의 메타데이터

JSON 표현 
{
  "source": {
    object (Source)
  },
  "mimeType": string,
  "thumbnailUrl": string,
  "owner": {
    object (Person)
  },
  "createTime": string,
  "updateTime": string,
  "fields": [
    {
      object (NamedProperty)
    }
  ],
  "displayOptions": {
    object (ResultDisplayMetadata)
  },
  "objectType": string
}
필드
source

object (Source)

Gmail과 같이 결과의 이름이 지정된 소스입니다.
mimeType

string

검색 결과의 MIME 유형입니다.
thumbnailUrl

string

결과의 썸네일 URL입니다.
owner

object (Person)

검색 결과의 문서 또는 객체의 소유자 (일반적으로 작성자)입니다.
createTime

string (Timestamp format)

검색 결과에 표시되는 이 문서 또는 객체의 생성 시간입니다.

RFC3339 UTC 'Zulu' 형식의 타임스탬프입니다(나노초 단위, 소수점 이하 9자리). 예를 들면 "2014-10-02T15:01:23Z" 및 "2014-10-02T15:01:23.045123456Z"입니다.
updateTime

string (Timestamp format)

검색 결과에 표시되는 객체의 최종 수정 날짜입니다. 항목에 설정되지 않은 경우 여기에 반환되는 값은 비어 있습니다. updateTime가 최신성 계산에 사용되지 않고 설정되지 않은 경우 이 값은 현재 시간으로부터 2년으로 기본 설정됩니다.

RFC3339 UTC 'Zulu' 형식의 타임스탬프입니다(나노초 단위, 소수점 이하 9자리). 예를 들면 "2014-10-02T15:01:23Z" 및 "2014-10-02T15:01:23.045123456Z"입니다.
fields[]

object (NamedProperty)

구조화된 데이터의 색인화된 필드로, 일반 이름이 지정된 속성으로 반환됩니다.
displayOptions

object (ResultDisplayMetadata)

구조화된 데이터 검색 결과를 표시하는 방법을 지정하는 옵션입니다.
objectType

string

검색 결과의 객체 유형입니다.

ResultDisplayMetadata

JSON 표현 
{
  "objectTypeLabel": string,
  "metalines": [
    {
      object (ResultDisplayMetadata.ResultDisplayLine)
    }
  ]
}
필드
objectTypeLabel

string

객체의 표시 라벨입니다.
metalines[]

object (ResultDisplayMetadata.ResultDisplayLine)

결과와 함께 표시할 메타라인 콘텐츠입니다.

ResultDisplayMetadata.ResultDisplayLine

표시된 선을 구성하는 필드 모음

JSON 표현 
{
  "fields": [
    {
      object (ResultDisplayMetadata.ResultDisplayField)
    }
  ]
}
필드
fields[]

object (ResultDisplayMetadata.ResultDisplayField)

ResultDisplayMetadata.ResultDisplayField

query.search 결과의 필드 표시

JSON 표현 
{
  "label": string,
  "operatorName": string,
  "property": {
    object (NamedProperty)
  }
}
필드
label

string

숙박 시설의 표시 라벨입니다.
operatorName

string

속성의 연산자 이름입니다.
property

object (NamedProperty)

속성의 이름-값 쌍입니다.

ResultDebugInfo

결과에 관한 디버깅 정보입니다.

JSON 표현 
{
  "formattedDebugInfo": string
}
필드
formattedDebugInfo

string

표시할 형식의 일반 디버그 정보입니다.

StructuredResult

검색 요청의 일부로 반환되는 구조화된 결과입니다.

JSON 표현 
{
  "person": {
    object (Person)
  }
}
필드
person

object (Person)

사람의 표현

SpellResult

JSON 표현 
{
  "suggestedQuery": string
}
필드
suggestedQuery

string

쿼리의 추천 맞춤법입니다.

FacetResult

소스별 측정기준 응답

JSON 표현 
{
  "sourceName": string,
  "objectType": string,
  "operatorName": string,
  "buckets": [
    {
      object (FacetBucket)
    }
  ]
}
필드
sourceName

string

상품 속성 결과가 반환되는 소스 이름입니다. 비워 둘 수 없습니다.
objectType

string

상품 속성 결과가 반환되는 객체 유형입니다. 비어 있을 수 있습니다.
operatorName

string

면 분할에 선택된 연산자의 이름입니다. @see cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

응답의 값에 해당하는 필터와 함께 하나 이상의 결과가 포함된 FacetBuckets입니다.

FacetBucket

측정기준의 버킷은 작업의 기본 단위입니다. 버킷은 버케팅된 필드의 유형에 따라 단일 값 또는 연속된 값 범위로 구성될 수 있습니다. FacetBucket은 현재 응답 객체를 반환하는 데만 사용됩니다.

JSON 표현 
{
  "count": integer,
  "percentage": integer,
  "filter": {
    object (Filter)
  },
  "value": {
    object (Value)
  }
}
필드
count

integer

버킷 값과 일치하는 결과의 수입니다. 개수는 개수 정확성이 보장되는 검색에 대해서만 반환됩니다. Cloud Search는 검색어의 측정기준 수를 보장하지 않으며 동일한 검색어의 경우에도 측정기준 수가 간헐적으로만 표시될 수 있습니다. 측정기준 개수 존재에 종속 항목을 빌드하지 마세요. 대신 항상 반환되는 측정기준 개수 비율을 사용하세요.
percentage

integer

버킷 값과 일치하는 결과의 비율입니다. 반환 값은 (0~100] 사이이며 소수점 이하 자릿수가 있는 경우 정수로 반올림됩니다. 값이 명시적으로 반환되지 않으면 0으로 반올림되는 비율 값을 나타냅니다. 비율은 모든 검색에 대해 반환되지만 추정치입니다. 백분율은 항상 반환되므로 개수 대신 백분율을 렌더링해야 합니다.
filter

object (Filter)

해당 버킷이 선택된 경우 검색 요청에 전달할 필터입니다.
value

object (Value)

ResponseDebugInfo

응답에 관한 디버깅 정보입니다.

JSON 표현 
{
  "formattedDebugInfo": string
}
필드
formattedDebugInfo

string

표시할 형식의 일반 디버그 정보입니다.

ErrorInfo

응답에 대한 오류 정보입니다.

JSON 표현 
{
  "errorMessages": [
    {
      object (ErrorMessage)
    }
  ]
}
필드
errorMessages[]

object (ErrorMessage)

ErrorMessage

소스 응답당 오류 메시지

JSON 표현 
{
  "source": {
    object (Source)
  },
  "errorMessage": string
}
필드
source

object (Source)
errorMessage

string

ResultCounts

결과 수 정보

JSON 표현 
{
  "sourceResultCounts": [
    {
      object (SourceResultCount)
    }
  ]
}
필드
sourceResultCounts[]

object (SourceResultCount)

결과가 있는 각 소스의 결과 수 정보입니다.

SourceResultCount

소스별 결과 수 정보

JSON 표현 
{
  "source": {
    object (Source)
  },
  "hasMoreResults": boolean,

  // Union field result_count can be only one of the following:
  "resultCountEstimate": string,
  "resultCountExact": string
  // End of list of possible types for union field result_count.
}
필드
source

object (Source)

결과 수 정보가 연결된 소스입니다.
hasMoreResults

boolean

이 소스에 대한 검색 결과가 더 있는지 여부입니다.

통합 필드 result_count.

result_count는 다음 중 하나여야 합니다.
resultCountEstimate

string (int64 format)

이 소스의 예상 결과 수입니다.
resultCountExact

string (int64 format)

이 소스의 정확한 결과 수입니다.