인덱스 업데이트(Azure AI Search REST API)

  • 아티클

기존 인덱스를 수정하려면 일반적으로 다음 스키마 변경 내용을 제외하고 인덱스 삭제 및 다시 작성이 필요합니다.

  • 필드 컬렉션에 새 필드 추가

  • 제안기에서 새로 만든 필드 추가

  • 점수 매기기 프로필 추가 또는 변경

  • 암호화 키 추가 또는 변경

  • 새 사용자 지정 분석기 추가

  • CORS 옵션 변경

  • 다음 세 가지 수정 사항 중 하나를 사용하여 기존 필드를 변경합니다.

    • 변경 retrievable (값이 true 또는 false임)
    • 변경 searchAnalyzer (쿼리 시 사용)
    • 추가 또는 변경 synonymMaps (쿼리 시 사용)

이러한 업데이트를 추가하려면 요청 URI에 인덱스 이름을 입력합니다. 요청 본문에 수정 내용과 함께 완전히 지정된 인덱스 정의를 포함합니다.

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

기존 필드와 대부분의 필드 특성은 삭제하거나 변경할 수 없으며 제안기에 필드를 추가할 수도 없습니다. 새로 만든 필드만 에 suggester추가할 수 있습니다.

새 필드가 추가되면 모든 기존 문서는 해당 필드에 대한 null 값을 자동으로 가져옵니다. 두 가지 중 하나가 발생할 때까지 다른 스토리지 공간이 소비되지 않습니다. 새 필드에 값이 제공되거나(병합 사용) 새 문서가 추가됩니다.

기존 분석기, 토큰라이저, 토큰 필터 및 char 필터를 변경할 수 없습니다. 이미 기존 인덱스로 새 항목을 추가하는 것은 인덱스 업데이트 요청에서 플래그가 allowIndexDowntime 켜져 있는 경우에만 가능합니다. 특히 REST API 버전 2023-07-01 미리 보기 이전의 벡터 검색을 지원하지 않는 API를 사용하여 설정된 기존 인덱스에 초기 벡터 필드를 추가할 때도 동일한 규칙이 적용됩니다.

PUT https://[search service name].search.windows.net/indexes/[index name]?api-version=[api-version]&allowIndexDowntime=true

이 작업은 몇 초 동안 인덱스 오프라인으로 전환됩니다. 인덱스가 오프라인인 동안 인덱싱 및 쿼리 요청이 실패합니다. 인덱스가 다시 온라인 상태가 된 후 몇 분 동안 성능 및 쓰기 작업이 일시적으로 손상될 수 있습니다.

URI 매개 변수

매개 변수 Description
서비스 이름 필수 사항입니다. 검색 서비스의 고유한 사용자 정의 이름으로 설정합니다.
인덱스 이름 필수 사항입니다. 요청 URI는 업데이트할 인덱스의 이름을 지정합니다.
api-version 필수 사항입니다. 지원되는 버전 목록은 API 버전을 참조하세요.
allowIndexDowntime 선택 사항입니다. False(기본값). 분석기, 토큰화기, 토큰 필터, char 필터 또는 유사성 속성 추가 또는 수정과 같은 특정 업데이트의 경우 true로 설정합니다. 인덱스는 업데이트 중에 오프라인으로 전환됩니다(일반적으로 몇 초 이하).

요청 헤더

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

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

요청 본문

요청 본문 구문은 인덱스 만들기와 동일합니다.

기존 인덱스를 업데이트할 때 본문에는 유지하려는 원래 정의를 포함하여 전체 스키마 정의가 포함되어야 합니다. 일반적으로 업데이트에 가장 적합한 패턴은 GET을 사용하여 인덱스 정의를 검색하고 수정한 다음 PUT으로 업데이트하는 것입니다.

응답

요청이 성공하면 "204 콘텐츠 없음"이 표시됩니다.

기본적으로 응답 본문은 비어 있습니다. 그러나 요청 헤더가 Prefer 로 return=representation설정된 경우 응답 본문에는 업데이트된 인덱스의 JSON이 포함됩니다. 이 경우 코드의 성공 상태 "200 OK"입니다.

추가 정보