Azure AI 검색에서 최신 REST API로 업그레이드

아티클
09/03/2024

이 문서를 사용하여 데이터 평면 호출을 검색 REST API의 새로운 버전으로 마이그레이션합니다.

2024-07-01은 최신 안정 버전입니다.
2024-05-01-preview는 최신 미리 보기 API 버전입니다.

업그레이드 지침은 기존 코드가 이전과 동일하지만 최신 API 버전에서 실행되도록 이전 버전의 호환성이 손상되는 변경을 통해 발생하는 코드 변경에 중점을 줍니다. 코드가 작동 순서대로 진행되면 최신 기능을 채택할지 여부를 결정할 수 있습니다. 새로운 기능에 관한 자세한 내용은 벡터 코드 샘플 및 새로운 기능을 참조하세요.

API 버전을 연속으로 업그레이드하고 최신 버전이 나올 때까지 각 버전을 진행하는 것이 좋습니다.

2023-07-01-preview는 벡터 지원을 위한 최초의 REST API였습니다. 이 API 버전을 사용하지 마세요. 이제 더 이상 사용되지 않으므로 즉시 안정적이거나 새로운 미리 보기 REST API로 마이그레이션해야 합니다.

참고 항목

이제 REST API 참조 문서의 버전이 관리됩니다. 버전별 콘텐츠의 경우 참조 페이지를 연 다음 목차 오른쪽에 있는 선택기를 사용하여 버전을 선택합니다.

업그레이드 시기

Azure AI Search는 최후의 수단으로 이전 버전과의 호환성을 중단합니다. 업그레이드는 다음과 같은 경우에 필요합니다.

사용자의 코드는 사용 중지되거나 지원되지 않는 API 버전을 참조하며 하나 이상의 호환성이 손상되는 변경이 적용됩니다. 코드가 벡터의 경우 2023-07-10-preview, 의미 순위매기기의 경우 2020-06-01-preview, 사용되지 않는 기술 및 해결 방법의 경우 2019-05-06을 대상으로 하는 경우 호환성이 손상되는 변경을 해결해야 합니다.
인식할 수 없는 속성이 API 응답에 반환되는 경우 코드가 실패합니다. 애플리케이션이 이해하지 못하는 속성을 무시하는 것이 가장 좋습니다.
코드는 API 요청을 보관하고 새 API 버전으로 다시 전송하려 합니다. 예를 들어 애플리케이션이 검색 API에서 반환된 연속 토큰을 보관하는 경우 이런 현상이 발생할 수 있습니다(자세한 내용은 검색 API 참조의 @search.nextPageParameters를 참조).

업그레이드 방법

각 API 버전에 대한 릴리스 정보를 검토합니다.
요청 헤더에 지정된 api-version 매개 변수를 최신 버전으로 업데이트합니다.

REST API를 직접 호출하는 애플리케이션 코드에서 기존 버전의 모든 인스턴스를 검색한 다음 새 버전으로 바꿉니다. REST 호출 구성에 대한 자세한 내용은 빠른 시작: REST 사용을 참조하세요.

Azure SDK를 사용하는 경우 해당 패키지는 특정 버전의 REST API를 대상으로 합니다. 패키지 업데이트는 REST API 업데이트와 동시에 이루어질 수 있지만, 각 SDK는 Azure AI 검색 REST API 버전과는 별개로 제공되는 자체 릴리스 일정에 따릅니다. SDK 패키지의 변경 로그를 확인하여 패키지 릴리스가 최신 REST API 버전을 대상으로 하는지 확인합니다.
이 문서에 설명된 호환성이 손상되는 변경을 검토하고 해결 방법을 구현합니다. 코드에서 사용하는 버전으로 시작하고, 최신의 안정적인 릴리스 또는 미리 보기 릴리스 버전에 도착할 때까지 각 최신 API 버전에서 호환성이 손상되는 변경을 해결합니다.

연결 정보를 읽는 클라이언트 코드에 대한 호환성이 손상되는 변경

2024년 3월 29일부터 적용되며 모든 지원되는 REST API에 적용됩니다.

