문서 검색(미리 보기 REST API)

  • 아티클

적용 대상: 2023-07-01-Preview, 2021-04-30-Preview, 2020-06-30-Preview

중요

2023-07-01-Preview는 다음을 추가합니다.

  • 벡터 쿼리 요청을 지정하는 "vectors" 쿼리 매개 변수입니다. 각 개체에는 쿼리의 벡터 표현, 결과에 반환할 가장 가까운 인접 항목의 "k" 수 및 쿼리 실행 중에 사용할 벡터 필드가 포함되어야 합니다.

2021-04-30-Preview는 다음을 추가합니다.

  • "semanticConfiguration" 은 특정 필드에 대한 의미 체계 순위 범위를 지원합니다.
  • "captions" 는 의미상 순위가 가장 높은 문서의 주요 구절에서 추출된 구를 반환합니다.

2020-06-30-Preview는 다음을 추가합니다.

  • "queryType=semantic" 은 의미 체계 재전송 및 응답을 지원합니다.
  • 의미 체계 쿼리의 "searchFields"는 캡션 및 답변을 작성하는 데 사용되는 필드의 우선 순위 순서를 설정합니다. 이 방법은 2021-04-30-Preview에서 "semanticConfiguration" 으로 대체되었으며 이제는 사용되지 않습니다.
  • "맞춤법 검사기" 를 사용하면 쿼리 입력 시 맞춤법 수정이 가능합니다.
  • "queryType=semantic" 및 "speller" 모두에 "queryLanguage"가 필요합니다.
  • "featuresMode" 는 검색 점수의 압축을 풀고 필드별 용어 빈도, 필드별 유사성 점수 및 필드별 고유 일치 횟수에 대해 보고합니다.

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

대부분의 쿼리에 GET 또는 POST를 사용할 수 있지만 벡터 쿼리 매개 변수가 URI 내에 맞지 않으므로 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
서비스 이름 필수 사항입니다. 이 이름을 검색 서비스의 고유한 사용자 정의 이름으로 설정합니다.
인덱스 이름/문서 필수 사항입니다. 명명된 인덱스의 문서 컬렉션을 지정합니다. 인덱스 별칭의 이름은 인덱스 이름 대신 사용할 수도 있습니다.
쿼리 매개 변수(query parameter) 쿼리 매개 변수는 GET 요청의 URI 및 POST 요청에 대한 요청 본문에 지정됩니다.
api-version 필수 사항입니다. 현재 버전은 2023-07-01-Preview입니다. 더 많은 버전은 API 버전을 참조하세요.

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에 연결을 참조하세요.

요청 본문

GET의 경우: 없음.

POST의 경우:

{  
     "answers": "none" (default) | "extractive", 
     "count": true | false (default),
     "captions": "none" (default) | "extractive",
     "facets": [ "facet_expression_1", "facet_expression_2", ... ],  
     "featuresMode" : "disabled" (default) | "enabled",
     "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",
     "queryLanguage": "en-us" (default) | (a supported language code), 
     "queryType": "simple" (default) | "full" | "semantic",
     "scoringParameters": [ "scoring_parameter_1", "scoring_parameter_2", ... ],  
     "scoringProfile": "scoring_profile_name",  
     "scoringStatistics" : "local" (default) | "global",
     "search": "simple_query_expression",  
     "searchFields": "field_name_1, field_name_2, ...",  
     "searchMode": "any" (default) | "all",  
     "select": "field_name_1, field_name_2, ...",  
     "semanticConfiguration": "semantic_configuration_name",
     "sessionId" : "session_id",
     "skip": # (default 0), 
     "speller": "none" (default) | "lexicon",  
     "top": #,
     "vectors": [
      {
        "value": "a vector representation of the query",
        "k": an integer (number of nearest neighbors to return as top results),
        "fields": "a comma-delimited list of vector fields to use in the query"
      }
     ]
   }

부분 검색 응답의 연속 작업

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

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

참고

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

쿼리 매개 변수

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

