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

이 문서를 사용하여 데이터 평면 및 컨트롤 플레인 작업에 대한 Search Service REST API 및 Search Management REST API의 최신 버전으로 마이그레이션할 수 있습니다.

REST API의 최신 버전은 다음과 같습니다.

대상 지정 작업 REST API 상태
데이터 평면 2026-04-01 안정적인
데이터 평면 2025-11-01-preview 미리 보기
컨트롤 플레인 2025-05-01 안정적인
컨트롤 플레인 2026-03-01-preview 미리 보기

업그레이드 지침은 이전 버전과 호환되지 않는 변경 사항을 해결하여, 기존 코드가 최신 API 버전에서 이전과 동일하게 실행되도록 하는 코드 변경에 중점을 둡니다. 코드가 작동 순서대로 진행되면 최신 기능을 채택할지 여부를 결정할 수 있습니다. 새 기능에 대한 자세한 내용은 Azure AI 검색 참조하세요.

최신 버전이 될 때까지 각 버전을 통해 작업하면서 API 버전을 연속으로 업그레이드하는 것이 좋습니다.

2023-07-01-preview 는 벡터 지원을 위한 첫 번째 REST API였습니다. 이 API 버전을 사용하지 마세요. 이제 더 이상 사용되지 않으며 안정 또는 최신 미리 보기 REST API로 즉시 마이그레이션해야 합니다.

참고

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

업그레이드 시기

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

  • 코드는 사용 중지되거나 지원되지 않는 API 버전을 참조하며 하나 이상의 호환성이 손상되는 변경이 적용됩니다.

  • 인식할 수 없는 속성이 API 응답에서 반환되면 코드가 실패합니다. 애플리케이션이 이해하지 못하는 속성을 무시하는 것이 가장 좋습니다.

  • 코드는 API 요청을 유지하여 새 API 버전으로 다시 보내려고 시도합니다. 예를 들어 애플리케이션이 Search API에서 반환된 연속 토큰을 유지하는 경우 발생할 수 있습니다(자세한 내용은 @search.nextPageParameters에서 확인).

업그레이드 방법

  1. 데이터 평면 버전을 업그레이드하는 경우 새 API 버전에서 릴리스된 내용을 검토합니다.

  2. api-version 요청 헤더에 지정된 매개 변수를 최신 버전으로 업데이트합니다.

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

    Azure SDK 사용하는 경우 각 패키지는 특정 버전의 REST API를 대상으로 합니다. 패키지에서 지원하는 REST API 버전을 확인하려면 해당 변경 로그를 검토합니다. 최신 기능 및 API 개선 사항에 액세스하도록 최신 패키지 버전으로 업데이트합니다.

  3. 데이터 평면 버전을 업그레이드하는 경우 이 문서에 설명된 호환성이 손상되는 변경 내용을 검토하고 해결 방법을 구현합니다. 코드가 사용하는 버전부터 시작해 최신 안정 또는 미리 보기 릴리스에 도달할 때까지, 각 최신 API 버전에서 발생할 수 있는 호환성 손상 변경 사항을 해결합니다.

주요 변경 내용

다음과 같은 주요 변경 내용이 데이터 작업에 적용됩니다.

에이전트 검색의 호환성이 손상되는 변경

2026-04-01 는 에이전트 검색을 위한 안정적인 첫 번째 REST API 버전입니다. 2025-11-01-preview로부터 다음과 같은 중대한 변경 사항이 도입됩니다.

  • 응답 합성, 쿼리 계획 및 구성 가능한 추론 작업이 제거됩니다. 검색은 추출된 접지된 콘텐츠만 반환합니다.

  • 검색 요청 셰이프 변경: messagesintents대체되고 여러 매개 변수의 이름이 변경되거나 제거됩니다.

  • Blob 및 OneLake 기술 원본에 대한 문서 수준 권한 필터링은 지원되지 않습니다.

속성 수준 변경 및 마이그레이션 단계의 전체 목록은 에이전트 검색 코드 마이그레이션을 참조하세요.

지식 에이전트의 주요 변경 내용

지식 에이전트가 2025-05-01-preview에 도입되었습니다. 2025-08-01-preview 에서 targetIndexes새 기술 자료 개체로 대체되었으며 defaultMaxDocsForReranker 다른 API로 대체되었습니다. 2025-11-01-preview에서 더 많은 주요 변경 사항이 도입되었습니다.

속성 수준 변경 및 마이그레이션 단계의 전체 목록은 에이전트 검색 코드 마이그레이션을 참조하세요.

