Azure Cognitive Search Service REST
Azure Cognitive Search 사용자 소유 콘텐츠보다 풍부한 검색 환경을 제공하는 완전 관리형 클라우드 검색 서비스입니다. 검색 기능을 추가하는 한 가지 방법은 검색 REST API를 통해 인덱스를 만들고 관리하고, 데이터를 로드하고, 검색 기능을 구현하고, 쿼리를 실행하고, 결과를 처리하는 작업입니다.
별도의 관리 REST API 를 사용하여 서비스 자체를 만들거나 수정할 수 있습니다. 또는 포털을 사용하여 많은 서비스 및 콘텐츠 관리 작업을 수행할 수 있습니다. 시작하려면 Azure Portal 검색 서비스 만들기를 참조하세요.
주요 개념
Cognitive Search에는 검색 서비스 및 인덱스 및 문서의 개념이 있습니다.
- 검색 서비스에는 하나 이상의 인덱스가 포함되어 있습니다.
- 인덱스가 검색 문서의 영구 스토리지를 제공합니다.
- 검색 문서는 외부 원본에서 JSON 문서 형식으로 로드되고 검색 가능하도록 인덱스로 푸시됩니다.
인덱싱을 자동화하는 인덱서도 만들 수 있습니다. 인덱서에는 데이터 원본 이 있고 인덱스가 있습니다. 필요에 따라 인덱서 파이프라인에 AI를 추가하는 기술 세트 가 있을 수도 있습니다.
AI 보강 은 텍스트를 추출하거나 생성하는 기계 학습 변환을 추가하거나 검색 서비스에서 인덱싱할 수 있도록 콘텐츠에 구조를 추가하는 인덱서의 확장입니다. AI 보강을 구동하는 구문을 기술 세트라고 합니다. 데이터 수집 중에는 그렇지 않으면 검색할 수 없는 콘텐츠(예: 이미지 콘텐츠)를 검색, 구조화 또는 변환하는 일련의 단계를 정의합니다.
모두 서비스에 대해 실행할 수 있는 다섯 가지 유형의 작업이 있습니다.
| 작업(Operation) | Description |
|---|---|
| Index | 검색 인덱스 만들기, 삭제, 업데이트 또는 구성 |
| Document | 인덱스에서 문서를 추가, 업데이트 또는 삭제하거나, 인덱스 쿼리를 하거나, ID별로 특정 문서를 조회합니다. |
| 인덱서 | 요청 시 예약하거나 실행할 수 있는 데이터 원본 및 인덱서 구성을 통해 인덱싱 작업의 측면을 자동화합니다. 이 기능은 Azure에서 제한된 수의 데이터 원본 형식에 대해 지원됩니다. |
| 기술 집합 | AI 보강 워크로드의 일부인 기술 세트는 구조화되지 않은 텍스트, 애플리케이션 파일 또는 이미지 파일에서 검색 가능한 텍스트를 추출하거나 만드는 일련의 보강 처리를 정의합니다. 기술 세트는 인덱서에서 호출됩니다. |
| 동의어 맵 | 동의어 맵은 사용자 정의 동의어를 포함하는 서비스 수준 리소스입니다. 이 리소스는 검색 인덱스와 독립적으로 유지 관리됩니다. 업로드되면 검색 가능한 모든 필드를 동의어 맵(필드당 하나씩)으로 가리킬 수 있습니다. |
API 호출
이 섹션에서 설명하는 API를 사용하면 인덱스 작성/채우기, 문서 업로드, 쿼리 등의 검색 데이터에 대한 작업을 수행할 수 있습니다. API를 호출할 때 다음 사항에 유의하세요.
HTTPS(기본 포트 443)를 통해 요청을 실행해야 합니다.
요청에는 URI에 api-version 이 포함되어야 합니다. 값은 다음 예제와 같이 형식이 지정된 지원되는 버전으로 설정해야 합니다.
GET https://[search service name].search.windows.net/indexes?api-version=2020-06-30요청 헤더에는 프로비전한 검색 서비스에 대해 생성된 api-key 가 포함되어야 합니다. 유효한 키가 있다면 요청을 기반으로 요청을 보내는 애플리케이션과 이를 처리하는 서비스 사이에 신뢰가 쌓입니다. 필요에 따라 ACCEPT HTTP 헤더를 설정할 수 있습니다. 헤더가 설정되지 않은 경우 기본값은 로
application/json간주됩니다.
키 인증
검색 서비스에 대한 모든 HTTP 요청은 두 가지 정보, 즉 검색 서비스 URL과 신뢰할 수 있는 엔터티에서 요청이 수신되었다는 증거를 제공하는 api-key 를 기반으로 인증됩니다. 작업 수준에는 두 가지 유형의 api-keys 가 있습니다.
| 키 | Description | 제한 |
|---|---|---|
| Admin | 관리 키는 서비스를 관리하고, 상태 및 개체 정의를 가져오고, 인덱스, 인덱서 및 데이터 원본을 만들고 삭제하는 기능을 포함하여 모든 작업에 대한 모든 권한을 부여합니다. 포털에서 기본 및 보조 키라고 하는 두 개의 관리자 api-keys는 서비스가 만들어질 때 자동으로 생성되며 요청 시 개별적으로 다시 생성될 수 있습니다. 키가 두 개이면 서비스에 대해 액세스를 지속하는 데 하나의 키를 사용하는 동안 다른 키를 롤오버할 수 있습니다. 관리 키는 HTTP 요청 헤더에만 지정됩니다. URL에 관리자 api-key를 배치할 수 없습니다. | 서비스당 최대 2개 |
| 쿼리 | 쿼리 키는 인덱스(문서) 내의 콘텐츠에 대한 읽기 전용 액세스 권한을 부여하며 일반적으로 검색 요청을 발급하는 클라이언트 애플리케이션에 배포됩니다. 쿼리 키는 요청 시 만들어집니다. 포털에서 수동으로 만들거나 관리 REST API를 통해 프로그래밍 방식으로 만들 수 있습니다. 검색, 제안 또는 조회 작업을 위해 HTTP 요청 헤더에서 쿼리 키를 지정할 수 있습니다. 또는 쿼리 키를 URL에 매개 변수로 전달할 수 있습니다. 클라이언트 애플리케이션이 요청을 작성하는 방법에 따라 키를 쿼리 매개 변수로 전달하는 것이 더 쉬울 수 있습니다. GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2020-06-30&api-key=[query key] |
서비스당 50개 |
시각적으로는 관리자 키 및 쿼리 키 간의 구분이 없습니다. 두 키는 임의로 생성된 32개의 영숫자 문자로 구성된 문자열입니다. 애플리케이션에 지정된 키 유형을 추적하지 못하면 포털에서 키 값을 확인 하거나 관리 REST API 를 사용하여 값과 키 형식을 반환할 수 있습니다.
참고
요청 URI에서 api-key와 같은 중요한 데이터를 전달하는 낮은 수준의 보안 사례로 간주됩니다. 이러한 이유로 Azure Cognitive Search 쿼리 문자열에서 쿼리 키를 로 api-key 만 수락하므로 인덱스의 내용을 공개적으로 사용할 수 없는 한 사용하지 않아야 합니다. 일반적으로 api-key를 요청 헤더로 전달하는 것이 좋습니다.
권한 부여
Cognitive Search는 소유자, 기여자 및 읽기 권한자 역할을 통해 검색 서비스 관리를 위한 Azure RBAC(Azure 역할 기반 액세스 제어) 를 지원합니다.
필요에 따라 미리 보기 기능을 사용할 수 있는 검색 솔루션의 경우 Azure RBAC를 사용하여 검색 서비스의 인덱스 및 기타 개체에 대한 액세스를 제어할 수 있습니다. 이 방법을 사용하려면 데이터 평면의 Azure RBAC에 대해 구성된 검색 서비스와 Azure Active Directory를 사용하여 인증된 REST API 호출의 권한 부여 헤더 가 필요합니다.