문서 검색(Azure AI Search REST API)

아티클
11/13/2023

쿼리 요청은 검색 서비스에서 단일 인덱스의 문서 컬렉션을 대상으로 합니다. 여기에는 일치 조건을 정의하는 매개 변수와 응답을 형성하는 매개 변수가 포함됩니다. 2021-04-30-Preview API 버전부터 인덱스 이름 자체를 사용하는 대신 인덱스 별칭 을 사용하여 특정 인덱스를 대상으로 지정할 수도 있습니다.

GET 또는 POST를 사용할 수 있습니다. 쿼리 매개 변수 는 GET 요청에 대한 쿼리 문자열 및 POST 요청에 대한 요청 본문에 지정됩니다.

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

POST를 사용하는 경우 "검색" 작업을 URI 매개 변수로 추가합니다.

POST https://[service name].search.windows.net/indexes/[index name]/docs/search?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	필수 사항입니다. 명명된 인덱스의 문서 컬렉션을 지정합니다.
[쿼리 매개 변수]	쿼리 매개 변수는 GET 요청의 URI 및 POST 요청에 대한 요청 본문에 지정됩니다.
api-version	필수 사항입니다. 현재 안정적인 버전은 입니다 `api-version=2020-06-30`. 더 많은 버전은 API 버전을 참조하세요. 쿼리의 경우 api-version은 항상 GET 및 POST 모두에 대한 URI 매개 변수로 지정됩니다.

URL 인코딩 권장 사항

GET REST API를 직접 호출할 때 특정 쿼리 매개 변수를 URL로 인코딩 해야 합니다. 문서 검색 작업의 경우 다음 쿼리 매개 변수에 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의 경우:

{  
     "count": true | false (default),  
     "facets": [ "facet_expression_1", "facet_expression_2", ... ],  
     "filter": "odata_filter_expression",  
     "highlight": "highlight_field_1, highlight_field_2, ...",  
     "highlightPreTag": "pre_tag",  
     "highlightPostTag": "post_tag",  
     "minimumCoverage": # (% of index that must be covered to declare query successful; default 100),  
     "orderby": "orderby_expression",  
     "queryType": "simple" (default) | "full",
     "scoringParameters": [ "scoring_parameter_1", "scoring_parameter_2", ... ],  
     "scoringProfile": "scoring_profile_name",  
     "scoringStatistics" : "local" | "global",
     "search": "simple_query_expression",  
     "searchFields": "field_name_1, field_name_2, ...",  
     "searchMode": "any" (default) | "all",  
     "select": "field_name_1, field_name_2, ...",  
     "sessionId" : "session_id",
     "skip": # (default 0),  
     "top": #  
   }

부분 검색 응답의 연속 작업

Azure AI Search가 요청된 모든 결과를 단일 검색 응답으로 반환할 수 없는 경우가 있습니다. 이러한 현상이 발생하는 여러 이유가 있는데, $top을 지정하지 않거나 $top에 너무 큰 값을 지정하여 쿼리에서 너무 많은 문서를 요청하는 경우를 예로 들 수 있습니다. 이러한 경우 Azure AI Search는 응답 본문에 주석을 @search.nextPageParameters 포함하고 POST 요청인 경우에도 포함 @odata.nextLink 됩니다. 이러한 주석의 값을 사용하여 검색 응답의 다음 부분을 가져오는 또 다른 검색 요청을 작성할 수 있습니다. 이것을 원래 검색 요청의 연속 작업이라고 부르며, 주석은 일반적으로 연속 토큰이라고 합니다. 이러한 주석의 구문과 응답 본문에 표시되는 위치에 대한 자세한 내용은 아래 응답 예제를 참조하세요.

Azure AI Search가 연속 토큰을 반환할 수 있는 이유는 구현에 따라 달라지고 변경될 수 있습니다. 견고한 클라이언트라면 예상보다 적은 문서가 반환되고 문서 검색을 계속할 수 있도록 연속 토큰이 포함되는 상황을 언제든지 처리할 수 있어야 합니다. 또한 검색을 계속하려면 원래 요청과 동일한 HTTP 메서드를 사용해야 합니다. 예를 들어 GET 요청을 보냈으면 보내는 모든 연속 작업 요청에서도 GET을 사용해야 합니다(POST도 마찬가지).

