관리 REST API 참조(Azure AI Search)

  • 아티클

Azure AI Search(이전의 Azure Cognitive Search)의 관리 REST API는 관리 작업에 프로그래밍 방식으로 액세스할 수 있도록 합니다.

  • 검색 서비스 만들기, 업데이트 및 삭제
  • 검색 서비스 정보 검색
  • 만들기, 다시 생성 또는 검색 api-keys (쿼리 또는 관리자 키)
  • 복제본 및 파티션 추가 또는 제거(용량 조정)
  • 프라이빗 엔드포인트를 사용하도록 검색 서비스 구성
  • Azure 역할 기반 액세스 제어 사용 또는 사용 안 함

인덱스 만들기 및 쿼리와 같은 데이터 평면 작업의 경우 Search Service REST API를 대신 사용합니다.

관리 REST API를 사용하는 방법

프로그래밍 방식으로 서비스를 완전히 관리하려면 여기에 설명된 Azure AI Search 관리 REST API와 일반적인 Azure Resource Manager REST API라는 두 가지 API를 사용합니다.

Resource Manager API는 구독 데이터 쿼리, 지역 위치 나열 등과 같이 서비스별로 지정되지 않은 범용 작업에 사용됩니다. 모든 Resource Manager API 호출은 Microsoft Entra ID 사용하여 인증됩니다. Resource Manager API 호출을 수행하려면 Microsoft Entra 테넌트에서 멤버 자격 및 역할 할당이 있어야 합니다.

버전이 지정된 API 문서

이제 REST API 문서의 버전이 지정됩니다. API 참조 페이지를 열 때 드롭다운 필터에서 API 버전을 선택합니다.

버전 선택기의 스크린샷.

권한 및 액세스 제어

관리 권한은 Microsoft Entra ID 기본 제공 역할을 통해 전달됩니다.

  • 소유자 또는 기여자 할당은 대부분의 작업에 필요합니다.
  • 읽기 권한자 역할은 서비스 정보에 대한 액세스가 제한됩니다(소유자 또는 기여자 권한이 필요한 API 키를 제외한 GET 작업).

자세한 내용은 Azure AI Search 역할 기반 액세스 제어를 참조하세요.

모범 사례는 개별 사용자가 아닌 그룹에 역할을 할당하는 것입니다. Azure 구독 소유자 또는 전역 관리자가 이러한 할당을 관리합니다. 자세한 내용은 그룹에 Microsoft Entra 역할 할당을 참조하세요.

관리 엔드포인트에 연결

연결을 설정할 때 Resource Manager 엔드포인트 https://management.azure.com 로 시작한 다음 구독 ID, 공급자(Microsoft.Search) 및 API 버전을 추가합니다. 작업은 요청 본문에 지정됩니다.

완전히 지정된 엔드포인트에는 다음과 같은 구성 요소가 있습니다.

https://management.azure.com/subscriptions/[subscriptionId]/resourceGroups/[resourceGroupName]/providers/Microsoft.Search/searchServices/[serviceName]?api-version=2020-08-01

다음 클라이언트는 일반적으로 관리 REST API를 호출하는 데 사용됩니다.

클라이언트 지침 및 예제
Az.Search 모듈을 사용하여 Azure PowerShell Azure PowerShell 사용하여 Azure AI Search 관리
Azure CLI(명령줄 인터페이스) Azure CLI를 사용하여 Azure AI Search 관리
REST 클라이언트를 사용하여 Visual Studio Code REST를 사용하여 Azure AI Search 관리

Azure Portal 사용하여 검색 서비스를 관리할 수도 있습니다.

다른 SDK의 관리 API

REST API는 Azure AI Search 기본이며 프로그래밍 모델의 변경 내용은 먼저 REST API에 반영됩니다.

대안으로는 별도의 릴리스 일정에 따라 독립적으로 업데이트되는 다음 Azure SDK가 포함됩니다.

추가 정보