중요합니다
인덱스 별칭은 현재 공개 미리 보기로 제공되며 보충 사용 약관에 따라 사용할 수 있습니다.
Azure AI Search에서 인덱스 별칭은 검색 인덱스의 보조 이름입니다. 검색 인덱스에 매핑되는 별칭을 만들어 인덱스 이름 대신 사용해야 하는 곳에 별칭 이름을 대체하여 사용할 수 있습니다. 이렇게 하면 애플리케이션이 가리키는 인덱스를 변경해야 하는 경우 유연성을 제공합니다. 프로덕션 코드에서 인덱스 이름에 대한 참조를 업데이트하는 대신 별칭에 대한 매핑만 업데이트할 수 있습니다.
지정된 별칭 리소스에 대한 HTTP 요청(POST, GET, PUT, DELETE)을 통해 Azure AI Search 서비스에서 별칭을 만들고 관리할 수 있습니다. 별칭은 서비스 수준 리소스이며 검색 인덱스와 독립적으로 유지 관리됩니다. 검색 인덱스가 만들어지면 해당 검색 인덱스에 매핑되는 별칭을 만들 수 있습니다.
별칭을 사용하기 전에 애플리케이션은 요청을 직접 hotel-samples-index보냅니다.
POST /indexes/hotel-samples-index/docs/search?api-version=2025-08-01-preview
{
"search": "pool spa +airport",
"select": "HotelId, HotelName, Category, Description",
"count": true
}
별칭을 사용한 후 애플리케이션은 my-alias에 매핑된 hotel-samples-index로 요청을 보냅니다.
POST /indexes/my-alias/docs/search?api-version=2025-08-01-preview
{
"search": "pool spa +airport",
"select": "HotelId, HotelName, Category, Description",
"count": true
}
지원되는 시나리오
문서 작업에서 별칭만 사용하거나 인덱스 정의를 가져오고 업데이트할 수 있습니다.
별칭을 사용하여 인덱스를 삭제하거나 텍스트 토큰화를 테스트하거나 targetIndexName 또는 지식 원본에서 참조 할 수 없습니다.
인덱스 별칭 만들기
별칭을 만들면 별칭 이름과 인덱스 이름 간에 매핑이 설정됩니다. 요청이 성공하면 별칭을 인덱싱, 쿼리 및 기타 작업에 사용할 수 있습니다.
별칭을 업데이트하면 해당 별칭을 다른 검색 인덱스에 매핑할 수 있습니다. 기존 별칭을 업데이트하면 전체 정의가 요청 본문의 내용으로 바뀝니다. 일반적으로 업데이트에 사용하는 가장 좋은 패턴은 GET을 사용하여 별칭 정의를 검색하고 수정한 다음 PUT으로 업데이트하는 것입니다.
미리 보기 REST API, 미리 보기 SDK 또는 Azure Portal을 통해 별칭을 만들 수 있습니다. 별칭은 별칭의 name과 별칭이 매핑되는 검색 인덱스의 이름으로 구성됩니다.
indexes 배열에는 하나의 인덱스 이름만 지정할 수 있습니다.
만들 수 있는 별칭의 최대 수는 가격 책정 계층에 따라 다릅니다. 자세한 내용은 서비스 제한을 참조하세요.
별칭 만들기 또는 업데이트(REST 미리 보기)를 사용하여 인덱스 별칭을 만들 수 있습니다.
POST /aliases?api-version=2025-08-01-preview
{
"name": "my-alias",
"indexes": ["hotel-samples-index"]
}
인덱스 별칭에 요청 보내기
별칭은 쿼리, 인덱싱, 제안 및 자동 완성을 포함한 모든 문서 작업에 사용할 수 있습니다.
이 쿼리는 검색 서비스의 실제 인덱스에 매핑되는 요청을 my-alias보냅니다.
POST /indexes/my-alias/docs/search?api-version=2025-08-01-preview
{
"search": "pool spa +airport",
"searchMode": any,
"queryType": "simple",
"select": "HotelId, HotelName, Category, Description",
"count": true
}
별칭 정의 가져오기
이 요청은 이름별로 기존 별칭 개체 목록을 반환합니다.
GET https://[service name].search.windows.net/aliases?api-version=[api-version]&$select=name
api-key: [admin key]
이 요청은 별칭 정의를 반환합니다.
GET https://[service name].search.windows.net/aliases/my-alias?api-version=[api-version]
api-key: [admin key]
별칭 업데이트
별칭에 대한 가장 일반적인 업데이트는 기본 인덱스가 최신 버전으로 바뀐 경우 인덱스 이름을 변경하는 것입니다.
별칭 업데이트에는 Create or Update Alias (REST 미리 보기)에 설명된 대로 PUT이 필요합니다.
PUT /aliases/my-alias?api-version=2025-08-01-preview
{
"name": "my-alias",
"indexes": ["hotel-samples-index2"]
}
별칭에 대한 업데이트는 전파하는 데 최대 10초가 걸릴 수 있으므로 별칭이 이전에 매핑된 인덱스를 삭제하기 전에 10초 이상 기다려야 합니다.
현재 별칭에 매핑된 인덱스를 삭제하려고 하면 작업이 400(잘못된 요청)으로 실패하고 해당 인덱스에 매핑된 별칭을 삭제하거나 다른 인덱스에 매핑해야 인덱스를 삭제할 수 있다는 오류 메시지가 표시됩니다.