연결 정보를 읽는 클라이언트 코드의 주요 변경 내용

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

  • GET Skillset, GET Index 및 GET Indexer는 더 이상 응답에서 키 또는 연결 속성을 반환하지 않습니다. GET 응답에서 키 또는 연결(중요한 데이터)을 읽는 다운스트림 코드가 있는 경우 이는 호환성이 손상되는 변경입니다.

  • 검색 서비스에 대한 관리자 또는 쿼리 API 키를 검색해야 하는 경우 Search Management 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로 전환하세요.

데이터 평면 업그레이드

업그레이드 지침에서는 최신 이전 버전에서 업그레이드를 가정합니다. 코드가 이전 API 버전을 기반으로 하는 경우 각 연속 버전을 통해 업그레이드하여 최신 버전으로 가져오는 것이 좋습니다.

2026-04-01로 업그레이드

2026-04-01 는 안정적인 최신 REST API 버전입니다. 에이전트 검색을 더 쉽게 하고, 지식 소스를 선택할 수 있으며, 다양한 기술과 기능을 표준 제공 형태로 제공합니다.

업그레이드하기 전에 다음 2026-04-01 주요 변경 내용이 코드에 적용되는지 확인합니다.

  • GenAI 프롬프트 기술 정의httpMethod에서 6개의 속성이 timeoutbatchSizedegreeOfParallelismhttpHeadersauthResourceId제거됩니다. 업그레이드하기 전에 이러한 속성을 제거합니다. 이러한 속성이 여전히 포함된 정의는 오류를 반환합니다 400 Bad Request .

  • 에이전트 자료 검색에는 이제 자체 청구 동의가 필요합니다. 업그레이드하기 전에 semanticSearch=standard가 있는 경우 명시적으로 knowledgeRetrieval=standard을 설정해야 합니다. 자세한 내용은 에이전트릭 리트리벌 청구 사용 설정 또는 해제를 참조하세요.

  • 에이전트 검색 코드가 대상 2025-11-01-preview2026-04-01 인 경우 몇 가지 미리 보기 기능을 제거하고 의도 입력, 추출 출력 및 최소한의 추론을 중심으로 검색을 표준화합니다. 자세한 내용은 에이전트 검색 코드 마이그레이션을 참조하세요.

다른 모든 기존 API의 경우 동작이 변경되지 않습니다. 새 API 버전에서 교환할 수 있으며 코드는 이전과 동일하게 실행됩니다.

2025-11-01-preview로 업그레이드

2025-11-01-preview은 2025-08-01-preview에 구현된 에이전틱 검색에 다음과 같은 호환성 깨짐 변경 사항을 도입합니다.

  • agents를 knowledgebases로 대체합니다. 기술 자료와 관련된 여러 속성이 기술 자료 정의에서 검색 작업으로 이동했습니다.

  • 인덱서 파이프라인을 생성하는 지식 원본에 대한 새 ingestionParameters 개체를 구현하여 기술 원본 속성이 리팩터링됩니다.

속성 수준 변경 및 마이그레이션 단계의 전체 목록은 에이전트 검색 코드 마이그레이션을 참조하세요.

다른 모든 기존 API의 경우 동작이 변경되지 않습니다. 새 API 버전에서 교환할 수 있으며 코드는 이전과 동일하게 실행됩니다.

2025-09-01로 업그레이드

2025-09-01 는 OneLake 인덱서, 문서 레이아웃 기술 및 기타 API에 대한 일반 가용성을 추가하는 안정적인 REST API 버전입니다.

미리 보기 기능을 사용하지 않고 2024-07-01에서 업그레이드하는 경우에는 호환성을 해치는 변경 사항이 없습니다. 안정적인 새 릴리스를 사용하려면 API 버전을 변경하고 코드를 테스트합니다.

2025-08-01-preview로 업그레이드

2025-08-01-preview 에서는 2025-05-01-preview로 생성된 지식 에이전트에 중대한 변경 사항이 발생합니다.

  • targetIndexes를 knowledgeSources로 대체합니다.
  • 교체하지 않고 제거합니다 defaultMaxDocsForReranker .

그렇지 않으면 기존 API에 대한 동작이 변경되지 않습니다. 새 API 버전에서 교환할 수 있으며 코드는 이전과 동일하게 실행됩니다.

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

2025-05-01-preview 는 새로운 기능을 제공하지만 기존 API에는 동작이 변경되지 않습니다. 새 API 버전에서 교환할 수 있으며 코드는 이전과 동일하게 실행됩니다.

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

2025-03-01-preview 는 새로운 기능을 제공하지만 기존 API에는 동작이 변경되지 않습니다. 새 API 버전에서 교환할 수 있으며 코드는 이전과 동일하게 실행됩니다.

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

