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 호출의 권한 부여 헤더 가 필요합니다.

추가 정보