제안(Azure AI Search REST API)

아티클
05/10/2023

제안 요청은 제안자 인식 필드에서 일치하는 값을 찾고 일치 항목이 포함된 문서를 반환하는 검색 형식 쿼리입니다. 예를 들어 도시 필드에 제안을 사용하도록 설정하면 "sea"를 입력하면 해당 필드에 대해 "Seattle", "Sea Tac", "Seaside"(모든 실제 도시 이름)가 포함된 문서가 생성됩니다.

응답은 일치하는 문서의 콘텐츠와 문서 키입니다. 보조 쿼리에서 사용되는 완성된 용어 또는 구를 반환하는 Autocomplete와 달리 이 요청은 실제 문서로 확인되는 정보를 반환합니다. 일치하는 용어 또는 구가 문서 간에 동일한 경우 일치하는 콘텐츠가 반복됩니다. 결과의 구조를 개선하려면 필터를 $select 사용하여 더 많은 차별화와 컨텍스트를 제공하는 추가 필드를 반환하는 것이 좋습니다.

서비스 요청에는 HTTPS를 사용해야 합니다. 제안 요청은 GET 또는 POST 메서드를 사용하여 생성할 수 있습니다.

GET https://[service name].search.windows.net/indexes/[index name]/docs/suggest?[query parameters]  
  Content-Type: application/json  
  api-key: [admin or query key]

POST https://[service name].search.windows.net/indexes/[index name]/docs/suggest?api-version=[api-version]  
  Content-Type: application/json  
  api-key: [admin or query key]

문서 검색 요청과 달리 키보드 입력에 제안 호출을 바인딩할 수 있는 반면 검색 호출은 클릭 이벤트에 바인딩될 수 있습니다.

GET을 사용하여 호출하면 요청 URL의 길이가 8KB를 초과할 수 없습니다. 이 길이는 일반적으로 대부분의 애플리케이션에 충분합니다. 그러나 일부 애플리케이션은 특히 OData 필터 식을 사용하는 경우 매우 큰 쿼리를 생성합니다. 이러한 애플리케이션의 경우 HTTP POST는 GET보다 더 큰 필터를 허용하므로 더 나은 선택입니다.

POST를 사용하면 필터의 절 수는 제한되지만 POST의 요청 크기 제한이 약 16MB이므로 원시 필터 문자열의 크기는 제한되지 않습니다. POST 요청 크기 제한이 매우 크긴 하지만 필터 식을 임의로 복잡하게 작성할 수는 없습니다. 필터 복잡성 제한 사항에 대한 자세한 내용은 Azure AI Search용 OData 식 구문을 참조하세요.

URI 매개 변수

매개 변수	Description
[서비스 이름]	필수 사항입니다. 검색 서비스의 고유한 사용자 정의 이름으로 설정합니다.
[인덱스 이름]/docs	필수 사항입니다. 명명된 인덱스의 문서 컬렉션을 지정합니다.
api-version	필수 사항입니다. 현재 안정적인 버전은 입니다 `api-version=2020-06-30`. 더 많은 버전은 API 버전을 참조하세요. 쿼리의 경우 api-version은 항상 GET 및 POST 모두에 대한 URI 매개 변수로 지정됩니다.

URL 인코딩 권장 사항

GET REST API를 직접 호출할 때 특정 쿼리 매개 변수를 URL로 인코딩 해야 합니다. 제안 작업의 경우 다음이 포함됩니다.

search
$filter
highlightPreTag
highlightPostTag

URL 인코딩은 개별 매개 변수에만 권장됩니다. 실수로 ? 뒤에 있는 전체 쿼리 문자열을 URL로 인코딩한 경우 요청이 중단됩니다.

또한 URL 인코딩은 GET을 사용하여 REST API를 직접 호출할 때만 필요합니다. POST를 사용하여 제안을 호출하거나 Azure AI Search .NET 클라이언트 라이브러리 를 사용하는 경우 URL 인코딩이 필요하지 않습니다.

요청 헤더

다음 표에서는 필수 요청 헤더와 선택적 요청 헤더에 대해 설명합니다.

필드 Description

콘텐츠 형식 필수 사항입니다. application/json

