Documents - Autocomplete Post

서비스:: Search Service

API 버전:: 2025-09-01

인덱스의 입력 텍스트 및 일치하는 용어를 기반으로 불완전한 쿼리 용어를 자동 완성합니다.

POST {endpoint}/indexes('{indexName}')/docs/search.post.autocomplete?api-version=2025-09-01

URI 매개 변수

Name	In(다음 안에)	필수	형식	Description
endpoint	path	True	string	검색 서비스의 엔드포인트 URL입니다.
indexName	path	True	string	인덱스의 이름입니다.
api-version	query	True	string	클라이언트 API 버전입니다.

요청 헤더

Name	필수	형식	Description
x-ms-client-request-id		string (uuid)	디버깅을 돕기 위해 요청과 함께 전송된 추적 ID입니다.

요청 본문

Name	필수	형식	Description
search	True	string	자동 완성 결과의 기반이 되는 검색 텍스트입니다.
suggesterName	True	string	인덱스 정의의 일부인 제안자 컬렉션에 지정된 제안자의 이름입니다.
autocompleteMode		AutocompleteMode	자동 완성 모드를 지정합니다. 기본값은 'oneTerm'입니다. 'twoTerms'를 사용하여 대상 포진을 가져오고 'oneTermWithContext'를 사용하여 자동 완성된 용어를 생성하는 동안 현재 컨텍스트를 사용합니다.
filter		string	자동 완성 결과에 대해 완성된 용어를 생성하는 데 사용되는 문서를 필터링하는 OData 식입니다.
fuzzy		boolean	자동 완성 쿼리에 유사 항목 일치를 사용할지 여부를 나타내는 값입니다. 기본값은 false입니다. true로 설정하면 검색 텍스트에 대체되거나 누락된 문자가 있는 경우에도 쿼리가 용어를 자동 완성합니다. 이렇게 하면 일부 시나리오에서 더 나은 환경을 제공하지만 유사 항목 자동 완성 쿼리가 느리고 더 많은 리소스를 소비하므로 성능 비용이 발생합니다.
highlightPostTag		string	적중 강조 표시에 추가되는 문자열 태그입니다. highlightPreTag로 설정해야 합니다. 생략하면 적중 강조 표시가 비활성화됩니다.
highlightPreTag		string	히트 하이라이트 앞에 추가되는 문자열 태그입니다. highlightPostTag로 설정해야 합니다. 생략하면 적중 강조 표시가 비활성화됩니다.
minimumCoverage		number (double)	쿼리가 성공으로 보고되기 위해 자동 완성 쿼리에서 처리해야 하는 인덱스의 백분율을 나타내는 0에서 100 사이의 숫자입니다. 이 매개 변수는 복제본이 하나만 있는 서비스에서도 검색 가용성을 보장하는 데 유용할 수 있습니다. 기본값은 80입니다.
searchFields		string	자동 완성된 용어를 쿼리할 때 고려해야 할 필드 이름의 쉼표로 구분된 목록입니다. 대상 필드는 지정된 제안자에 포함되어야 합니다.
top		integer (int32)	검색할 자동 완성된 용어의 수입니다. 1에서 100 사이의 값이어야 합니다. 기본값은 5입니다.

응답

Name	형식	Description
200 OK	AutocompleteResult	부분 입력을 완료하는 제안된 쿼리 용어가 포함된 응답입니다.
Other Status Codes	ErrorResponse	오류 응답입니다.

예제

SearchIndexAutocompleteDocumentsPost

샘플 요청

HTTP

POST https://stableexampleservice.search.windows.net/indexes('stable-test')/docs/search.post.autocomplete?api-version=2025-09-01


{
  "search": "p",
  "autocompleteMode": "oneTerm",
  "filter": "ownerId ne '1'",
  "fuzzy": true,
  "highlightPostTag": "</em>",
  "highlightPreTag": "<em>",
  "minimumCoverage": 80,
  "searchFields": "category, ownerId",
  "suggesterName": "sg",
  "top": 10
}

샘플 응답

상태 코드:: 200

{
  "@search.coverage": 100,
  "value": [
    {
      "text": "purple",
      "queryPlusText": "<em>purple</em>"
    },
    {
      "text": "pink",
      "queryPlusText": "<em>pink</em>"
    }
  ]
}

정의

Name	Description
AutocompleteItem	자동 완성 요청의 결과입니다.
AutocompleteMode	자동 완성 모드를 지정합니다. 기본값은 'oneTerm'입니다. 'twoTerms'를 사용하여 대상 포진을 가져오고 'oneTermWithContext'를 사용하여 자동 완성 용어를 생성할 때 현재 컨텍스트를 사용합니다.
AutocompleteRequest	유사 항목 일치 및 기타 자동 완성 쿼리 동작에 대한 매개 변수입니다.
AutocompleteResult	자동 완성 쿼리의 결과입니다.
ErrorAdditionalInfo	리소스 관리 오류 추가 정보입니다.
ErrorDetail	오류 세부 정보입니다.
ErrorResponse	오류 응답

AutocompleteItem

Object

자동 완성 요청의 결과입니다.

Name	형식	Description
queryPlusText	string	완료된 용어와 함께 쿼리입니다.
text	string	완료된 기간.