Name 형식 Description
답변(미리 보기) 문자열 (선택 사항) 유효한 값은 "none" 및 "extractive"입니다. 기본값은 "none"입니다. 이 매개 변수는 쿼리 형식이 "의미 체계"인 경우에만 유효합니다. "추출"으로 설정하면 쿼리는 의미상 순위가 가장 높은 문서의 주요 구절에서 답변을 공식화하고 반환합니다. 기본값은 하나의 답변이지만 개수를 추가하여 최대 10개를 지정할 수 있습니다. 예를 들어 "answers": "extractive|count-3"은 세 가지 답변을 반환합니다. 답변이 반환되려면 대상 필드에 답변처럼 보이는 축자 콘텐츠가 있어야 합니다. 답변에 사용되는 언어 모델은 답변을 생성하지 않고 인식하도록 학습됩니다. 또한 쿼리 자체는 질문처럼 보일 수 있습니다.
api-version 문자열 필수 사항입니다. 요청에 사용되는 REST API의 버전입니다. 지원되는 버전 목록은 API 버전을 참조하세요. 이 작업의 경우 api-version은 GET 또는 POST를 사용하여 문서 검색 을 호출하는지 여부에 관계없이 URI 매개 변수로 지정됩니다.
캡션(미리 보기) 문자열 (선택 사항) 유효한 값은 "none" 및 "extractive"입니다. 기본값은 "none"입니다. 이 매개 변수는 쿼리 형식이 "의미 체계"인 경우에만 유효합니다. "추출"으로 설정하면 쿼리는 가장 높은 순위의 문서의 주요 구절에서 추출된 캡션을 반환합니다. 캡션이 '추출'으로 설정된 경우 강조 표시는 기본적으로 사용하도록 설정되며 파이프 문자 '|'와 'highlight-true/false>' 옵션(예: 'extractive|highlight-true<')을 추가하여 구성할 수 있습니다.
$count boolean 선택 사항입니다. 유효한 값은 “true” 또는 “false”입니다. 기본값은 "false"입니다. POST를 사용하여 호출하는 경우 이 매개 변수의 이름은 $count 대신 개수로 지정됩니다. 총 결과 수를 가져올지 여부를 지정합니다. 이 값은 검색 및 $filter 매개 변수와 일치하는 모든 문서의 수이며 $top 및 $skip 무시합니다. 이 값을 "true"로 설정하면 성능이 저하됩니다. 인덱스가 안정적인 경우 개수는 정확하지만 적극적으로 추가, 업데이트 또는 삭제된 모든 문서를 초과 보고합니다. 문서 없이 개수만 얻으려면 $top=0을 사용할 수 있습니다.
패싯 또는 패싯 문자열 (선택 사항) 패싯할 필드입니다. 여기서 필드는 "패싯 가능"으로 특성이 지정됩니다. 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개 이상은 포함하지 않음). 문자열 "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 매개 변수는 간격 옵션과 결합되어야 하며 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에서 시작됩니다.
featuresMode(미리 보기) boolean 선택 사항입니다. 유효한 값은 "enabled" 및 "disabled"입니다. 기본값은 "사용 안 함"입니다. 필드 유사성과 같이 쿼리와 관련하여 문서의 관련성 점수를 계산하는 데 사용되는 쿼리 결과 기능을 결과에 포함할지 여부를 지정하는 값입니다. "enabled"를 사용하여 필드 유사성 점수당, 필드 용어 빈도 및 일치하는 고유 토큰의 필드 수와 같은 더 많은 쿼리 결과 기능을 노출합니다. 자세한 내용은 유사성 및 채점을 참조하세요.
$filter 문자열 (선택 사항) 표준 OData 구문의 구조적인 검색 식입니다. 필터에서 필터링 가능한 필드만 사용할 수 있습니다. POST를 사용하여 호출되는 경우 이 매개 변수의 이름은 $filter 대신 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개로 제한됩니다.
queryLanguage(미리 보기) 문자열 (선택 사항) 유효한 값은 지원되는 언어입니다. 기본값은 "en-us"입니다. speller=lexicon 또는 queryType=semantic을 사용하는 경우 이 매개 변수를 설정해야 합니다. queryLanguage에 지정된 언어는 맞춤법 검사 및 결과를 다시 표시하고 캡션 또는 답변을 추출하는 의미 체계 모델에 사용됩니다. queryLanguage에 사용되는 라이브러리는 인덱싱 및 전체 텍스트 검색에 사용되는 언어 분석기와 같은 다른 로캘 기반 필드 특성과 독립적입니다.
queryType 문자열 (선택 사항) 유효한 값은 "simple", "full" 또는 "semantic"(미리 보기)입니다. 기본값은 “simple”입니다. 이 값은 벡터 검색에 대해 무시되지만 하이브리드 시나리오의 텍스트 검색에 적용됩니다.

