인덱스 만들기(Azure AI Search REST API)

아티클
02/22/2024

인덱스는 테이블이 데이터베이스의 레코드를 구성하는 방법과 유사하게 Azure AI Search에서 문서를 구성하고 검색하는 기본 수단입니다. 각 인덱스에는 모두 인덱스 스키마(필드 이름, 데이터 형식 및 특성)를 준수하는 문서 컬렉션이 있지만 인덱스는 다른 검색 동작을 정의하는 추가 구문(제안기, 점수 매기기 프로필 및 CORS 구성)도 지정합니다.

요청에 POST 또는 PUT을 사용할 수 있습니다. 둘 중 하나에 대해 요청 본문의 JSON 문서는 개체 정의를 제공합니다.

POST https://[servicename].search.windows.net/indexes?api-version=[api-version]  
  Content-Type: application/json
  api-key: [admin key]

또는 PUT을 사용하여 URI에서 인덱스 이름을 지정할 수 있습니다.

PUT https://[servicename].search.windows.net/indexes/[index name]?api-version=[api-version]
  Content-Type: application/json
  api-key: [admin key]

모든 서비스 요청에는 HTTPS를 사용해야 합니다. 인덱스가 없으면 생성됩니다. 이미 있는 경우 새 정의로 업데이트됩니다.

인덱스를 만들면 스키마와 메타데이터가 설정됩니다. 인덱스에 데이터를 입력하는 작업은 별도로 수행해야 합니다. 이 단계에서는 인덱서(지원되는 데이터 원본에 사용할 수 있는 인덱서 작업 참조) 또는 문서 추가, 업데이트 또는 삭제를 사용할 수 있습니다. 반전된 인덱스는 문서가 게시될 때 생성됩니다.

참고

만들 수 있는 최대 인덱스 수는 가격 책정 계층에 따라 다릅니다. 자세한 내용은 서비스 제한을 참조하세요.

URI 매개 변수

매개 변수	Description
서비스 이름	필수 사항입니다. 검색 서비스의 고유한 사용자 정의 이름으로 설정합니다.
인덱스 이름	PUT을 사용하는 경우 URI에 필요합니다. 이름은 소문자여야 하고, 문자 또는 숫자로 시작하고, 슬래시나 점이 없고, 128자 미만이어야 합니다. 이름의 시작은 문자 또는 숫자로 시작해야 하지만 밑줄과 대시가 연속되지 않는 한 나머지 이름에는 문자, 숫자, 밑줄 및 대시가 포함될 수 있습니다.
api-version	필수 사항입니다. 지원되는 버전 목록은 API 버전을 참조하세요.

요청 헤더

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

필드	Description
콘텐츠 형식	필수 사항입니다. `application/json`
api-key	Azure 역할을 사용하고 요청에 전달자 토큰이 제공된 경우 선택 사항이며, 그렇지 않으면 키가 필요합니다. 만들기 요청에는 쿼리 키가 아닌 관리자 키로 설정된 헤더가 포함되어 `api-key` 야 합니다. 자세한 내용은 키 인증을 사용하여 Azure AI Search에 연결을 참조하세요.

요청 본문

요청 본문에는 이 인덱스에 공급할 문서 내의 데이터 필드 목록이 들어 있는 스키마 정의가 포함됩니다.

다음 JSON은 정의의 기본 부분에 대한 개략적인 표현입니다.