참고

및 @search.nextPageParameters 의 목적은 @odata.nextLink 페이징에 대한 일반적인 메커니즘을 제공하지 않고 너무 많은 결과를 요청하는 쿼리로부터 서비스를 보호하는 것입니다. 결과를 페이지스하려면 및 를 $skip 함께 사용합니다$top. 예를 들어 크기가 10인 페이지를 원하는 경우 첫 번째 요청에는 및 가 있어야 $top=10 하고, 두 번째 요청에는 $top=10 및 가 있어야 하며$skip=10, 세 번째 요청에는 $top=10 및 $skip=20등이 있어야 $skip=0합니다.

쿼리 매개 변수

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

Name	형식	Description
api-version	문자열	필수 사항입니다. 요청에 사용되는 REST API의 버전입니다. 지원되는 버전 목록은 API 버전을 참조하세요. 이 작업의 경우 api-version은 GET 또는 POST를 사용하여 문서 검색 을 호출하는지 여부에 관계없이 URI 매개 변수로 지정됩니다.
`$count`	boolean	선택 사항입니다. 유효한 값은 “true” 또는 “false”입니다. 기본값은 "false"입니다. POST를 사용하여 호출할 때 이 매개 변수의 이름은 대신 count입니다 `$count`. 총 결과 수를 가져올지 여부를 지정합니다. 및 를 무시하고 `$top` 검색 및 $filter 매개 변수와 일치하는 모든 문서의 수입니다 `$skip`. 이 값을 "true"로 설정하면 성능이 저하 될 수 있습니다. 인덱스가 안정적인 경우 개수는 정확하지만 적극적으로 추가, 업데이트 또는 삭제된 문서를 초과 보고합니다. 문서 없이 개수만 얻으려면 =0을 사용할 `$top`수 있습니다.
패싯 또는 패싯	문자열	(선택 사항) 패싯할 필드입니다. 여기서 필드는 "패싯 가능"으로 특성이 지정됩니다. GET을 사용하여 호출되는 `facet` 경우 은 필드(`facet: field1`)입니다. POST를 사용하여 호출하면 이 매개 변수의 이름이 대신 `facet` 지정 `facets` 되고 배열(`facets: [field1, field2, field3]`)로 지정됩니다. 문자열에는 쉼표로 구분된 이름-값 쌍으로 표현되는 패싯을 사용자 지정하는 매개 변수가 포함될 수 있습니다. 유효한 매개 변수는 "count", "sort", "values", "interval" 및 "timeoffset"입니다. "count"는 패싯 용어의 최대 수입니다. 기본값은 10입니다. 용어 수에 대한 상한은 없지만 값이 높을수록 성능이 저하됩니다. 특히 패싯 필드에 고유한 용어가 많은 경우 성능이 저하됩니다. 예를 들어 "facet=category,count:5"는 패싯 결과에서 상위 5개 범주를 가져옵니다. count 매개 변수가 고유 용어 수보다 작으면 결과가 정확하지 않을 수 있습니다. 이는 패싯 쿼리가 분할된 데이터베이스에서 분산된 방식 때문입니다. 개수를 0으로 설정하거나 패싯 가능 필드의 고유 값 수보다 크거나 같은 값으로 설정하여 모든 분할된 데이터베이스에서 정확한 개수를 가져올 수 있습니다. 절충은 대기 시간이 증가합니다. "sort"는 "count", "-count", "value", "-value"로 설정할 수 있습니다. 개수를 사용하여 내림차순으로 정렬합니다. -count를 사용하여 오름차순으로 정렬합니다. 값을 사용하여 값별로 오름차순을 정렬합니다. -value를 사용하여 값으로 내림차순을 정렬합니다(예: "facet=category,count:3,sort:count"는 패싯의 상위 3개 범주를 가져오고 각 도시 이름을 가진 문서 수만큼 내림차순으로 정렬됩니다). 상위 3개 범주가 예산, 모텔, 럭셔리, 예산이 5개, 모텔이 6개, 럭셔리가 4개인 경우 버킷은 모텔, 버짓, 럭셔리 순으로 정렬됩니다. -value의 경우 "facet=rating,sort:-value"는 가능한 모든 등급에 대한 버킷을 값별로 내림차순으로 생성합니다(예: 등급이 1에서 5까지인 경우 버킷은 각 등급과 일치하는 문서 수에 관계없이 5, 4, 3, 2, 1로 정렬됨). "values"는 패싯 항목 값의 동적 집합을 지정하는 파이프로 구분된 숫자 또는 Edm.DateTimeOffset 값으로 설정할 수 있습니다(예: "facet=baseRate,values:10 \| 20"은 3개의 버킷을 생성합니다. 하나는 기본 속도 0에서 10까지, 하나는 최대 10개, 20개는 포함하지 않음, 하나는 20개 이상)입니다. 문자열 "facet=lastRenovationDate,values:2010-02-01T00:00:00Z"는 2010년 2월 이전에 개조된 호텔용 버킷과 2010년 2월 1일 이상 개조된 호텔용 버킷 등 두 개의 버킷을 생성합니다. 예상 결과를 얻으려면 값을 순차적으로 오름차순으로 나열해야 합니다. "interval"은 숫자 또는 분, 시간, 일, 주, 월, 분기, 날짜 시간 값의 경우 0보다 큰 정수 간격입니다. 예를 들어 "facet=baseRate,interval:100"은 크기 100의 기본 속도 범위를 기반으로 버킷을 생성합니다. 기본 요금이 모두 $60에서 $600 사이인 경우 0-100, 100-200, 200-300, 300-400, 400-500 및 500-600에 대한 버킷이 있습니다. "facet=lastRenovationDate,interval:year" 문자열은 호텔을 개조할 때 매년 하나의 버킷을 생성합니다. "timeoffset"을 ([+-]hh:mm, [+-]hhmm 또는 [+-]hh)로 설정할 수 있습니다. 사용하는 경우 timeoffset 매개 변수를 interval 옵션과 결합해야 하며 Edm.DateTimeOffset 형식의 필드에 적용된 경우에만 사용해야 합니다. 이 값은 설정 시간 경계에서 고려할 UTC 시간 오프셋을 지정합니다. 예: "facet=lastRenovationDate,interval:day,timeoffset:-01:00"은 01:00:00 UTC(대상 표준 시간대의 자정)에 시작하는 일 경계를 사용합니다. count 및 sort는 동일한 패싯 사양에서 결합할 수 있지만 간격 또는 값과 결합할 수 없으며 간격과 값을 함께 결합할 수 없습니다. 시간 제한 집합이 지정되지 않은 경우 날짜 시간의 간격 패싯은 UTC 시간을 기준으로 계산됩니다. 예: "facet=lastRenovationDate,interval:day"의 경우 일 경계는 00:00:00 UTC에서 시작됩니다.
$filter	문자열	(선택 사항) 표준 OData 구문의 구조적인 검색 식입니다. 필터에 필터링 가능한 필드만 사용할 수 있습니다. POST를 사용하여 를 호출할 때 이 매개 변수는 $filter 대신 필터로 명명됩니다. Azure AI Search에서 지원하는 OData 식 문법의 하위 집합에 대한 자세한 내용은 Azure AI Search용 OData 식 구문을 참조하세요.
highlight	문자열	(선택 사항) 적중 항목 강조 표시에 사용되는 쉼표로 구분된 필드 이름 집합입니다. 검색 가능한 필드만 적중 항목 강조 표시에 사용할 수 있습니다. 기본적으로 Azure AI Search는 필드당 최대 5개의 강조 표시를 반환합니다. 필드 이름 다음에 "-<max # of highlights"를 추가하여 필드당 제한을 구성할 수 있습니다>. 예를 들어 "highlight=title-3,description-10"은 제목 필드에서 최대 3개의 강조 표시된 적중과 설명 필드에서 최대 10개의 적중을 반환합니다. 최대 강조 표시 수는 1에서 1000 사이의 정수여야 합니다.
highlightPostTag	문자열	선택 사항입니다. 기본값은 `"</em>"`입니다. 강조 표시된 용어에 추가되는 문자열 태그입니다. highlightPreTag를 사용하여 설정해야 합니다. URL의 예약된 문자는 %로 인코딩해야 합니다. 예를 들어 # 대신 %23을 사용해야 합니다.
highlightPreTag	문자열	선택 사항입니다. 기본값은 `"</em>"`입니다. 강조 표시된 용어 앞에 추가되는 문자열 태그입니다. highlightPostTag를 사용하여 설정해야 합니다. URL의 예약된 문자는 %로 인코딩해야 합니다. 예를 들어 # 대신 %23을 사용해야 합니다.
minimumCoverage	integer	선택 사항입니다. 유효한 값은 0에서 100 사이의 숫자로, 쿼리가 성공으로 보고되기 전에 쿼리를 서비스하는 데 사용할 수 있어야 하는 인덱스의 백분율을 나타냅니다. 기본값은 "100"입니다. 100% 적용 범위는 모든 분할된 데이터베이스가 요청에 응답했음을 의미합니다(서비스 상태 문제나 유지 관리 활동은 적용 범위를 줄이지 않음). 기본 설정에서 전체 검사 미만은 HTTP 상태 코드 503을 반환합니다. minimumCoverage를 낮추면 503 오류가 발생하고 쿼리 성공 확률을 높이려는 경우에 유용할 수 있습니다. 특히 한 복제본(replica) 구성된 서비스의 경우 더욱 그렇습니다. minimumCoverage 및 Search가 성공하도록 설정하면 HTTP 200을 반환하고 쿼리에 포함된 인덱스의 백분율을 나타내는 값을 응답에 포함합니다 @search.coverage . 이 시나리오에서 일치하는 모든 문서가 검색 결과에 표시되도록 보장되는 것은 아니지만 검색 가용성이 회수보다 더 중요한 경우 적용 범위를 줄이는 것이 실행 가능한 완화 전략이 될 수 있습니다.
$orderby	문자열	(선택 사항) 결과 정렬 기준으로 사용할 쉼표로 구분된 식 목록입니다. POST를 사용하여 호출할 때 이 매개 변수의 이름은 $orderby 대신 orderby로 지정됩니다. 각 식은 필드 이름 또는 geo.distance() 함수에 대한 호출일 수 있습니다. 각 식 뒤에 오름차순을 나타내는 "asc"와 내림차순을 나타내는 "desc"가 뒤따를 수 있습니다. 정렬 필드에 null 값이 있는 경우 null은 먼저 오름차순으로 표시되고 마지막은 내림차순으로 표시됩니다. 기본값은 오름차순입니다. 동률은 문서의 일치 점수로 구분됩니다. $orderby 지정하지 않으면 기본 정렬 순서가 문서 일치 점수별로 내림차순입니다. $orderby 대한 절은 32개로 제한됩니다.
queryType	문자열	(선택 사항) 유효한 값은 "simple" 또는 "full"입니다. 기본값은 “simple”입니다. "simple"은 , `*` 및 `""`와 같은 `+`기호를 허용하는 간단한 쿼리 구문을 사용하여 쿼리 문자열을 해석합니다. 쿼리는 기본적으로 각 문서의 모든 검색 가능한 필드(또는 searchFields에 표시된 필드)에서 평가됩니다. "full"은 필드별 및 가중치 검색을 허용하는 전체 Lucene 쿼리 구문을 사용하여 쿼리 문자열을 해석합니다. Lucene 쿼리 언어의 범위 검색은 유사한 기능을 제공하는 $filter 위해 지원되지 않습니다.
scoringParameter	문자열	(선택 사항) "name-value1,value2,..." 형식을 사용하여 점수 매기기 함수(예: referencePointParameter)에 정의된 각 매개 변수의 값을 나타냅니다. POST를 사용하여 호출할 때 이 매개 변수의 이름은 scoringParameter 대신 scoringParameters로 지정됩니다. 또한 각 문자열이 별도의 이름-값 쌍인 문자열의 JSON 배열로 지정합니다. 함수를 포함하는 점수 매기기 프로필의 경우 함수를 입력 목록에서 문자로 `-` 구분합니다. 예를 들어 라는 `"mylocation"` 함수는 "&scoringParameter=mylocation--122.2,44.8"입니다. 첫 번째 대시는 함수 이름을 값 목록과 구분하고 두 번째 대시는 첫 번째 값(이 예제의 경도)의 일부입니다. 쉼표를 포함할 수 있는 태그 상승과 같은 점수 매기기 매개 변수의 경우 작은따옴표를 사용하여 목록에서 이러한 값을 이스케이프할 수 있습니다. 값 자체가 작은따옴표를 포함하는 경우 두 배로 높여 이스케이프할 수 있습니다. 태그 부스팅 매개 변수가 호출 `"mytag"` 되어 있고 태그 값 "Hello, O'Brien" 및 "Smith"를 강화하려는 경우 쿼리 문자열 옵션은 "&scoringParameter=mytag-'Hello, O'Brien',Smith"가 됩니다. 따옴표는 쉼표를 포함하는 값에만 필요합니다.
scoringProfile	문자열	(선택 사항) 결과를 정렬하기 위해 일치하는 문서의 일치 점수를 계산하는 점수 매기기 프로필의 이름입니다.
scoringStatistics	문자열	(선택 사항) 유효한 값은 "local" 또는 "global"입니다. 기본값은 "local"입니다. 더 일관된 채점을 위해 전역적으로(모든 분할된 데이터베이스에서) 문서 빈도와 같은 점수 매기기 통계를 계산할지 또는 대기 시간을 낮추기 위해 로컬(현재 분할된 데이터베이스)을 계산할지 여부를 지정합니다. Azure AI Search의 점수 매기기 통계를 참조하세요. 점수 매기기 통계는 유사 항목 검색('~')을 사용하는 용어에 대해 항상 로컬로 계산됩니다.
search	문자열	(선택 사항) 검색할 텍스트입니다. searchFields를 지정하지 않으면 검색 가능한 모든 필드는 기본적으로 검색됩니다. 인덱스에서 검색 가능한 필드의 텍스트는 토큰화되므로 여러 용어를 공백으로 구분할 수 있습니다(예: 'search=hello world'). 모든 용어를 일치시키려면 `` 를 사용합니다(부울 필터 쿼리에 유용할 수 있음). 이 매개 변수를 생략하는 것은 ``로 설정하는 것과 같습니다. 검색 구문에 대한 세부 사항은 단순 쿼리 구문 을 참조하세요. 검색 가능한 필드를 쿼리할 때 결과가 놀랄 수 있습니다. 토큰나이저에는 아포스트로피, 숫자의 쉼표 등 영어 텍스트에서 일반적으로 사용되는 기호의 사례를 처리하는 논리가 포함되어 있습니다. 예를 들어 'search=123,456'은 쉼표가 영어로 많은 수의 천 구분 기호로 사용되므로 개별 용어 '123'과 '456'이 아닌 단일 용어 '123,456'과 일치합니다. 따라서 문장 부호 대신 공백을 사용하여 검색 매개 변수에서 용어를 구분하는 것이 좋습니다.
searchMode	문자열	(선택 사항) 유효한 값은 "any" 또는 "all" 기본값이 "any"입니다. 문서를 일치 항목으로 계산하기 위해 일치해야 하는 항목(모든 검색 용어 또는 검색 용어 중 하나)을 지정합니다.
searchFields	문자열	(선택 사항) 지정된 텍스트를 검색하기 위한 쉼표로 구분된 필드 이름 목록입니다. 대상 필드는 인덱스 스키마에서 검색 가능한 것으로 표시되어야 합니다.
$select	문자열	(선택 사항) 결과 집합에 포함할 쉼표로 구분된 필드 목록입니다. 검색 가능으로 표시된 필드만 이 절에 포함할 수 있습니다. 지정하지 않거나 `*`로 지정하면 스키마에서 검색 가능으로 표시된 모든 필드가 프로젝션에 포함됩니다. POST를 사용하여 호출하면 이 매개 변수의 이름은 $select 대신 select로 지정됩니다.
sessionID	문자열	(선택 사항) sessionId를 사용하면 여러 복제본이 있는 검색 서비스의 관련성 점수 일관성을 개선하는 데 도움이 됩니다. 다중 복제본(replica) 구성에서는 동일한 쿼리에 대한 개별 문서의 관련성 점수 간에 약간의 차이가 있을 수 있습니다. 세션 ID가 제공되면 서비스는 지정된 요청을 해당 세션의 동일한 복제본(replica) 라우팅하기 위해 최선을 다합니다. 동일한 세션 ID 값을 반복적으로 다시 사용하면 복제본 간에 요청의 부하 분산을 방해하고 검색 서비스의 성능에 부정적인 영향을 줄 수 있습니다. sessionId로 사용되는 값은 '_' 문자로 시작할 수 없습니다. 서비스에 복제본이 없는 경우 이 매개 변수는 성능 또는 점수 일관성에 영향을 주지 않습니다.
$skip	integer	선택 사항입니다. 건너뛸 검색 결과의 수입니다. POST를 사용하여 호출하면 이 매개 변수의 이름은 대신 skip으로 `$skip`지정됩니다. 이 값은 100,000보다 클 수 없습니다. 순서대로 문서를 검사해야 하지만 이 제한으로 인해 사용할 `$skip` 수 없는 경우 인덱스의 모든 문서(예: 문서 키)에 고유한 값이 있는 필드에 $orderby 사용하고 범위 쿼리를 사용하여 $filter 것이 좋습니다.
$top	integer	선택 사항입니다. 검색할 검색 결과의 수입니다. 기본값은 50입니다. POST를 사용하여 호출하면 이 매개 변수의 `$top`이름이 대신 top으로 지정됩니다. 1000보다 큰 값을 지정하고 1000개 이상의 결과가 있는 경우 결과의 다음 페이지에 대한 링크와 함께 처음 1000개 결과만 반환됩니다(아래 예제 참조 @odata.nextLink ). Azure AI Search는 서버 쪽 페이징 을 사용하여 쿼리가 한 번에 너무 많은 문서를 검색하지 못하도록 합니다. 기본 페이지 크기는 50이고 최대 페이지 크기는 1000입니다. 즉, 을 지정`$top`하지 않으면 기본적으로 검색 문서는 최대 50개 결과를 반환합니다. 결과가 50개 이상인 경우 응답에는 최대 50개의 결과의 다음 페이지를 검색하는 정보가 포함됩니다(아래 예제 에서 "@odata.nextLink" 및 "@search.nextPageParameters" 참조). 마찬가지로 에 대해 `$top` 1000보다 큰 값을 지정하고 1000개 이상의 결과가 있는 경우 처음 1000개 결과만 반환되고 최대 1,000개 결과의 다음 페이지를 검색하는 정보가 반환됩니다.