"simple"은 , *및 ""와 같은 +기호를 허용하는 간단한 쿼리 구문을 사용하여 쿼리 문자열을 해석합니다. 쿼리는 기본적으로 각 문서의 모든 검색 가능한 필드(또는 searchFields에 표시된 필드)에서 평가됩니다.

"full"은 필드별 및 가중치 검색을 허용하는 전체 Lucene 쿼리 구문을 사용하여 쿼리 문자열을 해석합니다. Lucene 쿼리 언어의 범위 검색은 유사한 기능을 제공하는 $filter 위해 지원되지 않습니다."

의미 체계"는 키워드가 아닌 자연어로 표현된 쿼리에 대해 Bing corpus에서 학습된 순위 모델을 사용하여 상위 50개 일치 항목을 다시 표시하여 검색 결과의 정밀도를 향상시킵니다. 쿼리 유형을 의미 체계로 설정하는 경우 queryLanguage 및 semanticConfiguration도 설정해야 합니다. 쿼리 입력이 자연어("what is a ...)"로 공식화된 경우 상위 3개 답변을 반환하려는 경우 필요에 따라 답변을 설정할 수 있으며, 선택적으로 가장 높은 순위의 문서에서 키 구절을 추출하도록 캡션을 설정할 수 있습니다.
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 문자열 (선택 사항) 검색할 텍스트입니다. 이 값은 벡터 검색에 대해 무시되지만 하이브리드 시나리오의 텍스트 검색에 적용됩니다. REST API에서 searchFields를 지정하지 않으면 검색 가능한 모든 필드가 기본적으로 검색됩니다. 인덱스에서 검색 가능한 필드의 텍스트는 토큰화되므로 여러 용어를 공백으로 구분할 수 있습니다(예: 'search=hello world'). 모든 용어를 일치시키려면 * 를 사용합니다(부울 필터 쿼리에 유용할 수 있음). 이 매개 변수를 생략하는 것은 *로 설정하는 것과 같습니다. 검색 구문에 대한 세부 사항은 단순 쿼리 구문 을 참조하세요.

검색 가능한 필드를 쿼리할 때 결과가 놀랄 수 있습니다. 토큰나이저에는 아포스트로피, 숫자의 쉼표 등 영어 텍스트에서 일반적으로 사용되는 기호의 사례를 처리하는 논리가 포함되어 있습니다. 예를 들어 'search=123,456'은 쉼표가 영어로 많은 수의 천 구분 기호로 사용되므로 개별 용어 '123'과 '456'이 아닌 단일 용어 '123,456'과 일치합니다. 따라서 문장 부호 대신 공백을 사용하여 검색 매개 변수에서 용어를 구분하는 것이 좋습니다.
searchMode 문자열 (선택 사항) 유효한 값은 "any" 또는 "all" 기본값이 "any"입니다. 문서를 일치 항목으로 계산하기 위해 일치해야 하는 항목(모든 검색 용어 또는 검색 용어 중 하나)을 지정합니다.
searchFields 문자열 (선택 사항) 지정된 텍스트를 검색하기 위한 쉼표로 구분된 필드 이름 목록입니다. 대상 필드는 인덱스 스키마에서 검색 가능한 것으로 표시되어야 하며 , Edm.ComplexType또는 Collection(Edm.String)형식Edm.String이어야 합니다.
$select 문자열 (선택 사항) 결과 집합에 포함할 쉼표로 구분된 필드 목록입니다. 검색 가능으로 표시된 필드만 이 절에 포함될 수 있습니다. 지정하지 않거나 *로 지정하면 스키마에서 검색 가능으로 표시된 모든 필드가 프로젝션에 포함됩니다. POST를 사용하여 호출할 때 이 매개 변수의 이름은 $select 대신 select로 지정됩니다.
semanticConfiguration(미리 보기) 문자열 (선택 사항) queryType="semantic"인 경우 필수입니다. 의미 체계 순위, 캡션, 강조 표시 및 답변에 사용해야 하는 필드를 나열하는 의미 체계 구성의 이름입니다. 자세한 내용은 의미 체계 쿼리 만들기를 참조하세요.
sessionID 문자열 (선택 사항) sessionId를 사용하면 여러 복제본이 있는 검색 서비스의 관련성 점수 일관성을 개선하는 데 도움이 됩니다. 다중 복제본(replica) 구성에서는 동일한 쿼리에 대한 개별 문서의 관련성 점수 간에 약간의 차이가 있을 수 있습니다. 세션 ID가 제공되면 서비스는 지정된 요청을 해당 세션의 동일한 복제본(replica) 라우팅하기 위해 최선을 다합니다. 동일한 세션 ID 값을 반복적으로 다시 사용하면 복제본 간에 요청 부하 분산을 방해하고 검색 서비스의 성능에 부정적인 영향을 줄 수 있습니다. sessionId로 사용되는 값은 '_' 문자로 시작할 수 없습니다. 서비스에 복제본이 없는 경우 이 매개 변수는 성능 또는 점수 일관성에 영향을 주지 않습니다.
$skip integer 선택 사항입니다. 건너뛸 검색 결과의 수입니다. POST를 사용하여 호출하면 이 매개 변수의 이름은 $skip 대신 skip으로 지정됩니다. 이 값은 100,000보다 클 수 없습니다. 순서대로 문서를 검색해야 하지만 이 제한으로 인해 $skip 사용할 수 없는 경우 인덱스의 모든 문서에 대해 고유한 값이 있는 필드에 $orderby 사용하고(예: 문서 키) 범위 쿼리와 함께 $filter 것이 좋습니다.
맞춤법 검사기(미리 보기) 문자열 선택 사항입니다. 유효한 값은 "none" 및 "lexicon"입니다. 기본값은 "none"입니다. 개별 검색 쿼리 용어를 맞춤법 수정하여 회수를 개선합니다. 단순, 전체 및 의미 체계 쿼리 형식에서 사용할 수 있습니다. 사용하는 경우 맞춤법 검사기 매개 변수에는 queryLanguage가 필요합니다. 자세한 내용과 예제는 쿼리에 맞춤법 검사 추가를 참조하세요.
$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개의 결과의 다음 페이지를 검색하는 정보가 반환됩니다.
벡터(미리 보기) array 선택 사항입니다. 배열 내의 개체 형식은 벡터 쿼리입니다. 벡터 쿼리에 대한 쿼리 매개 변수입니다.