{  
  "name": (optional on PUT; required on POST) "Name of the index",  
  "fields": [  
    {  
      "name": "name_of_field",  
      "type": "Edm.String | Edm.Int32 | Edm.Int64 | Edm.Double | Edm.Boolean | Edm.DateTimeOffset | Edm.GeographyPoint | Edm.ComplexType | Collection(Edm.String) | Collection(Edm.Int32) | Collection(Edm.Int64) | Collection(Edm.Double) | Collection(Edm.Boolean) | Collection(Edm.DateTimeOffset) | Collection(Edm.GeographyPoint) | Collection(Edm.ComplexType)",  
      "searchable": true (default where applicable) | false (only Edm.String and Collection(Edm.String) fields can be searchable),  
      "filterable": true (default) | false,  
      "sortable": true (default where applicable) | false (Collection(Edm.String) fields cannot be sortable),  
      "facetable": true (default where applicable) | false (Edm.GeographyPoint fields cannot be facetable),  
      "key": true | false (default, only Edm.String fields can be keys, enable on one field only),  
      "retrievable": true (default) | false,  
      "analyzer": "name_of_analyzer_for_search_and_indexing", (only if 'searchAnalyzer' and 'indexAnalyzer' are not set)
      "searchAnalyzer": "name_of_search_analyzer", (only if 'indexAnalyzer' is set and 'analyzer' is not set)
      "indexAnalyzer": "name_of_indexing_analyzer", (only if 'searchAnalyzer' is set and 'analyzer' is not set)
      "synonymMaps": [ "name_of_synonym_map" ] (optional, only one synonym map per field is currently supported),
      "fields" : [ ... ] (optional, a list of sub-fields if this is a field of type Edm.ComplexType or Collection(Edm.ComplexType). Must be null or empty for simple fields.)
    }
  ],
  "similarity": (optional) { },
  "suggesters": (optional) [ ... ],  
  "scoringProfiles": (optional) [ ... ],  
  "analyzers":(optional) [ ... ],
  "charFilters":(optional) [ ... ],
  "tokenizers":(optional) [ ... ],
  "tokenFilters":(optional) [ ... ],
  "defaultScoringProfile": (optional) "Name of a custom scoring profile to use as the default",  
  "corsOptions": (optional) { },
  "encryptionKey":(optional) { }  
}

요청에는 다음 속성이 포함됩니다.

속성	Description
name	필수 사항입니다. 인덱스의 이름입니다. 인덱스 이름은 소문자, 숫자 또는 대시만 포함해야 하며 대시로 시작하거나 끝낼 수 없으며 128자로 제한됩니다.
필드	필수 사항입니다. 이름, 데이터 형식 및 해당 필드에 허용되는 작업을 정의하는 특성을 포함하여 이 인덱스로 공급될 필드의 컬렉션입니다. 데이터 형식은 EDM(엔터티 데이터 모델)을 준수합니다. 자세한 내용은 지원되는 데이터 형식을 참조하세요. 컬렉션에 키 필드로 지정된 필드가 하나 있어야 합니다. 이 필드는 문자열 필드여야 하며, 이 필드는 인덱스와 함께 저장된 각 문서에 대해 문서 ID라고도 하는 고유 식별자를 나타냅니다. 문서 키는 대/소문자를 구분합니다. 예를 들어 키가 "abc"인 문서는 "ABC" 키가 있는 문서와는 다른 것으로 간주됩니다.
유사성	선택 사항입니다. 2020년 7월 15일 이전에 만든 서비스의 경우 BM25 순위 알고리즘을 사용하도록 이 속성을 설정합니다. 유효한 값은 `"#Microsoft.Azure.Search.ClassicSimilarity"`나 `"#Microsoft.Azure.Search.BM25Similarity"`입니다. 이 속성을 지원하는 API 버전에는 2020-06-30 및 2019-05-06-Preview가 포함됩니다. 자세한 내용은 Azure AI Search의 순위 알고리즘을 참조하세요.
제안기	선택 사항입니다. 인덱스당 하나씩 자동 완성된 쿼리 또는 제안된 검색 결과에 사용됩니다. 자동 완성 및 제안과 같은 부분 쿼리에서 일치하기 위한 접두사를 저장하는 데이터 구조입니다. `name` 자동 완성된 쿼리 및 제안된 결과에 대한 콘텐츠를 제공하는 및 제안기 인식 필드로 구성됩니다. `searchMode` 는 필수이며 항상 로 설정됩니다 `analyzingInfixMatching`. 쿼리 문자열의 모든 용어에서 일치가 발생되도록 지정합니다.
scoringProfiles	선택 사항입니다. 사용자 지정 검색 점수 순위에 사용됩니다. 사용자 지정 프로필을 쿼리 문자열에 지정하지 않을 때마다 호출되는 기본값으로 사용자 지정 프로필을 사용하도록 설정합니다 `defaultScoringProfile` . 요소에 대한 자세한 내용은 검색 인덱스에 점수 매기기 프로필 추가 및 다음 섹션의 예제를 참조하세요.
분석기, charFilters, tokenizers, tokenFilters	선택 사항입니다. 사용자 지정 분석기를 정의하는 경우 인덱스의 다음 섹션을 지정합니다. 기본적으로 이러한 섹션은 null입니다.
defaultScoringProfile	선택 사항입니다. 기본 채점 동작을 덮어쓰는 사용자 지정 점수 매기기 프로필의 이름입니다.
corsOptions	선택 사항입니다. 브라우저가 모든 원본 간 요청을 방지하므로 클라이언트 쪽 JavaScript는 기본적으로 API를 호출할 수 없습니다. 인덱스에 대한 원본 간 쿼리를 허용하려면 corsOptions 특성을 설정하여 CORS(원본 간 리소스 공유)를 사용하도록 설정합니다. 보안상의 이유로 쿼리 API에서만 CORS가 지원됩니다. 섹션에는 `corsOptions` (필수) 인덱스에 대한 액세스 권한이 부여되는 쉼표로 구분된 원본 목록이 포함 `allowedOrigins` 됩니다. 여기서 각 원본은 일반적으로 형식 protocol://< fully-qualified-domain-name>:<port(포트>>는 생략되는 경우가 많지만<)입니다. 이 원본에서 제공되는 모든 JavaScript 코드는 올바른 `api-key`를 제공하는 경우 인덱스를 쿼리하도록 허용됩니다. 모든 원본에 대한 액세스를 허용하려면 배열에서 `allowedOrigins` 단일 항목으로 지정 `*` 합니다. 프로덕션에는 권장되지 않지만 개발 또는 디버깅에 유용할 수 있습니다. `maxAgeInSeconds` (선택 사항) 브라우저는 이 값을 사용하여 CORS 실행 전 응답을 캐시하는 기간(초)을 결정합니다. 이 값은 음수가 아닌 정수여야 합니다. 이 값이 클수록 성능은 개선되지만 CORS 정책 변경 내용이 적용되는 시간은 더 오래 걸립니다. 설정되지 않은 경우 기본 기간인 5분이 사용됩니다.
encryptionKey	선택 사항입니다. Azure Key Vault 관리되는 고유한 키를 사용하여 동의어 맵을 암호화하는 데 사용됩니다. 2019-01-01 또는 그 이후에 생성된 청구 가능한 검색 서비스에 사용할 수 있습니다. `encryptionKey` 섹션에는 사용자 정의 `keyVaultKeyName` (필수), 시스템 생성 `keyVaultKeyVersion` (필수) 및 `keyVaultUri` 제공 키(필수, DNS 이름이라고도 함)가 포함되어 있습니다. 예제 URI는 "https://my-keyvault-name.vault.azure.net"일 수 있습니다. 필요에 따라 관리되는 시스템 ID를 사용하지 않는지 지정할 `accessCredentials` 수 있습니다. 의 `accessCredentials` 속성에는 지정된 Azure Key Vault 대한 액세스 권한이 부여된(Microsoft Entra ID 애플리케이션 ID) 및 `applicationSecret` (등록된 애플리케이션의 인증 키)가 포함 `applicationId` 됩니다. 다음 섹션의 예제에서는 구문을 보여 줍니다.

