- HTTP 요청
- 요청 본문
- 응답 본문
- 승인 범위
- QueryInterpretationOptions
- QueryInterpretation
- QueryInterpretation.InterpretationType
- QueryInterpretation.Reason
- SearchResult
- 스니펫
- MatchRange
- 메타데이터
- ResultDisplayMetadata
- ResultDisplayMetadata.ResultDisplayLine
- ResultDisplayMetadata.ResultDisplayField
- ResultDebugInfo
- StructuredResult
- SpellResult
- FacetResult
- FacetBucket
- ResponseDebugInfo
- ErrorInfo
- ErrorMessage
- ResultCounts
- 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개입니다. |
응답 본문
성공할 경우 응답 본문에 다음 구조의 데이터가 포함됩니다.
검색 API 응답입니다.
JSON 표현 |
---|
{ "queryInterpretation": { object ( |
필드 | |
---|---|
queryInterpretation |
사용자 검색어에 대한 검색어 해석 결과입니다. 검색어 해석이 사용 중지된 경우 비어 있습니다. |
results[] |
검색어의 검색결과입니다. |
structuredResults[] |
사용자 검색어에 관한 구조화된 결과입니다. 이러한 결과는 페이지 크기에 포함되지 않습니다. |
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 수준에서 선택한 보완 결과 설정이 우선 적용됩니다. |
QueryInterpretation
JSON 표현 |
---|
{ "interpretedQuery": string, "interpretationType": enum ( |
필드 | |
---|---|
interpretedQuery |
검색에 사용된 검색어의 해석입니다. 예를 들어 'email from john'과 같은 자연어 인텐트가 포함된 쿼리는 'from:john source:mail'로 해석됩니다. 사유가 NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY인 경우 이 필드가 채워지지 않습니다. |
interpretationType |
|
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 ( |
필드 | |
---|---|
title |
검색 결과의 제목입니다. |
url |
검색결과의 URL입니다. URL에는 실제 항목으로 연결되는 Google 리디렉션이 포함됩니다. 이 URL은 서명되었으며 변경할 수 없습니다. |
snippet |
이 결과에 사용할 수 있는 모든 스니펫 (요약)의 연결입니다. |
metadata |
검색결과의 메타데이터입니다. |
clusteredResults[] |
소스가 클러스터링된 경우 클러스터링된 결과 목록을 제공합니다. 클러스터링된 결과는 한 수준만 표시됩니다. 현재 소스가 클러스터링에 사용 설정되지 않은 경우 이 필드는 비어 있습니다. |
debugInfo |
이 검색결과에 대한 디버깅 정보입니다. |
snippet
결과 페이지의 콘텐츠를 요약하는 검색결과의 스니펫입니다.
JSON 표현 |
---|
{
"snippet": string,
"matchRanges": [
{
object ( |
필드 | |
---|---|
snippet |
문서의 스니펫입니다. 문서의 스니펫입니다. 렌더링 전에 이스케이프 취소해야 하는 이스케이프 처리된 HTML 문자가 포함되어 있을 수 있습니다. |
matchRanges[] |
스니펫의 일치 범위입니다. |
MatchRange
스니펫의 일치하는 범위[start, end)입니다.
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 |
속성의 이름 값 쌍입니다. |
ResultDebugInfo
결과에 대한 디버깅 정보입니다.
JSON 표현 |
---|
{ "formattedDebugInfo": string } |
필드 | |
---|---|
formattedDebugInfo |
표시할 형식의 일반 디버그 정보입니다. |
StructuredResult
검색 요청의 일부로 반환되는 구조화된 검색결과입니다.
JSON 표현 |
---|
{
"person": {
object ( |
필드 | |
---|---|
person |
사람을 나타내는 표현 |
SpellResult
JSON 표현 |
---|
{ "suggestedQuery": string } |
필드 | |
---|---|
suggestedQuery |
추천된 쿼리 맞춤법입니다. |
FacetResult
소스 특정 패싯 응답
JSON 표현 |
---|
{
"sourceName": string,
"objectType": string,
"operatorName": string,
"buckets": [
{
object ( |
필드 | |
---|---|
sourceName |
패싯 결과가 반환되는 소스 이름입니다. 비어 있지 않습니다. |
objectType |
패싯 결과가 반환되는 객체 유형입니다. 비어 있을 수 있습니다. |
operatorName |
패싯 생성에 선택한 연산자의 이름입니다. @see cloudsearch.SchemaPropertyOptions |
buckets[] |
해당 필터가 있는 결과가 하나 이상 포함된 응답의 값에 대한 FacetBucket입니다. |
FacetBucket
패싯의 버킷은 기본 작업 단위입니다. 버킷은 버케팅된 필드의 유형에 따라 단일 값 또는 연속된 값 범위로 구성될 수 있습니다. FacetBucket은 현재 응답 객체를 반환하는 데에만 사용됩니다.
JSON 표현 |
---|
{ "count": integer, "percentage": integer, "filter": { object ( |
필드 | |
---|---|
count |
버킷 값과 일치하는 결과 수입니다. 개수는 개수의 정확성이 보장된 경우에만 검색에 대해 반환됩니다. Cloud Search는 모든 쿼리에 대한 상품 속성 수를 보장하지 않으며 동일한 쿼리인 경우에도 상품 속성 수가 간헐적으로만 표시될 수 있습니다. 패싯 수 존재 여부에 대한 종속 항목을 빌드하지 말고, 대신 항상 반환되는 패싯 개수 백분율을 사용하세요. |
percentage |
버킷 값과 일치하는 결과의 비율입니다. 반환된 값은 (0~100] 사이이며 소수인 경우 정수로 내림됩니다. 값이 명시적으로 반환되지 않으면 0으로 반올림되는 백분율 값을 나타냅니다. 비율은 모든 검색에 대해 반환되지만 추정치입니다. 비율은 항상 반환되므로 개수 대신 비율을 렌더링해야 합니다. |
filter |
해당 버킷이 선택된 경우 검색 요청에서 전달할 필터입니다. |
value |
|
ResponseDebugInfo
응답에 대한 디버깅 정보입니다.
JSON 표현 |
---|
{ "formattedDebugInfo": string } |
필드 | |
---|---|
formattedDebugInfo |
표시할 형식의 일반 디버그 정보입니다. |
ErrorInfo
응답에 대한 오류 정보입니다.
JSON 표현 |
---|
{
"errorMessages": [
{
object ( |
필드 | |
---|---|
errorMessages[] |
|
ErrorMessage
소스 응답당 오류 메시지입니다.
JSON 표현 |
---|
{
"source": {
object ( |
필드 | |
---|---|
source |
|
errorMessage |
|
ResultCounts
결과 수 정보
JSON 표현 |
---|
{
"sourceResultCounts": [
{
object ( |
필드 | |
---|---|
sourceResultCounts[] |
결과가 있는 각 소스의 결과 수 정보입니다. |
SourceResultCount
소스별 결과 수 정보입니다.
JSON 표현 |
---|
{ "source": { object ( |
필드 | |
---|---|
source |
결과 수 정보와 연결된 소스입니다. |
hasMoreResults |
이 소스에 대한 검색결과가 더 있는지 여부입니다. |
통합 필드
|
|
resultCountEstimate |
이 소스의 예상 결과 수입니다. |
resultCountExact |
이 소스의 정확한 결과 수입니다. |