"value"는 검색 쿼리의 벡터 표현입니다. 이 표현은 외부에서 형성되어야 합니다. Azure AI Search는 포함을 만들지 않습니다.

"k"는 상위 적중으로 반환할 가장 가까운 인접 항목 수를 지정하는 정수입니다. 기본값은 50입니다. 최소값은 1이고 최대값은 10,000입니다.

"fields"는 벡터 데이터를 포함하는 쉼표로 구분된 목록 필드 이름입니다. 형식 Collection(Edm.Single) 의 필드만 "필드" 목록에 포함할 수 있습니다.

응답

상태 코드: 응답에 성공하면 ‘200 OK’가 반환됩니다. 이 문서에는 의미 체계 검색 및 기능Mode에 대해 각각 하나씩 두 개의 샘플 응답이 있습니다.

의미 체계 쿼리에 대한 샘플 응답

첫 번째 예제에서는 의미 체계 쿼리 "클라우드가 어떻게 형성되는지"에 대한 최상위 결과에 대한 전체 응답을 보여 줍니다.

  • "@search.answers"는 answers 매개 변수를 지정하고 인덱스의 쿼리 및 대상 필드에 답변으로 인식할 수 있는 콘텐츠가 포함될 때 나타납니다. @search.answers 키, 텍스트 및 강조 표시가 있는 배열입니다. 점수는 답변의 강도를 나타내는 지표입니다.

  • "value"는 응답의 본문입니다. 는 @search.rerankerScore 의미 체계 순위 알고리즘에 의해 할당되며 결과의 순위를 지정하는 데 사용됩니다(@search.score는 초기 결과를 채점할 때 사용되는 BM25 유사성 알고리즘에서 사용됨). 캡션에는 일반 텍스트와 강조 표시된 버전이 포함됩니다. 이 예제는 OCR 및 엔터티 인식 기술을 사용하여 만들어졌습니다. 추출 및 병합된 콘텐츠에 대한 필드가 응답에 포함됩니다.

