Method: query.search

Cloud Search 쿼리 API는 사용자 쿼리에서 가장 관련성이 높은 결과를 반환하는 검색 메서드를 제공합니다. 결과는 Gmail 또는 Google Drive와 같은 Google Workspace 앱에서 가져올 수도 있고, 서드 파티에서 색인을 생성한 데이터에서 가져올 수도 있습니다.

참고: 이 API를 실행하려면 표준 최종 사용자 계정이 필요합니다. 서비스 계정은 쿼리 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개입니다.

응답 본문

검색 API 응답입니다. 다음 ID: 19

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

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. 요청된 모든 데이터 소스의 총 결과 수입니다. 쿼리된 데이터 소스 집합에 사전 정의된 소스가 포함된 경우 생략됩니다. 다음과 같은 경우에는 결과 수가 정확한 값이 아닌 추정치로 반환될 수 있습니다.

  • 따옴표로 묶인 구문에 검색어가 3개 이상인 경우(예: '결과 수 정확')

  • 평가할 고유 검색 결과 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),
  "interpretedQueryActualResultCount": integer,
  "interpretedQueryEstimatedResultCount": string
}
필드
interpretedQuery

string

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

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

질문의 해석 이유입니다. 해석 유형이 NONE이 아닌 경우 이 필드는 UNSPECIFIED가 아닙니다.
interpretedQueryActualResultCount

integer

해석된 쿼리에서 반환된 실제 결과 수입니다.
interpretedQueryEstimatedResultCount

string (int64 format)

해석된 쿼리에서 반환된 예상 결과 수입니다.

QueryInterpretation.InterpretationType

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

QueryInterpretation.Reason

열거형
UNSPECIFIED
QUERY_HAS_NATURAL_LANGUAGE_INTENT 자연어 해석이 검색 결과를 가져오는 데 사용됩니다.
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY 사용자 쿼리에 대한 결과가 충분히 발견되지 않았으므로 쿼리 및 문서 용어 유사성을 사용하여 추가 검색 결과를 검색하기 위해 쿼리를 선택적으로 확대합니다. 이 경우 해석된 질문은 비어 있습니다.

SearchResult

문서의 색인 정보를 포함하는 결과입니다. 다음 ID: 16

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)

소스가 클러스터링된 경우 클러스터링된 결과 목록을 제공합니다. 클러스터링된 결과는 한 수준만 표시됩니다. 현재 소스에서 클러스터링이 사용 설정되지 않은 경우 이 필드는 비어 있습니다.
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)

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

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
updateTime

string (Timestamp format)

검색 결과에 있는 객체의 마지막 수정 날짜입니다. 상품에 설정되지 않은 경우 여기에서 반환되는 값은 비어 있습니다. updateTime이 업데이트 빈도를 계산하는 데 사용되고 설정되지 않은 경우 이 값은 현재 시간으로부터 2년으로 기본 설정됩니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
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 표현 
{

  // Union field structured_result can be only one of the following:
  "person": {
    object (Person)
  }
  // End of list of possible types for union field structured_result.
}
필드

통합 필드 structured_result.

structured_result는 다음 중 하나여야 합니다.
person

object (Person)

사람의 표현

SpellResult

JSON 표현 
{
  "suggestedQuery": string,
  "suggestionType": enum (SpellResult.SuggestionType),
  "suggestedQueryHtml": {
    object (SafeHtmlProto)
  }
}
필드
suggestedQuery

string

질문의 추천 맞춤법입니다.
suggestionType

enum (SpellResult.SuggestionType)

현재 쿼리에 대해 트리거된 추천입니다.
suggestedQueryHtml

object (SafeHtmlProto)

맞춤법이 수정된 질문을 나타내며 UI에서 사용할 수 있는 정리된 HTML입니다. 여기에는 일반적으로 맞춤법 검사를 거친 쿼리 부분을 표시하는 언어별 태그가 있습니다.

SpellResult.SuggestionType

질문에 대해 트리거된 추천 유형입니다.

열거형
SUGGESTION_TYPE_UNSPECIFIED 기본 맞춤법 검사 유형
NON_EMPTY_RESULTS_SPELL_SUGGESTION 결과가 변경되지 않은 맞춤법 제안 결과가 있는 맞춤법 제안과 함께 결과가 0이 아닌 원래 검색어의 결과가 계속 표시됩니다.
ZERO_RESULTS_FULL_PAGE_REPLACEMENT 원래 쿼리에 결과가 없는 경우 맞춤법 제안이 트리거됩니다. 원래 쿼리에 결과가 없고 맞춤법 제안에 결과가 있는 경우 맞춤법이 수정된 쿼리의 결과가 트리거됩니다.

SafeHtmlProto

중요: 공격자가 유형의 안전 계약을 충족하지 않는 직렬화된 메시지를 위조하는 것은 사소한 일이므로 신뢰할 수 없는 소스의 이 메시지를 수락하는 것은 안전하지 않습니다. 예를 들어 공격자가 제어하는 스크립트가 포함될 수 있습니다. SafeHtmlProto를 수신하는 시스템은 SafeHtmlProto의 생산자를 암시적으로 신뢰합니다. 따라서 RPC 응답에서 이 메시지를 반환하는 것은 일반적으로 안전하지만 RPC 요청에서 이를 수락하는 것은 일반적으로 안전하지 않습니다.

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

string

중요: 테스트에서라도 이 필드를 설정하거나 읽지 마세요. 비공개입니다. 이 메시지를 만들거나 읽을 프로그래밍 언어 패키지에 관한 내용은 .proto 파일 상단의 문서를 참고하세요.

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)
  },

  // Union field bucket_value can be only one of the following:
  "value": {
    object (Value)
  }
  // End of list of possible types for union field bucket_value.
}
필드
count

integer

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

integer

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

object (Filter)

해당 버킷이 선택된 경우 검색 요청에 전달할 필터입니다.
통합 필드 bucket_value. 패싯 처리된 bucket_value 버킷의 범위 또는 값은 다음 중 하나일 수 있습니다.
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)

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