응답

상태 코드: 응답에 성공하면 ‘200 OK’가 반환됩니다.

  {
    "@odata.count": # (if `$count`=true was provided in the query),
    "@search.coverage": # (if minimumCoverage was provided in the query),
    "@search.facets": { (if faceting was specified in the query)
      "facet_field": [
        {
          "value": facet_entry_value (for non-range facets),
          "from": facet_entry_value (for range facets),
          "to": facet_entry_value (for range facets),
          "count": number_of_documents
        }
      ],
      ...
    },
    "@search.nextPageParameters": { (request body to fetch the next page of results if not all results could be returned in this response and Search was called with POST)
      "count": ... (value from request body if present),
      "facets": ... (value from request body if present),
      "filter": ... (value from request body if present),
      "highlight": ... (value from request body if present),
      "highlightPreTag": ... (value from request body if present),
      "highlightPostTag": ... (value from request body if present),
      "minimumCoverage": ... (value from request body if present),
      "orderby": ... (value from request body if present),
      "scoringParameters": ... (value from request body if present),
      "scoringProfile": ... (value from request body if present),
      "scoringStatistics": ... (value from request body if present),
      "search": ... (value from request body if present),
      "searchFields": ... (value from request body if present),
      "searchMode": ... (value from request body if present),
      "select": ... (value from request body if present),
      "sessionId" : ... (value from request body if present),
      "skip": ... (page size plus value from request body if present),
      "top": ... (value from request body if present minus page size),
    },
    "value": [
      {
        "@search.score": document_score (if a text query was provided),
        "@search.highlights": {
          field_name: [ subset of text, ... ],
          ...
        },
        "@search.features": {
          "field_name": {
            "uniqueTokenMatches": feature_score,
            "similarityScore": feature_score,
            "termFrequency": feature_score,
          },
          ...
        },
        key_field_name: document_key,
        field_name: field_value (retrievable fields or specified projection),
        ...
      },
      ...
    ],
    "@odata.nextLink": (URL to fetch the next page of results if not all results could be returned in this response; Applies to both GET and POST)
  }