GET Skillset, GET Index 및 GET Indexer는 더 이상 응답에 키나 연결 속성을 반환하지 않습니다. GET 응답에서 키나 연결(중요한 데이터)을 읽는 다운스트림 코드가 있는 경우 이는 호환성이 손상되는 변경입니다.
쿼리 서비스에 대한 관리 또는 쿼리 API 키를 쿼리해야 하는 경우 관리 REST API를 사용합니다.
Azure Storage 또는 Azure Cosmos DB와 같은 다른 Azure 리소스의 연결 문자열을 검색해야 하는 경우 해당 리소스의 API와 게시된 지침을 사용하여 정보를 가져옵니다.

의미 순위매기기의 호환성이 손상되는 변경

의미 순위매기기는 2023-11-01에 일반 공급됩니다. 이전 릴리스의 의미 순위매기기에 대한 호환성이 손상되는 변경은 다음과 같습니다.

2020-06-01-preview 이후의 모든 버전에서: semanticConfiguration은 L2 순위 지정에 사용할 필드를 지정하는 메커니즘으로 searchFields를 바꿉니다.
모든 API 버전의 경우 2023년 7월 14일 Microsoft 호스팅 의미 체계 모델 업데이트로 인해 의미 순위매기기가 언어에 구애받지 않게 되어 queryLanguage 속성이 효과적으로 해제되었습니다. 코드에는 "호환성이 손상되는 변경"이 없지만 속성은 무시됩니다.

semanticConfiguration을 사용하도록 코드를 전환하려면 미리 보기 버전에서 마이그레이션을 참조하세요.

2024-07-01로 업그레이드

2024-07-01은 일반 릴리스입니다. 통합 청크 및 벡터화(텍스트 분할 기술, AzureOpenAIEmbedding 기술), AzureOpenAIEmbedding을 기반으로 하는 쿼리 벡터라이저, 벡터 압축(스칼라 양자화, 이진 양자화, 저장된 속성, 좁은 데이터 형식) 등 이전의 미리 보기 기능이 이제 일반 공급됩니다.

2024-05-01-preview에서 안정적인 버전으로 업그레이드하는 경우 호환성이 손상되는 변경이 없습니다. 안정적인 새 릴리스를 사용하려면 API 버전을 변경하고 코드를 테스트합니다.

2023-11-01에서 직접 업그레이드하는 경우 호환성이 손상되는 변경이 발생합니다. 최신 미리 보기 각각에 대해 설명한 단계에 따라 2023-11-01에서 2024-07-01로 마이그레이션합니다.

2024-05-01-preview로 업그레이드

2024-05-01-preview는 OneLake 인덱스, 이진 파일 벡터 지원 및 더 많은 포함 모델 지원을 추가합니다.

2024-03-01-preview에서 업그레이드하는 경우 이제 AzureOpenAIEmbedding 기술에 모델 이름과 차원 속성이 필요합니다.

코드베이스에서 AzureOpenAIEmbedding 참조를 검색합니다.
modelName을 "text-embedding-ada-002"로 설정하고 dimensions를 "1536"으로 설정합니다.

2024-03-01-preview로 업그레이드

2024-03-01-preview는 좁은 데이터 형식, 스칼라 양자화 및 벡터 스토리지 옵션을 추가합니다.

2023-10-01-preview에서 업그레이드하는 경우 호환성이 손상되는 변경은 없습니다. 그러나 한 가지 동작 차이가 있습니다. 2023-11-01 및 최신 미리 보기의 경우 필터 식에 대한 vectorFilterMode 기본값이 사후 필터에서 사전 필터로 변경되었습니다.

코드베이스에서 vectorFilterMode 참조를 검색합니다.
속성이 명시적으로 설정된 경우에는 작업이 필요하지 않습니다. 기본값을 사용한 경우 새로운 기본 동작은 쿼리 실행 전에 필터링하는 것입니다. 쿼리 후 필터링을 원하는 경우 명시적으로 vectorFilterMode를 postfilter로 설정하여 이전 동작을 보존합니다.

2023-11-01로 업그레이드