{
    "@search.answers": [
        {
            "key": "aHR0cHM6Ly9oZWlkaXN0YmxvYnN0b3JhZ2UuYmxvYi5jb3JlLndpbmRvd3MubmV0L25hc2EtZWJvb2stMS01MC9wYWdlLTQ1LnBkZg2",
            "text": "Sunlight heats the land all day, warming that moist air and causing it to rise high into the atmosphere until it cools and condenses into water droplets. Clouds generally form where air is ascending (over land in this case),   but not where it is descending (over the river).",
            "highlights": "Sunlight heats the land all day, warming that moist air and causing it to rise high into the   atmosphere until it cools and condenses into water droplets. Clouds generally form<em> where air is ascending</em> (over land in this case),   but not where it is<em> descending</em> (over the river).",
            "score": 0.94639826
        }
    ],
    "value": [
        {
            "@search.score": 0.5479723,
            "@search.rerankerScore": 1.0321671911515296,
            "@search.captions": [
                {
                    "text": "Like all clouds, it forms when the air reaches its dew point—the temperature at which an air mass is cool enough for its water vapor to condense into liquid droplets. This false-color image shows valley fog, which is common in the Pacific Northwest of North America.",
                    "highlights": "Like all<em> clouds</em>, it<em> forms</em> when the air reaches its dew point—the temperature at    which an air mass is cool enough for its water vapor to condense into liquid droplets. This false-color image shows valley<em> fog</em>, which is common in the Pacific Northwest of North America."
                }
            ],
            "content": "\nA\nT\n\nM\nO\n\nS\nP\n\nH\nE\n\nR\nE\n\nE\nA\n\nR\nT\n\nH\n\n34\n\nValley Fog\nCanada\n\nFog is essentially a cloud lying on the ground. Like all clouds, it forms when the air reaches its dew point—the temperature at  \n\nwhich an air mass is cool enough for its water vapor to condense into liquid droplets.\n\nThis false-color image shows valley fog, which is common in the Pacific Northwest of North America. On clear winter nights, the \n\nground and overlying air cool off rapidly, especially at high elevations. Cold air is denser than warm air, and it sinks down into the \n\nvalleys. The moist air in the valleys gets chilled to its dew point, and fog forms. If undisturbed by winds, such fog may persist for \n\ndays. The Terra satellite captured this image of foggy valleys northeast of Vancouver in February 2010.\n\n\n",
            "metadata_storage_path": "aHR0cHM6Ly9oZWlkaXN0YmxvYnN0b3JhZ2UuYmxvYi5jb3JlLndpbmRvd3MubmV0L25hc2EtZWJvb2stMS01MC9wYWdlLTQxLnBkZg2",
            "people": [],
            "locations": [
                "Pacific Northwest",
                "North America",
                "Vancouver"
            ],
            "merged_content": "\nA\nT\n\nM\nO\n\nS\nP\n\nH\nE\n\nR\nE\n\nE\nA\n\nR\nT\n\nH\n\n34\n\nValley Fog\nCanada\n\nFog is essentially a cloud lying on the ground. Like all clouds, it forms when the air reaches its dew point—the temperature at  \n\nwhich an air mass is cool enough for its water vapor to condense into liquid droplets.\n\nThis false-color image shows valley fog, which is common in the Pacific Northwest of North America. On clear winter nights, the \n\nground and overlying air cool off rapidly, especially at high elevations. Cold air is denser than warm air, and it sinks down into the \n\nvalleys. The moist air in the valleys gets chilled to its dew point, and fog forms. If undisturbed by winds, such fog may persist for \n\ndays. The Terra satellite captured this image of foggy valleys northeast of Vancouver in February 2010.\n\n\n",
            "text": [],
            "layoutText": []
        }
    ]
}

featuresMode에 대한 샘플 응답

이 예제에서는 featuresMode를 포함하는 쿼리의 "@search.features" 출력을 보여줍니다.

  {
    "@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),
      "featuresMode" : ... (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 식 구문에서 더 많은 예제를 찾을 수 있습니다.

예: 단순 검색

단순 쿼리 구문을 사용하여 인덱스에서 문서를 찾습니다. 이 쿼리는 검색 가능한 필드에 "comfort" 및 "location"이라는 용어가 있지만 "motel"이라는 용어가 없는 호텔을 반환합니다.

Get /indexes/hotels/docs?search=comfort +location –motel&searchMode=all&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "comfort +location -motel",  
      "searchMode": "all"  
    }

팁

searchMode=all을 사용하면 searchMode=any의 기본값을 재정의하여 -motel이 "OR NOT" 대신 "AND NOT"을 의미하도록 합니다. searchMode=all을 사용하지 않으면 검색 결과를 제한하는 것이 아니라 확장하는 "OR NOT"을 가져오므로 일부 사용자에게 직관적으로 보이지 않을 수 있습니다.

예: 전체 Lucene 검색

Lucene 쿼리 구문을 사용하여 인덱스에서 문서를 찾습니다( Azure AI Search의 Lucene 쿼리 구문 참조). 이 쿼리는 범주 필드에 “예산"이라는 용어가 포함된 호텔 및 “최근 혁신된" 문구가 포함된 모든 검색 가능 필드를 반환합니다. 용어 boost 값(3)의 결과로 "최근 혁신된" 문구가 포함된 문서가 더 높은 순위가 됩니다.

GET /indexes/hotels/docs?search=Category:budget AND \"recently renovated\"^3&searchMode=all&api-version=2021-04-30-Preview&querytype=full`

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "Category:budget AND \"recently renovated\"^3",  
      "queryType": "full",  
      "searchMode": "all"  
}