api-key Azure 역할을 사용하고 요청에 전달자 토큰이 제공된 경우 선택 사항이며, 그렇지 않으면 키가 필요합니다. api-key는 검색 서비스에 대한 요청을 인증하는 고유한 시스템 생성 문자열입니다. 문서 컬렉션에 대한 쿼리 요청은 관리자 키 또는 쿼리 키를 API 키로 지정할 수 있습니다. 쿼리 키는 문서 컬렉션에 대한 읽기 전용 작업에 사용됩니다. 자세한 내용은 키 인증을 사용하여 Azure AI Search에 연결을 참조하세요.

필드	Description
콘텐츠 형식	필수 사항입니다. `application/json`
api-key	Azure 역할을 사용하고 요청에 전달자 토큰이 제공된 경우 선택 사항이며, 그렇지 않으면 키가 필요합니다. api-key는 검색 서비스에 대한 요청을 인증하는 고유한 시스템 생성 문자열입니다. 문서 컬렉션에 대한 쿼리 요청은 관리자 키 또는 쿼리 키를 API 키로 지정할 수 있습니다. 쿼리 키는 문서 컬렉션에 대한 읽기 전용 작업에 사용됩니다. 자세한 내용은 키 인증을 사용하여 Azure AI Search에 연결을 참조하세요.

요청 본문

GET의 경우: 없음.

POST의 경우:

{  
      "filter": "odata_filter_expression",  
      "fuzzy": true | false (default),  
      "highlightPreTag": "pre_tag",  
      "highlightPostTag": "post_tag",  
      "minimumCoverage": # (% of index that must be covered to declare query successful; default 80),  
      "orderby": "orderby_expression",  
      "search": "partial_search_input",  
      "searchFields": "field_name_1, field_name_2, ...",  
      "select": "field_name_1, field_name_2, ...",  
      "suggesterName": "suggester_name",  
      "top": # (default 5)  
}

쿼리 매개 변수

쿼리는 GET을 사용하여 호출할 때 URL에 대한 여러 매개 변수를 허용하고 POST를 사용하여 호출할 때 요청 본문의 JSON 속성으로 허용합니다. 일부 매개 변수에 대한 구문은 GET 및 POST 간에 약간 다릅니다. 이러한 차이점은 아래와 같이 설명됩니다.