2023-11-01은 일반 릴리스입니다. 의미 순위매기기, 벡터 인덱스 및 쿼리 지원과 같은 이전의 미리 보기 기능이 이제 일반 공급됩니다.

2023-10-01-preview에서 호환성이 손상되는 변경은 없지만, 2023-07-01-preview에서 2023-11-01까지 호환성이 손상되는 변경이 여러 가지 있습니다. 자세한 내용은 2023-07-01-미리보기에서 업그레이드를 참조하세요.

안정적인 새 릴리스를 사용하려면 API 버전을 변경하고 코드를 테스트합니다.

2023-10-01-preview로 업그레이드

2023-10-01-preview는 인덱싱 중 기본 제공 데이터 청크 및 벡터화와 기본 제공 쿼리 벡터화를 추가한 최초의 미리 보기 버전입니다. 또한 이전 버전의 벡터 인덱싱 및 쿼리도 지원합니다.

이전 버전에서 업그레이드하는 경우 다음 섹션에 해당 단계가 있습니다.

2023-07-01-preview에서 업그레이드

이 API 버전을 사용하지 마세요. 최신 API 버전과 호환되지 않는 벡터 쿼리 구문을 구현합니다.

2023-07-01-preview는 이제 더 이상 사용되지 않으므로 이 버전을 기반으로 새 코드를 작성해서는 안 되며 어떤 상황에서도 이 버전으로 업그레이드해서는 안 됩니다. 이 섹션에서는 2023-07-01-preview에서 최신 API 버전으로의 마이그레이션 경로를 설명합니다.

벡터 인덱스에 대한 포털 업그레이드

Azure Portal은 2023-07-01-preview 인덱스에 대한 원클릭 업그레이드 경로를 지원합니다. 벡터 필드를 검색하고 마이그레이션 단추를 제공합니다.

마이그레이션 경로는 2023-07-01-preview에서 2024-05-01-preview까지입니다.
업데이트는 벡터 필드 정의 및 벡터 검색 알고리즘 구성으로 제한됩니다.
업데이트는 단방향입니다. 업그레이드를 취소할 수 없습니다. 인덱스가 업그레이드되면 2024-05-01-preview 이상을 사용하여 인덱스를 쿼리해야 합니다.

벡터 쿼리 구문을 업그레이드하기 위한 포털 마이그레이션은 없습니다. 쿼리 구문 변경 내용은 코드 업그레이드를 참조하세요.

마이그레이션을 선택하기 전에 먼저 JSON 편집을 선택하여 업데이트된 스키마를 검토합니다. 코드 업그레이드 섹션에 설명된 변경 내용을 준수하는 스키마를 찾아야 합니다. 포털 마이그레이션은 하나의 벡터 검색 알고리즘 구성으로 인덱스만 처리합니다. 이는 2023-07-01-preview 벡터 검색 알고리즘에 매핑되는 기본 프로필을 만듭니다. 여러 벡터 검색 구성이 있는 인덱스에는 수동 마이그레이션이 필요합니다.

벡터 인덱스 및 쿼리에 대한 코드 업그레이드

벡터 검색 지원은 인덱스 만들기 또는 업데이트(2023-07-01-preview)에 도입되었습니다.

2023-07-01-preview에서 최신 안정 버전이나 미리 보기 버전으로 업그레이드하려면 다음이 필요합니다.

인덱스의 벡터 구성 이름 바꾸기 및 재구성
벡터 쿼리 다시 쓰기

2023-07-01-preview에서 벡터 필드, 구성 및 쿼리를 마이그레이션하려면 이 섹션의 지침을 사용합니다.

기존 정의를 검색하려면 인덱스 가져오기를 호출합니다.

벡터 검색 구성을 수정합니다. 2023-11-01 이상 버전에서는 벡터 관련 구성을 하나의 이름으로 묶는 벡터 프로필의 개념이 도입되었습니다. 최신 버전에서는 algorithmConfigurations의 이름도 algorithms로 변경됩니다.