필드 정의

인덱스 생성 시 필드에 다음 특성을 설정할 수 있습니다.

attribute	Description
name	필수 사항입니다. 인덱스 또는 부모 필드의 필드 컬렉션 내에서 고유해야 하는 필드의 이름을 설정합니다.
type	필수 사항입니다. 필드의 데이터 형식을 설정합니다. 필드는 단순하거나 복잡할 수 있습니다. 단순 필드는 텍스트 또는 `Edm.Int32` 정수와 같은 `Edm.String` 기본 형식입니다. 복합 필드에 는 단순하거나 복잡한 하위 필드가 있을 수 있습니다. 이렇게 하면 개체 및 개체의 배열을 모델링할 수 있으므로 대부분의 JSON 개체 구조를 인덱스에 업로드할 수 있습니다. 지원되는 형식의 전체 목록은 지원되는 데이터 형식(Azure AI Search)을 참조하세요.
key	필수 사항입니다. 필드의 값이 인덱스의 문서를 고유하게 식별하도록 지정하려면 이 특성을 true로 설정합니다. 키 필드의 최대 값 길이는 1024자입니다. 각 인덱스에서 정확히 하나의 최상위 필드를 키 필드로 선택해야 하며 형식 `Edm.String`이어야 합니다. 기본값은 단순 필드 및 `null` 복소수 필드의 경우 입니다`false`. 키 필드는 문서를 직접 조회하고 특정 문서를 업데이트하거나 삭제하는 데 사용할 수 있습니다. 키 필드의 값은 문서를 조회하거나 인덱싱할 때 대/소문자를 구분하는 방식으로 처리됩니다. 자세한 내용은 문서 조회(Azure AI Search REST API) 및 문서 추가, 업데이트 또는 삭제(Azure AI Search REST API) 를 참조하세요.
retrievable	검색 결과에서 필드를 반환할 수 있는지 여부를 나타냅니다. 필드(예: 여백)를 필터, 정렬 또는 채점 메커니즘으로 사용하지만 최종 사용자에게 필드를 표시하지 않으려면 이 특성을 `false` 로 설정합니다. 이 특성은 키 필드에 대한 특성이어야 `true` 하며 복잡한 필드에 대한 특성이어야 `null` 합니다. 이 특성은 기존 필드에서 변경할 수 있습니다. 검색 가능 을 로 `true` 설정해도 인덱스 스토리지 요구 사항이 증가하지 않습니다. 기본값은 단순 필드 및 `null` 복소수 필드의 경우 입니다`true`.
searchable	필드가 전체 텍스트 검색 가능하고 검색 쿼리에서 참조할 수 있는지 여부를 나타냅니다. 즉, 인덱싱 중에 단어 분리와 같은 어휘 분석을 거칩니다. 검색 가능한 필드를 "Sunny day"와 같은 값으로 설정하면 내부적으로 정규화되고 개별 토큰 "sunny" 및 "day"로 분할됩니다. 따라서 이러한 용어에 대한 전체 텍스트 검색을 수행할 수 있습니다. 또는 형식 `Edm.StringCollection(Edm.String)` 의 필드는 기본적으로 검색할 수 있습니다. 이 특성은 `false` 다른 비 문자열 데이터 형식의 단순 필드에 대한 것이어야 하며 복잡한 필드의 경우여야 `null` 합니다. Azure AI Search는 해당 필드의 내용을 처리하고 수행 검색을 위해 보조 데이터 구조로 구성하므로 검색 가능한 필드는 인덱스에 추가 공간을 사용합니다. 인덱스의 공간을 절약하고 검색에 필드를 포함할 필요가 없는 경우 검색 가능을 로 `false`설정합니다. 자세한 내용은 Azure AI Search에서 전체 텍스트 검색 작동 방식을 참조하세요.
filterable	쿼리에서 `$filter` 필드를 참조할 수 있도록 설정할지 여부를 나타냅니다. 필터링 가능 항목은 문자열 처리 방식에서 검색 가능 항목과 다릅니다. 형식 `Edm.String` 또는 `Collection(Edm.String)` 필터링 가능한 필드는 어휘 분석을 거치지 않으므로 정확한 일치 항목에 대해서만 비교가 가능합니다. 예를 들어 이러한 필드를 `f` "맑은 날" `$filter=f eq 'sunny'` 로 설정하면 일치하는 항목은 찾을 수 없지만 `$filter=f eq 'Sunny day'` 은 입니다. 이 특성은 복합 필드에 대한 특성이어야 `null` 합니다. 기본값은 단순 필드 및 `null` 복소수 필드의 경우 입니다`true`. 인덱스 크기를 줄이려면 필터링하지 않는 필드에서 이 특성을 `false` 로 설정합니다.
sortable	식에서 `$orderby` 필드를 참조할 수 있도록 설정할지 여부를 나타냅니다. 기본적으로 Azure AI Search는 점수를 기준으로 결과를 정렬하지만 대부분의 환경에서 사용자는 문서의 필드를 기준으로 정렬하려고 합니다. 단순 필드는 단일 값인 경우에만 정렬할 수 있습니다(부모 문서의 scope 단일 값이 있음). 단순 컬렉션 필드는 다중값이므로 정렬할 수 없습니다. 복합 컬렉션의 단순 하위 필드도 다중 값이므로 정렬할 수 없습니다. 이는 바로 부모 필드이든 상위 필드이든 관계없이 복잡한 컬렉션입니다. 복합 필드는 정렬할 수 없으며 정렬 가능한 특성은 해당 필드에 대해 여야 `null` 합니다. 정렬 가능의 기본값은 `true` 단일 값 단순 필드, `false` 다중값 단순 필드 및 `null` 복합 필드의 경우 입니다.
facetable	패싯 쿼리에서 필드를 참조할 수 있도록 설정할지 여부를 나타냅니다. 일반적으로 범주별 적중 횟수를 포함하는 검색 결과 프레젠테이션에 사용됩니다(예: 디지털 카메라를 검색하고 브랜드별 적중 횟수, 메가픽셀별, 가격 등). 이 특성은 복합 필드에 대한 특성이어야 `null` 합니다. 형식 `Edm.GeographyPoint` 또는 `Collection(Edm.GeographyPoint)` 필드는 패싯할 수 없습니다. 기본값은 `true` 다른 모든 단순 필드에 대한 것입니다. 인덱스 크기를 줄이려면 이 특성을 `false` 패싯하지 않는 필드에서 로 설정합니다.
분석기	인덱싱 및 쿼리 작업 중에 문자열을 토큰화하기 위한 어휘 분석기를 설정합니다. 이 속성의 유효한 값에는 언어 분석기, 기본 제공 분석기 및 사용자 지정 분석기가 포함됩니다. 기본값은 `standard.lucene`입니다. 이 특성은 검색 가능한 문자열 필드에만 사용할 수 있으며 searchAnalyzer 또는 indexAnalyzer와 함께 설정할 수 없습니다. 분석기를 선택하고 인덱스에 필드를 만든 후에는 필드에 대해 변경할 수 없습니다. 복소수 필드의 경우 여야 `null` 합니다.
searchAnalyzer	인덱싱 및 쿼리에 대해 다른 어휘 분석기를 지정하려면 indexAnalyzer와 함께 이 속성을 설정합니다. 이 속성을 사용하는 경우 분석기를 로 `null` 설정하고 indexAnalyzer가 허용되는 값으로 설정되어 있는지 확인합니다. 이 속성의 유효한 값에는 기본 제공 분석기 및 사용자 지정 분석기가 포함됩니다. 이 특성은 검색 가능한 필드에만 사용할 수 있습니다. 검색 분석기는 쿼리 시간에만 사용되므로 기존 필드에서 업데이트할 수 있습니다. 복소수 필드의 경우 여야 `null` 합니다.
indexAnalyzer	인덱싱 및 쿼리에 대해 다른 어휘 분석기를 지정하려면 searchAnalyzer와 함께 이 속성을 설정합니다. 이 속성을 사용하는 경우 분석기를 로 `null` 설정하고 searchAnalyzer가 허용되는 값으로 설정되어 있는지 확인합니다. 이 속성의 유효한 값에는 기본 제공 분석기 및 사용자 지정 분석기가 포함됩니다. 이 특성은 검색 가능한 필드에만 사용할 수 있습니다. 인덱스 분석기가 선택되면 필드에 대해 변경할 수 없습니다. 복소수 필드의 경우 여야 `null` 합니다.
synonymMaps	이 필드와 연결할 동의어 맵의 이름 목록입니다. 이 특성은 검색 가능한 필드에만 사용할 수 있습니다. 현재 필드당 하나의 동의어 맵만 지원됩니다. 필드에 동의어 맵을 할당하면 해당 필드를 대상으로 하는 쿼리 용어가 동의어 맵의 규칙을 사용하여 쿼리 시간에 확장됩니다. 이 특성은 기존 필드에서 변경할 수 있습니다. 또는 복합 필드의 빈 컬렉션이어야 `null` 합니다.
fields	또는 형식 `Edm.ComplexTypeCollection(Edm.ComplexType)`의 필드인 경우 하위 필드 목록입니다. 단순 필드의 경우 이거나 `null` 비어 있어야 합니다. 하위 필드를 사용하는 방법과 시기에 대한 자세한 내용은 Azure AI Search에서 복잡한 데이터 형식을 모델링하는 방법을 참조하세요.