2024-11-01-preview 쿼리 다시 쓰기, 문서 레이아웃 기술, 기술 처리를 위한 키 없는 청구, Markdown 구문 분석 모드 및 압축된 벡터에 대한 다시 점수 지정 옵션

2024-09-01-preview에서 업그레이드하는 경우 새 API 버전으로 바꿀 수 있으며, 코드는 이전과 동일하게 실행됩니다.

그러나 새 버전은 다음과 같은 구문 변경을 도입합니다 vectorSearch.compressions.

  • 다음으로 대체합니다.rerankWithOriginalVectorsenableRescoring
  • defaultOversampling를 새 rescoringOptions 속성 개체로 이동

내부 API 매핑으로 인해 이전 버전과의 호환성이 유지되지만 새 미리 보기 버전을 채택하는 경우 구문을 변경하는 것이 좋습니다. 구문 비교는 스칼라 또는 이진 양자화를 사용하여 벡터 압축을 참조하세요.

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

2024-09-01-preview 는 text embedding-3 모델에 대한 Matryoshka 표현 학습(MRL) 압축, 하이브리드 쿼리에 대한 대상 벡터 필터링, 디버깅을 위한 벡터 하위 점수 세부 정보 및 텍스트 분할 기술을 위한 토큰 청크를 추가합니다.

2024-05-01-preview에서 업그레이드하는 경우, 새로운 API 버전으로 전환할 수 있으며 코드는 이전과 동일하게 실행됩니다.

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 Microsoft OneLake, 이진 벡터 및 기타 포함 모델에 대한 인덱서가 추가됩니다.

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

  1. 코드베이스에서 AzureOpenAIEmbedding 참조를 검색합니다.

  2. modelName을(를) "text-embedding-ada-002"로 설정하고 dimensions을(를) "1536"으로 설정합니다.

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

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

2023-10-01-preview에서 업그레이드하는 경우, 변경 사항은 없습니다. 그러나 한 가지 동작 차이점이 있습니다: 2023-11-01 및 그 이후의 미리 보기에서 vectorFilterMode이 필터 식에 대해 사후 필터에서 프리필터로 변경되었습니다.

  1. 코드베이스에서 vectorFilterMode 참조를 검색합니다.

  2. 속성이 명시적으로 설정된 경우 아무 작업도 필요하지 않습니다. 기본값을 사용하는 경우 새 기본 동작은 쿼리 실행 전에 필터링하는 것입니다. 사후 쿼리 필터링을 원하는 경우 이전 동작을 유지하기 위해 사후 필터로 명시적으로 설정합니다 vectorFilterMode .

2023-11-01로 업그레이드

2023-11-01 는 일반 릴리스입니다. 이전 프리뷰 기능인 의미 체계 순위 및 벡터 지원이 이제 일반적으로 사용할 수 있습니다.

호환성이 손상되는 변경 사항은 2023-10-01-preview에서는 없지만, 2023-07-01-preview에서 2023-11-01로의 호환성에 영향을 주는 여러 가지 변경 사항이 있습니다. 자세한 내용은 2023-07-01-preview에서 업그레이드를 참조하세요.

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

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

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

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

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

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

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

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

Azure 포털은 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의 벡터 필드, 구성 및 쿼리를 마이그레이션합니다.

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

  2. 벡터 검색 구성을 수정합니다. 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"
      }
    ]
  }

  3. 벡터 필드 정의를 수정하여 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"
  }

  4. Create 또는 Update Index를 호출하여 변경 내용을 게시합니다.

  5. 검색 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"
}

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

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

이 버전에는 하나의 주요 변경 내용과 몇 가지 동작 차이점이 있습니다. 일반적으로 사용할 수 있는 기능은 다음과 같습니다.

  • 기술 세트를 통해 생성된 보강된 콘텐츠의 영구 스토리지인 지식 저장소는 다운스트림 분석 및 다른 애플리케이션을 통한 처리를 위해 생성됩니다. 지식 저장소는 Azure AI 검색 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 값이 마지막에 표시됩니다. null 값이 정렬되는 방식을 처리하는 코드를 작성한 경우 이 변경 사항에 유의하세요.

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

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

  • 자동 완성은 부분적으로 입력된 용어를 완성하는 자동 입력 기능입니다.
  • 복합 형식 은 검색 인덱스에서 구조화된 개체 데이터에 대한 기본 지원을 제공합니다.
  • Azure Blob 인덱싱의 일부인 JsonLines 구문 분석 모드는 줄 바꿈으로 구분된 JSON 엔터티당 하나의 검색 문서를 만듭니다.
  • AI 보강 은 Foundry 도구의 AI 보강 엔진을 사용하는 인덱싱을 제공합니다.

