Azure AI Search REST API 참조
Azure AI Search(이전의 Azure Cognitive Search)은 사용자 소유 콘텐츠에 대한 정보 검색을 제공하는 완전 관리형 클라우드 검색 서비스입니다.
데이터 평면 REST API는 인덱싱 및 쿼리 워크플로에 사용되며 이 섹션에 설명되어 있습니다.
서비스 관리를 위한 컨트롤 플레인 작업은 별도의 관리 REST API다룹니다.
버전이 지정된 API 문서
이제 REST API 문서의 버전이 지정됩니다. API 참조 페이지를 열면 버전 선택기가 목차 위에 나타납니다. API 참조가 Reference > Data Plane 폴더에 있는지 확인합니다.
주요 개념
Azure AI Search에는
- 검색 서비스는 인덱스, 인덱서, 데이터 원본, 기술 세트 및 동의어 맵을 최상위 개체로 호스트합니다.
- 검색 인덱스가 검색 문서의 영구 스토리지를 제공합니다. 검색 문서는 필드 컬렉션으로 표시되고 외부 원본에서 로드되고 검색 가능하도록 인덱스로 푸시된 데이터입니다.
- 검색 인덱서는 자동화를 추가하고 네이티브 형식으로 데이터를 읽고 JSON으로 직렬화합니다.
- 인덱서에는 데이터 원본이 있고 인덱스가 가리킵니다.
- 인덱서에는
AI 보강 추가하고 통합 벡터화 인덱싱 파이프라인에기술 세트가 있을 수도 있습니다. 기술 세트는 항상 인덱서에 연결됩니다. 기계 학습을 호출하여 텍스트를 추출하거나 청크하거나, 콘텐츠를 벡터화하거나, 기능을 유추하거나, 검색 서비스에서 향상된 인덱싱을 위해 콘텐츠에 구조를 추가합니다.
모두 검색 서비스에서 다음 개체를 만들 수 있습니다.
| 개체 | 묘사 |
|---|---|
| 데이터 원본 | 인덱싱을 위해 문서를 검색하고 새로 고치는 데 인덱서에서 사용하는 데이터 원본 연결입니다. 데이터 원본에는 type있습니다. Azure 또는 파트너 커넥터에 대해 Microsoft에서 제공하는 연결을 사용할 수 있습니다. 전체 목록은 데이터 원본 갤러리 참조하세요. |
| 문서 | 개념적으로 문서는 인덱스 내의 엔터티입니다. 검색 인덱스는 테이블과 동일하며 문서는 테이블의 행과 거의 동일합니다. 문서는 인덱스에만 존재하며 인덱스의 문서 컬렉션(/docs)을 대상으로 하는 쿼리를 통해서만 검색됩니다. 컬렉션에서 수행되는 모든 작업(예: 문서 업로드, 병합, 삭제 또는 쿼리)은 단일 인덱스의 컨텍스트에서 수행되므로 URL 형식 문서 작업에는 항상 지정된 인덱스 이름에 대한 /indexes/[index name]/docs 포함됩니다. |
| 인덱스 | 인덱스는 검색 서비스에 저장되고 정보 검색을 위해 인덱싱되고 토큰화된 JSON 문서로 채워집니다. 인덱스의 필드 컬렉션은 검색 문서의 구조를 정의합니다. 필드에는 사용량을 결정하는 이름, 데이터 형식 및 특성이 있습니다. 예를 들어 searchable 필드는 전체 텍스트 검색에 사용되므로 인덱싱 중에 토큰화됩니다. 또한 인덱스는 관련성 튜닝, 제안기, 의미 체계 구성 및 사용자 지정 분석기의 점수 매기기 프로필과 같은 다른 구문을 정의합니다. |
| 인덱서 | 인덱서는 인덱싱 자동화를 제공합니다. 인덱서는 데이터 원본에 연결하고, 데이터를 읽고, 대상 검색 인덱스에 인덱싱하기 위해 검색 엔진에 전달합니다. 인덱서는 데이터 원본의 연결 정보를 사용하여 외부 원본에서 읽고 들어오는 데이터를 JSON 검색 문서로 직렬화합니다. 인덱서에는 데이터 원본 외에도 인덱스가 필요합니다. 인덱스는 검색 문서의 필드와 특성을 지정합니다. |
| 기술 세트 | 기술 세트는 인덱서 실행에 외부 처리 단계를 추가하고 AI 또는 딥 러닝 모델을 적용하여 인덱스 검색 가능성을 개선하기 위해 콘텐츠를 분석하거나 변환하는 데 사용됩니다. 기술 세트의 콘텐츠는 하나 이상의 |
| 동의어 맵 | 동의어 맵은 사용자 정의 동의어를 포함하는 서비스 수준 개체입니다. 이 개체는 검색 인덱스와 독립적으로 유지 관리됩니다. 업로드되면 검색 가능한 모든 필드를 동의어 맵(필드당 하나씩)으로 가리킬 수 있습니다. |
권한 및 액세스 제어
Microsoft Entra ID를 통해 키 기반 인증 또는 역할 기반을 사용할 수 있습니다.
키 기반 인증 검색 서비스에 대해 생성된 API 키를 사용합니다. 유효한 키를 보유하면 요청을 보내는 애플리케이션과 요청을 처리하는 서비스 간에 요청별로 트러스트가 설정됩니다. 읽기/쓰기 작업에
관리 API 키 사용하거나 검색 인덱스의 문서 컬렉션에 대한 읽기 액세스를 위해쿼리 API 키를 사용할 수 있습니다. microsoft Entra ID 인증 및 역할 기반 액세스 제어
보안 주체 및 역할 할당을 사용하여 Microsoft Entra ID에 설정된 테넌트가 있어야 합니다. 다음 역할의 멤버는 데이터 평면에 액세스할 수 있습니다. 기본 제공 역할이 부족한 경우 사용자 지정 역할을 만들 수 있습니다. 역할 접근 Search Service 기여자 개체에 액세스하지만 인덱스 콘텐츠에 대한 액세스 권한은 없습니다. 이 역할은 검색 인덱스 및 기타 최상위 개체를 만들지만 검색 인덱스 쿼리 또는 검색 인덱스의 문서를 추가, 제거 또는 업데이트할 수는 없습니다. 이 역할은 개체 정의를 만들고, 업데이트하고, 삭제하는 개발자를 위한 것입니다. 또한 개체를 관리해야 하지만 개체 데이터를 보거나 액세스할 수 없는 관리자를 위한 것입니다. 데이터 인덱스 참가자 검색 인덱스 콘텐츠에 대한 읽기/쓰기 권한입니다. 이 역할은 인덱스의 문서 컬렉션을 가져오거나 새로 고치거나 쿼리해야 하는 개발자 또는 인덱스 소유자를 위한 것입니다. 데이터 인덱스 판독기 검색 인덱스 콘텐츠에 대한 읽기 권한입니다. 이 역할은 쿼리를 실행하는 앱 및 사용자를 위한 것입니다.
연결에서 역할을 사용하는 경우 클라이언트 앱은 권한 부여 헤더에 전달자 토큰을 표시합니다. 이 설정에 대한 도움말은 Microsoft Entra ID 사용하여 검색 앱에 대한 액세스 권한 부여를 참조하세요.
키 기반 인증 또는 역할 기반 인증을 사용하지 않도록 설정할 수 있습니다. 역할 기반 인증을 사용하지 않도록 설정하면 데이터 평면 작업에만 적용됩니다. 서비스 관리와 같은 제어 평면 작업은 항상 역할 기반 인증을 사용합니다. 자세한 내용은 Microsoft Entra ID 인증 및 Azure AI Search 대한 역할 기반 액세스 제어를 참조하세요.
API 호출
이 섹션에 설명된 API는 인덱스 만들기 및 채우기, 문서 업로드 및 쿼리와 같은 검색 데이터에 대한 작업에 대한 액세스를 제공합니다. API를 호출할 때 다음 사항에 유의하세요.
HTTPS를 통해 요청이 발급되어야 합니다(기본 포트 443).
요청 URI에는 api-version포함되어야 합니다. 이 값은 다음 예제와 같이 형식이 지정된 지원되는 버전으로 설정해야
GET https://[search service name].search.windows.net/indexes?api-version=2023-11-01요청 헤더 인증된 연결에 대한 api-key 또는 전달자 토큰을 포함해야 합니다. 필요에 따라 ACCEPT HTTP 헤더를 설정할 수 있습니다. 콘텐츠 형식 헤더가 설정되지 않은 경우 기본값은
application/json것으로 간주됩니다.
참고 항목
- Azure Portal 검색 서비스 만들기
- 일반적인 HTTP 요청 및 응답 헤더