Name	형식	Description
api-version	문자열	필수 사항입니다. 요청에 사용되는 REST API의 버전입니다. 지원되는 버전 목록은 API 버전을 참조하세요. 이 작업의 경우 api-version은 GET 또는 POST를 사용하여 API를 호출하는지 여부에 관계없이 URL에서 쿼리 매개 변수로 지정됩니다.
$filter	문자열	(선택 사항) 제안을 검색할 때 고려할 문자를 필터링하는 식입니다. 필터에 필터링 가능한 필드만 사용할 수 있습니다. 필터 식 "search.ismatch" 및 "search.ismatchscoring*"은 자동 완성 API에서 지원되지 않습니다. POST를 사용하여 호출하면 이 매개 변수는 $filter 대신 필터로 명명됩니다. Azure AI Search에서 지원하는 OData 식 문법의 하위 집합에 대한 자세한 내용은 Azure AI Search용 OData 식 구문을 참조하세요.
유사	boolean	선택 사항입니다. 기본값은 false입니다. true로 설정하면 이 API는 검색 텍스트에 대체되거나 누락된 문자가 있더라도 제안을 찾습니다. 편집 거리는 쿼리 문자열당 1입니다. 쿼리 문자열이 여러 용어인 경우 전체 문자열에 누락, 추가, 대체 또는 변환된 문자가 하나만 있을 수 있습니다. 유사 항목 일치를 사용하도록 설정하는 것은 일부 시나리오에서 더 나은 환경이 될 수 있으며, 유사 항목 제안 검색이 느리고 더 많은 리소스를 사용하므로 성능 비용이 발생합니다.
highlightPostTag	문자열	(선택 사항) 기본값은 빈 문자열입니다. 강조 표시된 용어에 추가되는 문자열 태그입니다. highlightPreTag를 사용하여 설정해야 합니다. URL의 예약된 문자는 %로 인코딩해야 합니다. 예를 들어 # 대신 %23을 사용해야 합니다. GET을 사용하여 호출할 때 URL의 예약 문자는 백분율로 인코딩되어야 합니다(예: #대신 %23).
highlightPreTag	문자열	(선택 사항) 기본값은 빈 문자열입니다. 강조 표시된 용어 앞에 추가되는 문자열 태그입니다. highlightPostTag를 사용하여 설정해야 합니다. GET을 사용하여 호출하는 경우 URL의 예약 문자는 백분율로 인코딩되어야 합니다(예: #대신 %23).
$orderby	문자열	(선택 사항) 결과 정렬 기준으로 사용할 쉼표로 구분된 식 목록입니다. 각 식은 필드 이름이거나 `geo.distance()` 함수 호출일 수 있습니다. 각 식 뒤에 "asc"(오름차순) 또는 "desc"(내림차순)가 올 수 있습니다. 기본값은 오름차순입니다. $orderby 대한 절은 32개로 제한됩니다. POST를 사용하여 호출되는 경우 이 매개 변수의 이름은 $orderby 대신 order로 지정됩니다.
minimumCoverage	integer	선택 사항입니다. 기본값은 80입니다. 쿼리를 성공으로 보고하기 전에 쿼리를 서비스하는 데 사용할 수 있어야 하는 인덱스의 백분율을 나타내는 0에서 100 사이의 숫자입니다. 기본값은 전체 검사에 대한 속도 및 효율성에 대한 편견을 반영합니다. 범위를 줄이면 쿼리 확장이 제한되므로 결과가 더 빨리 돌아올 수 있습니다. 또한 서비스 상태 문제 또는 인덱스 유지 관리로 인해 하나의 분할된 데이터베이스가 응답 속도가 느리거나 사용할 수 없는 경우에도 부분 인덱스 가용성에서 쿼리가 성공할 수 있습니다. minimumCoverage 값에 관계없이 인덱스의 백분율을 사용할 수 있어야 합니다. 그렇지 않으면 제안에서 HTTP 상태 코드 503을 반환합니다. Suggestions가 minimumCoverage 수준에서 성공하면 HTTP 200을 반환하고 쿼리를 서비스할 때 사용할 수 있었던 인덱스의 백분율을 나타내는 값을 응답에 포함합니다 @search.coverage . 503 오류가 발생하는 경우 이 값을 낮추는 것이 도움이 될 수 있습니다. 그렇지 않으면 응답에서 일치하는 항목이 충분하지 않은 경우 값을 높이는 것이 좋습니다.
search	문자열	필수 사항입니다. 쿼리를 제안하는 데 사용할 검색 텍스트입니다. 최소 1자가 되어야 하며 100자를 넘지 않아야 합니다. 연산자, 쿼리 구문 또는 따옴표 붙은 구를 포함할 수 없습니다.
searchFields	문자열	(선택 사항) 지정된 검색 텍스트를 검색하기 위한 쉼표로 구분된 필드 이름 목록입니다. 대상 필드는 인덱 스에서 제안기 정의에 나열되어야 합니다.
$select	문자열	(선택 사항) 검색할 쉼표로 구분된 필드 목록입니다. 지정하지 않으면 문서 키 및 제안 텍스트만 반환됩니다. 이 매개 변수를 `*`로 설정하여 모든 필드를 명시적으로 요청할 수 있습니다. POST를 사용하여 를 호출할 때 이 매개 변수의 이름은 $select 대신 select로 지정됩니다.
suggesterName	문자열	필수 사항입니다. 인덱스 정의의 일부인 Suggesters 컬렉션에 지정된 제안기의 이름입니다. 제안기는 제안된 쿼리 용어를 검사할 필드를 결정합니다.
$top	integer	선택 사항입니다. 기본값은 5)입니다. 검색할 자동 완성 제안 수입니다. 값은 1~100 사이의 숫자여야 합니다. POST를 사용하여 를 호출할 때 이 매개 변수의 이름은 $top 대신 top으로 지정됩니다.

응답

상태 코드: 성공적인 응답을 위해 "200 OK"가 반환됩니다.

{  
  "@search.coverage": # (if minimumCoverage was provided in the query),  
  "value": [  
    {  
      "@search.text": "...",  
      "<key field>": "..."  
    },  
    ...  
  ]  
}

프로젝션 옵션을 사용하여 필드를 검색하는 경우에는 배열의 각 요소에 필드가 포함됩니다.

{  
  "value": [  
    {  
      "@search.text": "...",  
      "<key field>": "..."  
      <other projected data fields>  
    },  
    ...  
  ]  
}

예제

부분 검색 입력이 'lux'인 제안 5개 검색

GET /indexes/hotels/docs/suggest?search=lux&$top=5&suggesterName=sg&api-version=2020-06-30

POST /indexes/hotels/docs/suggest?api-version=2020-06-30 
    {  
      "search": "lux",  
      "top": 5,  
      "suggesterName": "sg"  
    }

제안 작업에 suggesterName 이 필요합니다.