algorithmConfigurations의 이름을 algorithms로 바꿉니다. 이는 배열의 이름만 바꿉니다. 콘텐츠는 이전 버전과 호환됩니다. 이는 기존 HNSW 구성 매개 변수를 사용할 수 있음을 의미합니다.
profiles를 추가하여 각각에 대한 이름과 알고리즘 구성을 제공합니다.

마이그레이션 전(2023-07-01-preview):

  "vectorSearch": {
    "algorithmConfigurations": [
        {
            "name": "myHnswConfig",
            "kind": "hnsw",
            "hnswParameters": {
                "m": 4,
                "efConstruction": 400,
                "efSearch": 500,
                "metric": "cosine"
            }
        }
    ]}

마이그레이션 후(2023-11-01):

  "vectorSearch": {
    "algorithms": [
      {
        "name": "myHnswConfig",
        "kind": "hnsw",
        "hnswParameters": {
          "m": 4,
          "efConstruction": 400,
          "efSearch": 500,
          "metric": "cosine"
        }
      }
    ],
    "profiles": [
      {
        "name": "myHnswProfile",
        "algorithm": "myHnswConfig"
      }
    ]
  }

벡터 필드 정의를 수정하여 vectorSearchConfiguration을 vectorSearchProfile로 바꿉니다. 프로필 이름이 알고리즘 구성 이름이 아닌 새 벡터 프로필 정의로 확인되는지 확인합니다. 다른 벡터 필드 속성은 변경되지 않습니다. 예를 들어, 필터링, 정렬 또는 패싯이 가능하지 않으며 분석기, 노멀라이저 또는 동의어 맵을 사용할 수도 없습니다.

이전(2023-07-01-preview):

  {
      "name": "contentVector",
      "type": "Collection(Edm.Single)",
      "key": false,
      "searchable": true,
      "retrievable": true,
      "filterable": false,  
      "sortable": false,  
      "facetable": false,
      "analyzer": "",
      "searchAnalyzer": "",
      "indexAnalyzer": "",
      "normalizer": "",
      "synonymMaps": "", 
      "dimensions": 1536,
      "vectorSearchConfiguration": "myHnswConfig"
  }

이후(2023-11-01):

  {
    "name": "contentVector",
    "type": "Collection(Edm.Single)",
    "searchable": true,
    "retrievable": true,
    "filterable": false,  
    "sortable": false,  
    "facetable": false,
    "analyzer": "",
    "searchAnalyzer": "",
    "indexAnalyzer": "",
    "normalizer": "",
    "synonymMaps": "", 
    "dimensions": 1536,
    "vectorSearchProfile": "myHnswProfile"
  }

변경 내용을 게시하려면 인덱스 만들기 또는 업데이트를 호출합니다.
쿼리 구문을 변경하려면 검색 POST를 수정합니다. 이 API 변경으로 다형성 벡터 쿼리 형식을 지원할 수 있습니다.
- vectors의 이름을 vectorQueries로 바꿉니다.
- 각 벡터 쿼리에 대해 kind를 추가하고 이를 vector로 설정합니다.
- 각 벡터 쿼리에 대해 value의 이름을 vector로 바꿉니다.
- 선택적으로 필터 식을 사용하는 경우 vectorFilterMode를 추가합니다. 기본값은 2023-10-01 이후에 만들어진 인덱스의 사전 필터입니다. 해당 날짜 이전에 만들어진 인덱스는 필터 모드 설정 방법에 관계없이 사후 필터만 지원합니다.
이전(2023-07-01-preview):
```
{
    "search": (this parameter is ignored in vector search),
    "vectors": [
      {
        "value": [
            0.103,
            0.0712,
            0.0852,
            0.1547,
            0.1183
        ],
        "fields": "contentVector",
        "k": 5
      }
    ],
    "select": "title, content, category"
}
```
이후(2023-11-01):
```
{
  "search": "(this parameter is ignored in vector search)",
  "vectorQueries": [
    {
      "kind": "vector",
      "vector": [
        0.103,
        0.0712,
        0.0852,
        0.1547,
        0.1183
      ],
      "fields": "contentVector",
      "k": 5
    }
  ],
  "vectorFilterMode": "preFilter",
  "select": "title, content, category"
}
```