주요 변경 내용

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

  1. Azure Cosmos DB 형식 속성입니다. NoSQL API에 대한 Azure Cosmos DB 데이터 원본을 대상으로 하는 인덱서의 경우, "type": "documentdb"를 "type": "cosmosdb"로 바꾸십시오.

  2. 인덱서 오류 처리에 속성에 대한 참조가 status 포함된 경우 제거해야 합니다. 유용한 정보를 제공하지 않아 오류 응답에서 상태를 제거했습니다.

  3. 데이터 원본 연결 문자열은 응답에서 더 이상 반환되지 않습니다. API 버전 2019-05-06 이상 2019-05-06-Preview 에서 데이터 원본 API는 REST 작업의 응답으로 더 이상 연결 문자열을 반환하지 않습니다. 이전 API 버전에서는 POST를 사용하여 생성된 데이터 소스의 경우, Azure AI 검색은 201을 반환한 후, 일반 텍스트로 연결 문자열을 포함한 OData 응답을 반환했습니다.

  4. 명명된 엔터티 인식 인지 기술이 사용 중지되었습니다. 코드에서 이름 엔터티 인식 기술을 호출한 경우 호출이 실패합니다. 대체 기능은 V3(엔터티 인식 기술)입니다. 사용되지 않는 기술의 권장 사항에 따라 지원되는 기술로 마이그레이션합니다.

복합 형식 업그레이드

API 버전은 2019-05-06 복잡한 형식에 대한 공식적인 지원을 추가했습니다. 코드가 2017-11-11-Preview 또는 2016-09-01-Preview에서 복잡한 형식 동등성에 대한 이전 권장 사항을 구현한 경우 버전 2019-05-06 부터 몇 가지 새롭고 변경된 제한이 있습니다.

  • 하위 필드의 깊이 및 인덱스당 복합 컬렉션 수에 대한 제한이 낮아졌습니다. 미리 보기 api-version을 사용하여 이러한 제한을 초과하는 인덱스를 만든 경우 API 버전을 2019-05-06 사용하여 업데이트하거나 다시 만들려는 시도가 실패합니다. 이 상황에서 자신을 발견하면 새 제한에 맞게 스키마를 다시 디자인한 다음 인덱스를 다시 작성해야 합니다.

  • 문서당 복합 컬렉션의 요소 수에 대한 api-version 2019-05-06 부터 새로운 제한이 있습니다. 미리 보기 api-version을 사용하여 이러한 제한을 초과하는 문서로 인덱스를 만든 경우 api-version 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 버전을 사용하여 새 형식으로 업데이트해야 API 버전 2017-11-11-Preview 2019-05-06을 사용하여 관리할 수 있습니다.

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

  1. GET 요청을 수행하여 인덱스 검색 이미 새 형식인 경우 완료된 것입니다.

  2. 인덱스를 플랫 형식에서 새 형식으로 변환합니다. 이 작업을 작성할 때 사용할 수 있는 샘플 코드가 없으므로 이 작업에 대한 코드를 작성해야 합니다.

  3. PUT 요청을 수행하여 인덱스가 새 형식으로 업데이트됩니다. 기존 인덱스의 실제 식에 영향을 주는 변경 내용은 업데이트 인덱스 API에서 허용되지 않으므로 필드의 검색 가능성/필터링 가능성과 같은 인덱스의 다른 세부 정보를 변경하지 마세요.

참고

Azure 포털에서 이전 "플랫" 형식으로 만든 인덱스를 관리할 수 없습니다. 가장 빠른 편의를 위해 인덱스를 "플랫" 표현에서 "트리" 표현으로 업그레이드합니다.

컨트롤 플레인 업그레이드

적용 대상:2014-07-31-Preview, 2015-02-28및 2015-08-19

listQueryKeys 이전 Search Management API 버전에 대한 GET 요청은 이제 더 이상 사용되지 않습니다. POST 요청을 사용listQueryKeys하려면 가장 최근의 안정적인 컨트롤 플레인 API 버전으로 마이그레이션하는 것이 좋습니다.

  1. 기존 코드에서 매개 변수를 api-version 최신 버전(2025-05-01)으로 변경합니다.

  2. GET 요청을 POST 다음과 같이 다시 구성합니다.

    POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/listQueryKeys?api-version=2025-05-01
Authorization: Bearer {{token}}

  3. Azure SDK 사용하는 경우 최신 버전으로 업그레이드하는 것이 좋습니다.

다음 단계

Search REST API 참조 설명서를 검토합니다. 문제가 발생하는 경우 Stack Overflow 에 대한 도움말을 요청하거나 지원에 문의하세요.

Search Service REST API 참조

  • Last updated on