참고

필터링 가능, 정렬 가능 또는 패싯 가능 형식 Edm.String 의 필드는 길이가 최대 32킬로바이트일 수 있습니다. 이러한 필드의 값은 단일 검색 용어로 처리되고 Azure AI Search에서 용어의 최대 길이는 32K바이트이기 때문입니다. 이보다 많은 텍스트를 단일 문자열 필드에 저장해야 하는 경우 인덱스 정의에서 필터링 가능, 정렬 가능 및 패싯 가능을 false 로 명시적으로 설정해야 합니다.

필드를 검색 가능, 필터링 가능, 정렬 가능 또는 패싯 가능으로 설정하면 인덱스 크기 및 쿼리 성능에 영향을 줍니다. 쿼리 식에서 참조할 수 없는 필드에는 이러한 특성을 설정하지 마세요.

필드를 검색 가능, 필터링 가능, 정렬 가능 또는 패싯 가능으로 설정하지 않으면 쿼리 식에서 필드를 참조할 수 없습니다. 이는 쿼리에 사용되지 않지만 검색 결과에 필요한 필드에 유용합니다.

참고

만들 수 있는 인덱스의 최대 수는 가격 책정 계층에 따라 다릅니다. 자세한 내용은 서비스 제한을 참조하세요.

응답