예제

Azure AI Search용 OData 식 구문에서 더 많은 예제를 찾을 수 있습니다.

날짜 기준 내림차순으로 정렬된 인덱스 검색:

GET /indexes/hotels/docs?search=*&$orderby=LastRenovationDate desc&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "orderby": "LastRenovationDate desc"
    }

패싯 검색에서 인덱스를 검색하고 특정 범위에서 baseRate가 있는 범주, 등급, 태그 및 항목에 대한 패싯을 검색합니다.
```
GET /indexes/hotels/docs?search=*&facet=Category&facet=Rating&facet=Tags&facet=Rooms/BaseRate,values:80|150|220&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "Category", "Rating", "Tags", "Rooms/BaseRate,values:80|150|220" ]  
    }  
```
마지막 패싯이 하위 필드에 있습니다. 패싯은 중간 하위 문서(객실)가 아닌 부모 문서(호텔)를 계산하므로 응답은 각 가격 버킷에 객실이 있는 호텔 수를 결정합니다.

필터를 사용하여 사용자가 등급 3 및 범주 "Motel"을 선택한 후 이전 패싯 쿼리 결과를 좁힐 수 있습니다.

GET /indexes/hotels/docs?search=*&facet=tags&facet=Rooms/BaseRate,values:80|150|220&$filter=Rating eq 3 and Category eq 'Motel'&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "tags", "Rooms/BaseRate,values:80|150|220" ],  
      "filter": "Rating eq 3 and Category eq 'Motel'"  
    }

