Azure AI 검색에서 별칭 인덱스를 만들기

메모

Azure AI 검색 Azure 포털, REST API 및 Azure SDK 통해 사용할 수 있습니다. 또한 엔터프라이즈 콘텐츠를 Microsoft Foundry 포털의 에이전트에 대해 재사용 가능한 사용 권한 인식 기술 자료로 변환하는 관리되는 기술 계층인 Foundry IQ를 뒷받침합니다.

Azure AI 검색 인덱스 별칭은 검색 인덱스의 보조 이름입니다. 검색 인덱스에 매핑되는 별칭을 생성하면, 별칭이 없는 경우에는 인덱스 이름을 참조하던 위치에서 그 인덱스 이름을 별칭으로 대신할 수 있습니다. 이 기능은 애플리케이션이 가리키는 인덱스 변경이 필요한 경우 유연성을 제공합니다. 프로덕션 코드에서 인덱스 이름에 대한 참조를 업데이트하는 대신 별칭 매핑을 업데이트하기만 하면 됩니다.

지정된 별칭 리소스에 대한 HTTP 요청(POST, GET, PUT 또는 DELETE)을 통해 검색 서비스에서 별칭을 만들고 관리할 수 있습니다. 별칭은 검색 인덱스와 독립적으로 유지 관리되는 서비스 수준 리소스입니다. 검색 인덱스를 만든 후에는 검색 인덱스에 매핑되는 별칭을 만들 수 있습니다.

별칭을 사용하기 전에 애플리케이션은 요청을 직접 hotel-samples-index보냅니다.

POST /indexes/hotel-samples-index/docs/search?api-version=2026-04-01
{
    "search": "pool spa +airport",
    "select": "HotelId, HotelName, Category, Description",
    "count": true
}

별칭을 사용한 후 애플리케이션은 요청을 my-alias에 보내며, 이 요청은 hotel-samples-index로 매핑됩니다.

POST /indexes/my-alias/docs/search?api-version=2026-04-01
{
    "search": "pool spa +airport",
    "select": "HotelId, HotelName, Category, Description",
    "count": true
}

필수 구성 요소

제한 사항 및 고려 사항

인덱스 별칭 만들기

별칭을 만들면 별칭 이름과 인덱스 이름 간에 매핑이 설정됩니다. 요청이 성공하면 인덱싱, 쿼리 및 기타 작업에 별칭을 사용할 수 있습니다.

REST API, Azure SDK 또는 Azure 포털을 사용하여 별칭을 만들 수 있습니다. 별칭은 name와 별칭이 매핑되는 검색 인덱스의 이름으로 구성됩니다. 배열에서 하나의 인덱스 indexes 이름만 지정할 수 있습니다.

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

안정적인 최신 버전의 별칭 - 만들기 (REST API)를 사용하여 인덱스 별칭을 만듭니다.

POST /aliases?api-version=2026-04-01
{
    "name": "my-alias",
    "indexes": ["hotel-samples-index"]
}

인덱스 별칭에 요청 보내기

쿼리, 인덱싱, 제안 및 자동 완성을 비롯한 모든 문서 작업에 별칭을 사용할 수 있습니다.

다음 쿼리는 my-alias로 요청을 보내며, 이는 검색 서비스의 실제 인덱스에 매핑됩니다.

POST /indexes/my-alias/docs/search?api-version=2026-04-01
{
    "search": "pool spa +airport",
    "searchMode": "any",
    "queryType": "simple",
    "select": "HotelId, HotelName, Category, Description",
    "count": true
}

별칭 정의 가져오기

별칭 - 목록(REST API)을 사용하여 이름별로 기존 별칭 개체 목록을 반환합니다.

GET /aliases?api-version=2026-04-01&$select=name

별칭 사용 - Get(REST API)을 사용하여 특정 별칭의 정의를 반환합니다.

GET /aliases/my-alias?api-version=2026-04-01

별칭 업데이트

별칭에 대한 가장 일반적인 업데이트는 기본 인덱스가 최신 버전으로 바뀐 경우 인덱스 이름을 변경하는 것입니다.

별칭 사용 - REST API( 만들기 또는 업데이트 )를 사용하여 별칭을 업데이트합니다. 다음 예제에서는 my-alias를 hotel-samples-index2 대신 hotel-samples-index을 가리키도록 업데이트하는 방법을 보여줍니다.

PUT /aliases/my-alias?api-version=2026-04-01
{
    "name": "my-alias",
    "indexes": ["hotel-samples-index2"]
}

별칭에 대한 업데이트는 시스템을 통해 전파되는 데 최대 10초가 걸릴 수 있으므로 별칭이 이전에 매핑된 인덱스를 삭제하기 전에 최소 10초 정도 기다립니다.

현재 별칭에 매핑된 인덱스를 삭제하려고 하면 400(잘못된 요청)과 해당 인덱스에 매핑된 별칭을 삭제하거나 다른 인덱스에 매핑해야 인덱스를 삭제할 수 있다는 오류 메시지가 표시되어 작업이 실패합니다.

관련 콘텐츠

  • Azure AI 검색
  • Last updated on