예: 의미 체계 검색

답변, 캡션 및 강조 표시된 콘텐츠를 사용하여 의미 체계 순위 모델을 호출합니다. 이 쿼리에 대한 응답은 이전 섹션에서 찾을 수 있습니다.

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
{
  "search": "how do clouds form",
  "queryType": "semantic",
  "semanticConfiguration": "my-semantic-config",
  "queryLanguage": "en-us",
  "answers": "extractive",
  "captions": "extractive",
  "count": "true"
}

예: 벡터 검색

형식 Collection(Edm.Single) 필드와 벡터 구성이 있는 인덱스의 경우 벡터 쿼리 매개 변수를 지정할 수 있습니다. 벡터 쿼리 매개 변수에는 쿼리에 대해 scope 있는 벡터 필드, 반환할 상위 적중 횟수의 "k" 수 및 쿼리 입력의 벡터 표현이 포함됩니다.

인덱스가 텍스트 필드를 포함하는 경우 "select" 매개 변수를 추가하는 것이 유용합니다. 일치 및 관련성은 벡터를 기반으로 하지만 사람이 읽을 수 있는 콘텐츠가 포함된 필드는 결과를 읽는 사람에게 더 유용합니다. 또는 검색 결과의 벡터 데이터를 텍스트로 변환하는 코드를 작성할 수 있습니다.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version={{api-version}}
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "search": (this parameter is ignored in vector search),
    "vectors": [{
        "value": [
            -0.009154141,
            0.018708462,
            . . . 
            -0.02178128,
            -0.00086512347
        ],
        "fields": "contentVector",
        "k": 5
    }],
    "select": "title, content, category"
}

예: orderby

인덱스 검색 및 날짜를 기준으로 정렬된 결과를 내림차순으로 반환합니다.

GET /indexes/hotels/docs?search=*&$orderby=LastRenovationDate desc&api-version=2021-04-30-Preview

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

예제: OData 식을 사용하여 필터링

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

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

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

예: 패싯 검색

패싯 검색에서 인덱스를 검색하고 특정 범위에서 baseRate가 있는 항목뿐만 아니라 범주, 등급, 태그에 대한 패싯을 검색합니다.

GET /indexes/hotels/docs?search=*&facet=Category&facet=Rating&facet=Tags&facet=Rooms/BaseRate,values:80|150|220&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "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=2021-04-30-Preview  

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview 
    {  
      "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=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "test",  
      "facets": [ "Address/City,count:5" ]  
    }

예: 현장 검색

특정 필드(예: 언어 필드) 내에서 인덱스 검색

GET /indexes/hotels/docs?search=hôtel&searchFields=Description_fr&api-version=2021-04-30-Preview

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

여러 필드에서 인덱스 검색 예를 들어 모두 동일한 인덱스 내에서 여러 언어로 된 검색 가능 필드를 저장하고 쿼리할 수 있습니다. 영어 및 프랑스어 설명이 동일한 문서에 공존하는 경우 쿼리 결과에서 또는 모두를 반환할 수 있습니다.

GET /indexes/hotels/docs?search=hotel&searchFields=Description,Description_fr&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "hotel",  
      "searchFields": "Description, Description_fr"
    }

한 번에 하나의 인덱스만 쿼리할 수 있습니다. 한 번에 하나씩 쿼리하려는 경우가 아니면 각 언어에 대해 여러 인덱스를 만들지 마세요.

예: 페이징 결과

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

GET /indexes/hotels/docs?search=*&$skip=0&$top=10&api-version=2021-04-30-Preview

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

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

GET /indexes/hotels/docs?search=*&$skip=10&$top=10&api-version=2021-04-30-Preview

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

예: 결과 집합의 필드 제한

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

GET /indexes/hotels/docs?search=*&$select=HotelName,Description&api-version=2021-04-30-Preview

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

예: 결과에서 적중 강조 표시

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

