Azure Cognitive Search 서비스 REST

Azure Cognitive Search는 사용자 지정 응용 프로그램에 다양 한 검색 환경을 제공 하는 완전히 관리 되는 클라우드 검색 서비스입니다. 검색 기능을 추가 하는 한 가지 방법은 인덱스를 만들고 관리 하며, 데이터를 로드 하 고, 검색 기능을 구현 하 고, 쿼리를 실행 하 고, 결과를 처리 하는 작업을 포함 하는 REST Api

별도의 REST API를 사용 하 여 검색 서비스 구성을 프로 비전 하 고 변경 합니다. 또는 포털을 사용할 수 있습니다. 자세한 내용은 Azure Portal 또는 Azure Cognitive Search 관리 REST 에서 search 서비스 만들기 를 참조 하세요.

주요 개념

Cognitive Search에는 검색 서비스인덱스문서의 개념이 있습니다.

  • 검색 서비스는 하나 이상의 인덱스를 포함 합니다.
  • 인덱스는 검색 문서의 영구 저장소를 제공 합니다.
  • 검색 문서는 JSON 문서 형식으로 외부 소스에서 로드 되 고 검색 가능 하도록 인덱스에 푸시됩니다.

인덱서 를 사용 하 여 인덱스를 로드 하는 경우 데이터 업로드 작업을 자동화할 수 있습니다. 인덱서는 대상 인덱스에 대 한 경로에서 데이터 원본을 탐색 하 고 콘텐츠를 JSON으로 직렬화 할 수 있습니다.

Cognitive Search AI 보강 의 개념은 기술력과 입니다. 기술는 인덱서에 연결 됩니다. 데이터를 수집 하는 동안 검색할 수 없는 콘텐츠를 검색, 구조 또는 변환 하는 일련의 단계를 정의 합니다.

서비스에 대해 실행할 수 있는 작업에는 다음 5 가지 유형이 있습니다.

작업(Operation) Description
Index 검색 인덱스를 생성, 삭제, 업데이트 또는 구성 합니다.
Document 인덱스의 문서를 추가, 업데이트 또는 삭제 하거나 인덱스를 쿼리하거나 ID 별로 특정 문서를 조회 합니다.
인덱서 주문형으로 예약 하거나 실행할 수 있는 데이터 원본인덱서 를 구성 하 여 인덱싱 작업의 여러 측면을 자동화 합니다. 이 기능은 Azure에서 제한 된 수의 데이터 원본 유형에 대해 지원 됩니다.
기술 AI 보강 워크 로드의 일부로, 기술는 일련의 보강 처리를 정의 합니다. 기술는 인덱서에 사용 됩니다.
동의어 맵 동의어 맵은 사용자 정의 동의어를 포함 하는 서비스 수준 리소스입니다. 이 리소스는 검색 인덱스와 독립적으로 유지 관리 됩니다. 업로드 되 면 검색 가능한 필드를 동의어 맵 (필드 당 하나)로 가리킬 수 있습니다.

Api 호출

이 섹션에서 설명하는 API를 사용하면 인덱스 작성/채우기, 문서 업로드, 쿼리 등의 검색 데이터에 대한 작업을 수행할 수 있습니다. Api를 호출할 때는 다음 사항을 염두에 두어야 합니다.

  • 요청은 HTTPS (기본 포트 443)에서 발급 되어야 합니다.

  • 요청은 URI에 api 버전 을 포함 해야 합니다. 이 값은 다음 예제와 같이 형식이 지정 된 지원 되는 버전으로 설정 되어야 합니다. GET https://[search service name].search.windows.net/indexes?api-version=2020-06-30

  • 요청 헤더는 프로 비전 한 검색 서비스에 대해 생성 된 api 키 를 포함 해야 합니다. 유효한 키가 있다면 요청을 기반으로 요청을 보내는 애플리케이션과 이를 처리하는 서비스 사이에 신뢰가 쌓입니다.

    필요에 따라 Accept HTTP 헤더를 설정할 수 있습니다. 헤더가 설정 되지 않은 경우 기본값은로 가정 됩니다 application/json .

키 인증

검색 서비스에 대 한 모든 HTTP 요청은 두 가지 정보, 즉 검색 서비스 URL과 요청을 신뢰할 수 있는 엔터티에서 제공 하는 api 키 를 기반으로 인증 됩니다. 서로 다른 작업 수준에는 두 가지 유형의 api 키 가 있습니다.

설명 제한
Admin 관리 키는 서비스를 관리 하 고, 상태 및 개체 정의를 가져오고, 인덱스, 인덱서데이터 원본을 만들고 삭제 하는 기능을 포함 하 여 모든 작업에 모든 권한을 부여 합니다.

포털에서 기본 키 및 보조 키로 지칭 되는 두 개의 관리 api 키 가 서비스를 만들 때 자동으로 생성 되며 필요 시 개별적으로 다시 생성할 수 있습니다. 키가 두 개이면 서비스에 대해 액세스를 지속하는 데 하나의 키를 사용하는 동안 다른 키를 롤오버할 수 있습니다.

관리자 키는 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를 요청 헤더로 전달하는 것이 좋습니다.

권한 부여

권한 부여는 Azure Portal에서 제공 하는 RBAC (역할 기반 액세스 제어)를 통해 관리 작업에 사용할 수 있습니다. RBAC 역할은 모든 서비스에서 일관 된 방식으로 서비스 관리에 대 한 액세스 수준을 설정 하는 데 사용 됩니다. 예를 들어 관리 키와 같은 중요한 데이터는 소유자 및 참가자 역할에서만 확인할 수 있는 반면 서비스 상태는 역할에 관계없이 모든 구성원이 확인할 수 있습니다.

자체 검색 중심 작업의 경우 Azure Cognitive Search는 권한 부여 모델을 제공 하지 않습니다. 그러나 문서 및 사용자 연결을 사용 하 여 인덱스를 로드 하는 기능이 있는 경우에는 사용자 id에 따라 검색 결과를 필터링 할 수 있습니다. 자세한 내용은 Azure Cognitive Search에서 결과를 자르기 위한 보안 필터를 참조 하세요.

참고 항목