이러한 단계를 수행하면 2023-11-01 안정적인 API 버전 또는 최신 미리 보기 API 버전으로의 마이그레이션이 완료됩니다.

2020-06-30으로 업그레이드

이 버전에는 한 가지 호환성이 손상되는 변경과 몇 가지 동작 차이가 있습니다. 일반 공급한 기능은 다음과 같습니다.

기술 세트를 통해 생성되고, 다운스트림 분석 및 다른 애플리케이션을 통한 처리를 위해 생성된 보강 콘텐츠의 영구 스토리지인 지식 저장소. 지식 저장소는 Azure AI Search REST API를 통해 생성되지만 Azure Storage에 상주합니다.

주요 변경 내용

코드에 다음 기능이 포함된 경우 이전 API 버전에 대해 작성된 코드는 2020-06-30 이상에서 중단됩니다.

필터 식의 모든 Edm.Date 리터럴(2020-12-12와 같이 연-월-일로 구성된 날짜)은 Edm.DateTimeOffset 형식(2020-12-12T00:00:00Z)을 따라야 합니다. 이 변경은 표준 시간대 차이로 인해 발생하는 잘못되었거나 예기치 않은 쿼리 결과를 처리하는 데 필요했습니다.

동작 변경

BM25 순위 지정 알고리즘은 이전 순위 지정 알고리즘을 최신 기술로 대체합니다. 2019년 이후에 만들어진 서비스는 이 알고리즘을 자동으로 사용합니다. 이전 서비스의 경우 새 알고리즘을 사용하려면 매개 변수를 설정해야 합니다.
이 버전에서는 null 값에 대해 정렬된 결과가 변경되었고, 정렬이 asc이면 null 값이 처음에 표시되고 정렬이 desc이면 마지막에 표시됩니다. null 값을 정렬하는 방법을 처리하는 코드를 작성한 경우 이 변경 내용을 알고 있어야 합니다.

2019-05-06으로 업그레이드

이 API 버전에서 일반 공급되는 기능은 다음과 같습니다.

자동 완성 - 부분적으로 지정된 용어 입력을 완성하는 미리 입력 기능입니다.
복합 형식 - 검색 인덱스의 구조화된 개체 데이터에 대한 네이티브 지원을 제공합니다.
Azure Blob 인덱싱의 일부인 JsonLines 구문 분석 모드는 JSON 엔터티마다 하나의 검색 문서를 만들고, 이 문서는 새로운 행으로 구분됩니다.
AI 보강은 Azure AI 서비스의 AI 보강 엔진을 사용하는 인덱싱을 제공합니다.

호환성이 손상되는 변경

이전 API 버전에 대해 작성된 코드는 다음 기능이 포함된 경우 2019-05-06 이상에서 중단됩니다.

Azure Cosmos DB의 Type 속성입니다. Azure Cosmos DB for NoSQL API 데이터 원본을 대상으로 하는 인덱서의 경우 "type": "documentdb"을(를) "type": "cosmosdb"(으)로 변경합니다.
인덱서 오류 처리에 status 속성에 대한 참조가 포함된 경우 제거해야 합니다. 유용한 정보를 제공하지 않아 오류 응답에서 상태를 제거했습니다.
데이터 원본 연결 문자열은 응답에서 더 이상 반환되지 않습니다. API 버전 2019-05-06 및 2019-05-06-Preview부터 데이터 원본 API는 더 이상 REST 작업의 응답으로 연결 문자열을 반환하지 않습니다. 이전 API 버전에서는 POST를 사용하여 만든 데이터 원본에 대해 Azure AI 검색이 201을 반환한 다음, OData 응답을 반환했습니다. 여기에는 일반 텍스트 형식의 연결 문자열이 포함되어 있었습니다.
명명된 엔터티 인식 기술이 사용 중지되었습니다. 코드에서 이름 엔터티 인식 기술을 호출하면 호출이 실패합니다. 대체 기능은 엔터티 인식 기술(V3)입니다. 지원되는 기술로 마이그레이션하려면 지원되지 않는 기술의 권장 사항을 따릅니다.