패싯 검색에서 쿼리에 반환되는 고유 항목의 상한을 설정합니다. 기본값은 10이지만 패싯 특성에 대해 count 매개 변수를 사용하여 이 값을 늘리거나 줄일 수 있습니다. 이 예제에서는 city에 대한 패싯(5개로 제한됨)을 반환합니다.
```
GET /indexes/hotels/docs?search=*&facet=Address/City,count:5&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "Address/City,count:5" ]  
    }  
```

언어 필드 등의 특정 필드 내 인덱스 검색

GET /indexes/hotels/docs?search=hôtel&searchFields=Description_fr&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hôtel",  
      "searchFields": "Description_fr"
    }

여러 필드에서 인덱스를 검색합니다. 예를 들어 모두 동일한 인덱스 내에서 여러 언어로 된 검색 가능 필드를 저장하고 쿼리할 수 있습니다. 영어 및 프랑스어 설명이 동일한 문서에 공존하는 경우 쿼리 결과에서 또는 모두를 반환할 수 있습니다.
```
GET /indexes/hotels/docs?search=hotel&searchFields=Description,Description_fr&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hotel",  
      "searchFields": "Description, Description_fr"
    }  
```
한 번에 인덱스만 쿼리할 수 있습니다. 한 번에 하나씩 쿼리하지 않는 한 각 언어에 대해 여러 인덱스를 만들지 마세요.