GET /indexes/hotels/docs?search=something&highlight=Description&api-version=2021-04-30-Preview

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

예: 지리 공간적 검색

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

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

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

예: "find by me"(주변 위치의 관련성 향상)

"currentLocation"이라는 매개 변수를 정의하는 것과 "lastLocation"이라는 매개 변수를 정의하는 두 개의 거리 점수 매기기 함수가 있는 "geo"라는 점수 매기기 프로필이 있다고 가정하여 인덱스를 검색합니다. 다음 예제에서 "currentLocation"에는 단일 대시(-)의 구분 기호가 있습니다. 경도 및 위도 좌표가 뒤따릅니다. 여기서 경도는 음수 값입니다.

GET /indexes/hotels/docs?search=something&scoringProfile=geo&scoringParameter=currentLocation--122.123,44.77233&scoringParameter=lastLocation--121.499,44.2113&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "something",  
      "scoringProfile": "geo",  
      "scoringParameters": [ "currentLocation--122.123,44.77233", "lastLocation--121.499,44.2113" ]  
    }

예제: 분할된 데이터베이스 대신 전체 인덱스 쿼리

짧은 대기 시간보다 일관된 채점을 선호하면서 인덱스에서 문서를 찾습니다. 이 쿼리는 전체 인덱스에서 문서 빈도를 계산하고 동일한 "세션" 내의 모든 쿼리에 대해 동일한 복제본(replica) 대상으로 지정하여 안정적이고 재현 가능한 순위를 생성하는 데 도움이 됩니다.

GET /indexes/hotels/docs?search=hotel&sessionId=mySessionId&scoringStatistics=global&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "hotel",  
      "sessionId": "mySessionId",
      "scoringStatistics" :"global"
    }

예: 점수 매기기 통계(featuresMode)

인덱스에서 문서를 찾고 일치하는 문서와 쿼리 간의 채점을 설명하는 각 결과에 대한 정보 검색 기능 목록을 반환합니다. 또한 쿼리는 전체 인덱스에서 문서 빈도를 계산하여 보다 일관된 채점을 생성합니다.

GET /indexes/hotels/docs?search=hotel&featuresMode=enabled&scoringStatistics=global&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "hotel",  
      "featuresMode": "enabled",
      "scoringStatistics" :"global"
    }