성공적인 요청의 경우, 상태 코드 “201 생성됨”이 표시되어야 합니다.

기본적으로 응답 본문에는 인덱스 정의에 대한 JSON이 포함됩니다. 그러나 요청 헤더가 로 설정된 return=minimal경우 Prefer 응답 본문이 비어 있고 코드의 성공 상태 "201 만든" 대신 "204 콘텐츠 없음"이 됩니다. 인덱스를 만드는 데 사용한 방법(PUT 또는 POST)과 관계없이 결과는 동일합니다.

예제

예: 인덱스 스키마

{
  "name": "hotels",  
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer" },
    { "name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true },
    { "name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address", "type": "Edm.ComplexType", 
      "fields": [
          { "name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true },
          { "name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
          { "name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
          { "name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
          { "name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true }
        ]
    },
    { "name": "Location", "type": "Edm.GeographyPoint", "filterable": true, "sortable": true },
    { "name": "Rooms", "type": "Collection(Edm.ComplexType)", 
      "fields": [
          { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene" },
          { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene" },
          { "name": "Type", "type": "Edm.String", "searchable": true },
          { "name": "BaseRate", "type": "Edm.Double", "filterable": true, "facetable": true },
          { "name": "BedOptions", "type": "Edm.String", "searchable": true },
          { "name": "SleepsCount", "type": "Edm.Int32", "filterable": true, "facetable": true },
          { "name": "SmokingAllowed", "type": "Edm.Boolean", "filterable": true, "facetable": true },
          { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "facetable": true, "analyzer": "tagsAnalyzer" }
        ]
    }
  ],
  "suggesters": [
      { "name": "sg", "searchMode": "analyzingInfixMatching", "sourceFields": ["HotelName"] }
  ],
  "analyzers": [
    {
      "@odata.type": "#Microsoft.Azure.Search.CustomAnalyzer",
      "name": "tagsAnalyzer",
      "charFilters": [ "html_strip" ],
      "tokenizer": "standard_v2"
    }
  ]
}

예: 제안기

 "suggesters": [  
   {  
     "name": "name of suggester",  
     "searchMode": "analyzingInfixMatching",  
     "sourceFields": ["field1", "field2", ...]  
   }  
 ]

제안기는 일치 항목 또는 쿼리 용어의 나머지 부분을 반환할지 여부에 따라 제안 API 또는 자동 완성 API를 포함하는 쿼리 요청에서 이름으로 참조됩니다. 제안기를 만들고 사용하는 방법에 대한 자세한 내용은 제안기 만들기를 참조하세요.

예: 검색 관련성에 대한 유사성

이 속성은 전체 텍스트 검색 쿼리의 검색 결과에서 관련성 점수를 만드는 데 사용되는 순위 알고리즘을 설정합니다. 2020년 7월 15일 이후에 생성된 서비스에서는 유사성 알고리즘이 항상 BM25이므로 이 속성은 무시됩니다. 2020년 7월 15일 이전에 만든 기존 서비스의 경우 다음과 같이 이 구문을 설정하여 BM25를 옵트인할 수 있습니다.

 "similarity": {
     "@odata.type": "#Microsoft.Azure.Search.BM25Similarity"
 }

예: CORS 옵션

브라우저가 모든 원본 간 요청을 방지하므로 클라이언트 쪽 JavaScript는 기본적으로 API를 호출할 수 없습니다. 인덱스에 대한 원본 간 쿼리를 허용하려면 특성을 설정하여 CORS(원본 간 리소스 공유(Wikipedia))를 사용하도록 설정합니다 corsOptions . 보안상의 이유로 쿼리 API에서만 CORS가 지원됩니다.

{
   "name": "hotels",  
   "fields": [ omitted for brevity],
   "suggesters": [ omitted for brevity  ],
   "analyzers": [ omitted for brevity ],
   "corsOptions": (optional) {  
       "allowedOrigins": ["*"] | ["https://docs.microsoft.com:80", "https://azure.microsoft.com:80", ...],  
       "maxAgeInSeconds": (optional) max_age_in_seconds (non-negative integer)  
     }
}

예: 암호화 키

암호화 키는 추가 암호화에 사용되는 고객 관리형 키입니다. 자세한 내용은 Azure Key Vault 고객 관리형 키를 사용한 암호화를 참조하세요.

{
    "name": "hotels",  
    "fields": [ omitted for brevity],
    "suggesters": [ omitted for brevity  ],
    "analyzers": [ omitted for brevity ],
    "encryptionKey": (optional) { 
      "keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
      "keyVaultKeyVersion": "Version of the Azure Key Vault key",
      "keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
      "accessCredentials": (optional, only if not using managed system identity) {
        "applicationId": "AAD Application ID that was granted access permissions to your specified Azure Key Vault",
        "applicationSecret": "Authentication key of the specified AAD application)"}
      }
}

예: 점수 매기기 프로필

점수 매기기 프로필은 검색 결과에서 더 높게 표시되는 문서에 영향을 줄 수 있는 사용자 지정 채점 동작을 정의하는 스키마의 섹션입니다. 점수 매기기 프로필은 필드 가중치와 함수로 구성됩니다. 사용하려면 쿼리 문자열에서 이름별로 프로필을 지정합니다. 자세한 내용은 검색 인덱스에 점수 매기기 프로필 추가를 참조하세요.

{
   "name": "hotels",  
   "fields": [ omitted for brevity],
   "suggesters": [ omitted for brevity  ],
   "analyzers": [ omitted for brevity ],
   "scoringProfiles": [  
   {  
     "name": "name of scoring profile",  
     "text": (optional, only applies to searchable fields) {  
       "weights": {  
         "searchable_field_name": relative_weight_value (positive #'s),  
         ...  
       }  
     },  
     "functions": (optional) [  
       {  
         "type": "magnitude | freshness | distance | tag",  
         "boost": # (positive number used as multiplier for raw score != 1),  
         "fieldName": "...",  
         "interpolation": "constant | linear (default) | quadratic | logarithmic",  
         "magnitude": {  
           "boostingRangeStart": #,  
           "boostingRangeEnd": #,  
           "constantBoostBeyondRange": true | false (default)  
         },  
         "freshness": {  
           "boostingDuration": "..." (value representing timespan leading to now over which boosting occurs)  
         },  
         "distance": {  
           "referencePointParameter": "...", (parameter to be passed in queries to use as reference location)  
           "boostingDistance": # (the distance in kilometers from the reference location where the boosting range ends)  
         },  
         "tag": {  
           "tagsParameter": "..." (parameter to be passed in queries to specify a list of tags to compare against target fields)  
         }  
       }  
     ],  
     "functionAggregation": (optional, applies only when functions are specified)   
       "sum (default) | average | minimum | maximum | firstMatching"  
       }  
 ]
}

예: 동의어 맵

검색 서비스에서 동의어 맵을 만든 후 형식 Edm.String 의 필드 또는 Collection(Edm.String) 인덱스에서 할당할 searchable 수 있습니다. 아래 인덱스 정의는 동의어 맵 'mysynonymmap'을 사용하도록 "genre" 필드를 구성합니다.

인덱스 업데이트 를 사용하여 이 속성을 기존 필드에 추가할 수 있습니다. 필드 속성 synonymMaps 은 맵(필드당 하나)을 지정합니다. 언제든지 기존 필드의 속성을 업데이트 synonymMaps 할 수 있습니다.

용어 또는 구(따옴표로 묶음)를 사용하여 평소와 같이 쿼리합니다. Azure AI Search에서 "온수 욕조"와 같은 두 부분으로 구성된 용어는 구로 표현되어야 합니다. 그렇지 않으면 각 용어는 독립적으로 평가됩니다. "온수 욕조"를 쿼리하는 경우 검색 엔진은 자쿠지와 같이 정의한 동의어뿐만 아니라 해당 구를 검색합니다.

POST /indexes?api-version=2020-06-30
{
    "name":"myindex",
    "fields":[
    ...
        {
            "name":"genre",
            "type":"Edm.String",
            "searchable":true,
            "analyzer":"en.lucene",
            "synonymMaps": [
                "mysynonymmap"
            ]
        }
    ]
    ...
}

인덱스 만들기(Azure AI Search REST API)

URI 매개 변수

요청 헤더

요청 본문

필드 정의

응답

예제

추가 정보

추가 리소스