페이징 - 항목의 첫 번째 페이지를 가져옵니다(페이지 크기는 10).

GET /indexes/hotels/docs?search=*&$skip=0&$top=10&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "skip": 0,  
      "top": 10  
    }

페이징 - 항목의 두 번째 페이지 가져오기(페이지 크기는 10)입니다.

GET /indexes/hotels/docs?search=*&$skip=10&$top=10&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "skip": 10,  
      "top": 10  
    }

특정 필드 집합을 검색합니다.

GET /indexes/hotels/docs?search=*&$select=HotelName,Description&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "select": "HotelName, Description"
    }

특정 필터 식과 일치하는 문서를 검색합니다.

GET /indexes/hotels/docs?$filter=(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "filter": "(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'"  
    }

인덱스를 검색하여 적중 항목이 강조 표시된 조각 반환

GET /indexes/hotels/docs?search=something&highlight=Description&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "highlight": "Description"  
    }

인덱스를 검색하여 참조 위치에서 가까운 위치부터 순서대로 정렬된 문서 반환

GET /indexes/hotels/docs?search=something&$orderby=geo.distance(Location, geography'POINT(-122.12315 47.88121)')&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "orderby": "geo.distance(Location, geography'POINT(-122.12315 47.88121)')"
    }

두 개의 거리 채점 함수가 있는 "geo"라는 점수 매기기 프로필이 있다고 가정하면 인덱스를 검색합니다. 하나는 "currentLocation"이라는 매개 변수를 정의하고 하나는 "lastLocation"이라는 매개 변수를 정의합니다. 다음 예제에서 "currentLocation"에는 단일 대시(-)의 구분 기호가 있습니다. 그 뒤에 경도 및 위도 좌표가 잇습니다. 여기서 경도는 음수 값입니다.
```
GET /indexes/hotels/docs?search=something&scoringProfile=geo&scoringParameter=currentLocation--122.123,44.77233&scoringParameter=lastLocation--121.499,44.2113&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "scoringProfile": "geo",  
      "scoringParameters": [ "currentLocation--122.123,44.77233", "lastLocation--121.499,44.2113" ]  
    }  
```
단순 쿼리 구문을 사용하여 인덱스에서 문서를 찾습니다. 이 쿼리는 검색 가능한 필드에 "comfort" 및 "location"이라는 용어가 있지만 "motel"이라는 용어가 없는 호텔을 반환합니다.
```
Get /indexes/hotels/docs?search=comfort +location –motel&searchMode=all&api-version=22020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "comfort +location -motel",  
      "searchMode": "all"  
    }  
```
팁