AutocompleteMode

열거형

자동 완성 모드를 지정합니다. 기본값은 'oneTerm'입니다. 'twoTerms'를 사용하여 대상 포진을 가져오고 'oneTermWithContext'를 사용하여 자동 완성 용어를 생성할 때 현재 컨텍스트를 사용합니다.

값	Description
oneTerm	하나의 용어만 제안됩니다. 쿼리에 두 개의 용어가 있는 경우 마지막 용어만 완료됩니다. 예를 들어 입력이 '워싱턴 메딕'인 경우 제안된 용어에는 '메디케이드', '메디케어' 및 '의약품'이 포함될 수 있습니다.
twoTerms	색인에서 일치하는 두 용어 구문이 제안됩니다. 예를 들어 입력이 'medic'인 경우 제안된 용어에는 'medicare 보장' 및 '의료 보조원'이 포함될 수 있습니다.
oneTermWithContext	두 개 이상의 용어가 있는 쿼리의 마지막 용어를 완성하며, 여기서 마지막 두 용어는 인덱스에 있는 구입니다. 예를 들어 입력이 '워싱턴 메딕'인 경우 제안된 용어에는 '워싱턴 메디케이드' 및 '워싱턴 메디컬'이 포함될 수 있습니다.

AutocompleteRequest

Object

유사 항목 일치 및 기타 자동 완성 쿼리 동작에 대한 매개 변수입니다.

Name	형식	Description
autocompleteMode	AutocompleteMode	자동 완성 모드를 지정합니다. 기본값은 'oneTerm'입니다. 'twoTerms'를 사용하여 대상 포진을 가져오고 'oneTermWithContext'를 사용하여 자동 완성된 용어를 생성하는 동안 현재 컨텍스트를 사용합니다.
filter	string	자동 완성 결과에 대해 완성된 용어를 생성하는 데 사용되는 문서를 필터링하는 OData 식입니다.
fuzzy	boolean	자동 완성 쿼리에 유사 항목 일치를 사용할지 여부를 나타내는 값입니다. 기본값은 false입니다. true로 설정하면 검색 텍스트에 대체되거나 누락된 문자가 있는 경우에도 쿼리가 용어를 자동 완성합니다. 이렇게 하면 일부 시나리오에서 더 나은 환경을 제공하지만 유사 항목 자동 완성 쿼리가 느리고 더 많은 리소스를 소비하므로 성능 비용이 발생합니다.
highlightPostTag	string	적중 강조 표시에 추가되는 문자열 태그입니다. highlightPreTag로 설정해야 합니다. 생략하면 적중 강조 표시가 비활성화됩니다.
highlightPreTag	string	히트 하이라이트 앞에 추가되는 문자열 태그입니다. highlightPostTag로 설정해야 합니다. 생략하면 적중 강조 표시가 비활성화됩니다.
minimumCoverage	number (double)	쿼리가 성공으로 보고되기 위해 자동 완성 쿼리에서 처리해야 하는 인덱스의 백분율을 나타내는 0에서 100 사이의 숫자입니다. 이 매개 변수는 복제본이 하나만 있는 서비스에서도 검색 가용성을 보장하는 데 유용할 수 있습니다. 기본값은 80입니다.
search	string	자동 완성 결과의 기반이 되는 검색 텍스트입니다.
searchFields	string	자동 완성된 용어를 쿼리할 때 고려해야 할 필드 이름의 쉼표로 구분된 목록입니다. 대상 필드는 지정된 제안자에 포함되어야 합니다.
suggesterName	string	인덱스 정의의 일부인 제안자 컬렉션에 지정된 제안자의 이름입니다.
top	integer (int32)	검색할 자동 완성된 용어의 수입니다. 1에서 100 사이의 값이어야 합니다. 기본값은 5입니다.

AutocompleteResult

Object

자동 완성 쿼리의 결과입니다.

Name	형식	Description
@search.coverage	number (double)	자동 완성 요청에서 고려한 인덱스의 백분율을 나타내는 값으로, 요청에 minimumCoverage가 지정되지 않은 경우 null입니다.
value	AutocompleteItem[]	반환된 자동 완성 항목 목록입니다.

ErrorAdditionalInfo

Object

리소스 관리 오류 추가 정보입니다.

Name	형식	Description
info	object	추가 정보입니다.
type	string	추가 정보 유형입니다.

ErrorDetail

Object

오류 세부 정보입니다.

Name	형식	Description
additionalInfo	ErrorAdditionalInfo[]	오류 추가 정보입니다.
code	string	오류 코드입니다.
details	ErrorDetail[]	오류 세부 정보입니다.
message	string	오류 메시지입니다.
target	string	오류 대상입니다.

ErrorResponse

Object

오류 응답

Name	형식	Description
error	ErrorDetail	오류 개체입니다.

다음을 통해 공유

Documents - Autocomplete Post

URI 매개 변수

요청 헤더

요청 본문

응답

예제

SearchIndexAutocompleteDocumentsPost

샘플 요청

샘플 응답

정의

AutocompleteItem

AutocompleteMode

AutocompleteRequest

AutocompleteResult

ErrorAdditionalInfo

ErrorDetail

ErrorResponse