를 포함하는 search.features 응답의 예는 다음과 유사합니다.

    "@search.score": 0.91875637,
    "@search.features": {
        "Description": {
            "uniqueTokenMatches": 1,
            "similarityScore": 0.2917966,
            "termFrequency": 2
        },
        "HotelName": {
            "uniqueTokenMatches": 1,
            "similarityScore": 0.44458693,
            "termFrequency": 1
        }
      . . .

정의

이 섹션에서는 기본 테이블에서 다루기에는 너무 복잡한 매개 변수에 대한 세부 정보를 제공합니다.

링크 Description
queryLanguage 맞춤법 검사기 및 의미 체계 검색에 지원되는 언어 목록입니다.

queryLanguage

queryLanguage 매개 변수에 대한 유효한 값은 다음 표의 "queryLanguage" 열에 제공되며 대/소문자를 구분하지 않습니다. 매개 변수 전체의 기본값은 "en-us"입니다. 각 언어 내에는 각 2자 언어 코드에 대한 기본 변형이 있습니다. 예를 들어 "es"를 지정하면 기본적으로 "es-us"가 사용됩니다. queryLanguage 매개 변수는 "queryType=semantic" 또는 "speller=lexicon"을 포함하는 쿼리 요청에 필요합니다. 전체 요청에 대한 queryLanguage 값은 하나뿐이며 해당 값은 의미 체계 순위, 캡션, 답변 및 맞춤법 검사기(개별 기능에 대한 재정의 없음)에 사용됩니다.

현재 언어 지원은 기능에 따라 다릅니다. 전체 기능 집합에는 영어, 스페인어, 프랑스어 및 독일어만 지원되지만 맞춤법 검사 더 적은 변형을 구현합니다.

맞춤법 검사기를 사용하는 EN-GB와 같이 지정된 기능에서 지원되지 않는 언어 코드를 지정하면 서비스는 HTTP 400을 반환합니다.

각 기능을 사용하는 방법에 대한 자세한 내용은 의미 체계 순위 및 캡션 사용, 의미 체계 답변 반환 및 쿼리에 맞춤법 검사 추가를 참조하세요.

"(미리 보기)" 지정은 모든 기능(의미 체계 순위, 캡션, 답변 및 맞춤법 검사)에 대한 유효성 검사가 진행 중이거나 보류 중임을 나타냅니다. 다음 표에 있는 모든 언어 변형을 사용하는 것이 좋지만, 콘텐츠에 대해 결과가 유효한지 확인하기 위해 미리 보기 언어를 더 테스트하는 것이 좋습니다. 검사 표시가 있고 미리 보기 지정이 없는 언어는 관련성이 측정 가능한 증가와 함께 동등한 데이터 집합을 사용하여 유효성을 검사했습니다.

언어 queryLanguage 의미 체계 순위 및 캡션 의미 체계 답변 검사기
영어 [en] en, en-US(기본값), en-GB, en-IN, , en-CAen-AU ✔️ ✔️ ✔️ (en, en-US)
프랑스어 [fr] fr, fr-FR (기본값), fr-CA ✔️ ✔️ ✔️ (fr, fr-FR)
독일어 [de] de, de-DE(기본값) ✔️ ✔️ ✔️ (de, de-DE)
스페인어 [es] es, es-ES(기본값), es-MX ✔️ ✔️ ✔️ (es, es-ES)
이탈리아어 [it] it, it-IT(기본값) ✔️ ✔️
일본어 [ja] ja, ja-JP(기본값) ✔️ ✔️ (미리 보기)
중국어 [zh] zh, zh-CN(기본값), zh-TW ✔️ ✔️ (미리 보기)
포르투갈어 [pt] pt, pt-BR(기본값), pt-PT ✔️ ✔️ (미리 보기)
네덜란드어 [nl] nl, nl-BE, nl-NL(기본값) ✔️ (미리 보기) ✔️ (미리 보기) ✔️ (nl, nl-NL)
아랍어 [ar] ar, ar-SA(기본값), ar-EG, ar-MA, ar-KW, ar-JO ✔️ (미리 보기) ✔️ (미리 보기)
아르메니아어 hy-AM(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
벵골어 bn-IN(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
바스크어 eu-ES(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
불가리아어 [bg] bg, bg-BG(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
카탈로니아어 [ca] ca, ca-ES(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
크로아티아어 [hr] hr, hr-HR (기본값), hr-BA ✔️ (미리 보기) ✔️ (미리 보기)
체코어 [cs] cs, cs-CZ(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
덴마크어 [da] da, da-DK(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
에스토니아어 [et] et, et-EE(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
핀란드어 [fi] fi, fi-FI(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
갈리시아어 gl-ES(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
그리스어 [el] el, el-GR(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
구자라트어 gu-IN(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
히브리어 he-IL(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
힌디어 [hi] hi, hi-IN(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
헝가리어 [hu] hu, hu-HU(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
아이슬란드어 [is] is, is-IS(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
인도네시아어 [id] id, id-ID(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
아일랜드어 ga-IE(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
칸나다어 kn-IN(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
한국어 [ko] ko, ko-KR(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
라트비아어 [lv] lv, lv-LV(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
리투아니아어 [lt] lt, lt-LT(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
말라얄람어 ml-IN(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
말레이시아어 [ms] ms, ms-MY(기본값), ms-BN ✔️ (미리 보기) ✔️ (미리 보기)
마라티어 mr-IN(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
노르웨이어 [no] 아니요, no-NO(기본값), nb-NO ✔️ (미리 보기) ✔️ (미리 보기)
페르시아어 fa-AE(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
폴란드어 [pl] pl, pl-PL(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
펀잡어 pa-IN(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
루마니아어 [ro] ro, ro-RO(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
러시아어 [ru] ru, ru-RU(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
세르비아어 [sr] (키릴 자모 또는 라틴 문자) sr, sr-BA(기본값), sr-ME, sr-RS ✔️ (미리 보기) ✔️ (미리 보기)
슬로바키아어 [sk] sk, sk-SK(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
슬로베니아어 [sl] sl, sl-SL(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
타밀어 [ta] ta, ta-IN(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
스웨덴어 [sv] sv, sv-SE(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
텔루구어 te-IN(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
태국어 [th] th, th-TH(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
터키어 [tr] tr, tr-TR(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
우크라이나어 [uk] uk, uk-UA(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
우르두어 ur-PK(기본값) ✔️ (미리 보기) ✔️ (미리 보기)
베트남어 [va] va, vi-VN(기본값) ✔️ (미리 보기) ✔️ (미리 보기)

추가 정보