searchMode=all을 사용하면 searchMode=any의 기본값을 재정의하여 -motel이 "OR NOT" 대신 "AND NOT"을 의미하도록 합니다. searchMode=all을 사용하지 않으면 검색 결과를 제한하는 것이 아니라 확장하는 "OR NOT"을 가져오므로 일부 사용자에게 직관적으로 보이지 않을 수 있습니다.
Lucene 쿼리 구문을 사용하여 인덱스에서 문서를 찾습니다.) 이 쿼리는 범주 필드에 “예산"이라는 용어가 포함된 호텔 및 “최근 혁신된" 문구가 포함된 모든 검색 가능 필드를 반환합니다. 용어 boost 값(3)의 결과로 "최근 혁신된" 문구가 포함된 문서가 더 높은 순위가 됩니다.
```
GET /indexes/hotels/docs?search=Category:budget AND \"recently renovated\"^3&searchMode=all&api-version=2020-06-30&querytype=full` 
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
     "search": "Category:budget AND \"recently renovated\"^3",  
      "queryType": "full",  
      "searchMode": "all"  
}  
```
낮은 대기 시간보다 일관된 채점을 선호하면서 인덱스에서 문서를 찾습니다. 이 쿼리는 전체 인덱스에서 문서 빈도를 계산하고 동일한 "세션" 내의 모든 쿼리에 대해 동일한 복제본(replica) 대상으로 지정하여 안정적이고 재현 가능한 순위를 생성하는 데 도움이 됩니다.
```
GET /indexes/hotels/docs?search=hotel&sessionId=mySessionId&scoringStatistics=global&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hotel",  
      "sessionId": "mySessionId",
      "scoringStatistics" :"global"
    }  
```