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

  • 검색어의 구문에 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

검색에 사용된 검색어의 해석입니다. 예를 들어 '영희가 보낸 이메일'과 같은 자연어 의도가 포함된 검색어입니다. '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)

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

스니펫

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

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

패싯 생성에 선택된 연산자의 이름입니다. @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)

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