복합 형식 업그레이드

API 버전 2019-05-06에는 복합 형식에 대한 공식 지원이 추가되었습니다. 코드에서 2017-11-11-Preview 또는 2016-09-01-Preview와 같은 복합 형식에 대한 이전 권장 사항을 구현한 경우, 2019-05-06 버전부터 도입된 새로운 제한 사항과 변경된 제한 사항에 주의해야 합니다.

하위 필드 수준 및 인덱스당 복합 컬렉션 수에 대한 제한 사항이 감소했습니다. 미리 보기 API 버전을 사용하여 이러한 제한 사항을 초과하는 인덱스를 만든 경우, API 버전 2019-05-06을 사용하여 해당 인덱스를 업데이트하거나 다시 만들려고 하면 실패합니다. 이런 상황에 처한다면 새로운 한도 내에 맞도록 스키마를 다시 디자인한 다음 인덱스를 다시 빌드해야 합니다.
API 버전 2019-05-06부터 문서당 복합 컬렉션의 요소 수에 대한 새로운 제한 사항이 있습니다. 미리 보기 API 버전을 사용하여 이러한 제한 사항을 초과하는 인덱스를 문서에 만든 경우, API 버전 2019-05-06을 사용하여 해당 데이터의 인덱스를 다시 작성하려고 하면 실패합니다. 이 상황에 처한 경우 데이터의 인덱스를 다시 작성하기 전에 문서당 복합 컬렉션 요소 수를 줄여야 합니다.

자세한 내용은 Azure AI 검색 서비스 제한을 참조하세요.

이전 복합 형식 구조를 업그레이드하는 방법

코드가 이전 미리 보기 API 버전 중 하나에서 복합 형식을 사용 하는 경우 다음과 같은 인덱스 정의 형식을 사용할 수 있습니다.

{
  "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" },
    { "name": "Address/StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true },
    { "name": "Address/City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/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)" }, 
    { "name": "Rooms/Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene" },
    { "name": "Rooms/Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene" },
    { "name": "Rooms/Type", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/BaseRate", "type": "Edm.Double", "filterable": true, "facetable": true },
    { "name": "Rooms/BedOptions", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/SleepsCount", "type": "Edm.Int32", "filterable": true, "facetable": true },
    { "name": "Rooms/SmokingAllowed", "type": "Edm.Boolean", "filterable": true, "facetable": true },
    { "name": "Rooms/Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "facetable": true, "analyzer": "tagsAnalyzer" }
  ]
}

인덱스 필드를 정의하기 위한 새로운 트리형 형식이 API 버전 2017-11-11-Preview에 도입되었습니다. 새 형식에서 각 복합 필드에는 하위 필드가 정의된 필드 컬렉션이 있습니다. API 버전 2019-05-06에서 이 새 형식은 배타적으로 사용되며, 이전 형식을 사용하여 인덱스를 만들거나 업데이트하려는 시도가 실패합니다. 이전 형식을 사용하여 생성된 인덱스가 있는 경우 API 버전 2017-11-11-Preview를 사용하여 새 형식으로 업데이트해야 API 버전 2019-05-06을 사용하여 관리할 수 있습니다.

API 버전 2017-11-11-Preview를 사용하여 다음 단계에 따라 플랫 인덱스를 새 형식으로 업데이트할 수 있습니다.

GET 요청을 수행하여 인덱스를 검색합니다. 이미 새 형식이면 완료된 것입니다.
인덱스를 플랫 형식에서 새 형식으로 변환합니다. 이 문서의 작성 시점을 기준으로 현재 사용할 수 있는 샘플 코드는 없으므로 이 작업에 대한 코드를 작성해야 합니다.
PUT 요청을 수행하여 인덱스를 새 형식으로 업데이트합니다. 기존 인덱스의 물리적 식에 영향을 주는 변경 내용은 인덱스 업데이트 API에서 허용되지 않으므로 필드의 검색 가능성/필터링 가능성과 같은 인덱스의 다른 세부 정보를 변경하지 마세요.