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개입니다.

응답 본문

성공할 경우 응답 본문에 다음 구조의 데이터가 포함됩니다.

검색 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)

사용자 검색어에 관한 구조화된 결과입니다. 이러한 결과는 페이지 크기에 포함되지 않습니다.

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

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

QueryInterpretation

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

string

검색에 사용된 검색어의 해석입니다. 예를 들어 'email from john'과 같은 자연어 인텐트가 포함된 쿼리는 '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)

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

debugInfo

object (ResultDebugInfo)

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

snippet

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

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)

해당 필터가 있는 결과가 하나 이상 포함된 응답의 값에 대한 FacetBucket입니다.

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)

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