Azure AI Search REST API 참조
Azure AI Search(이전의 Azure Cognitive Search)은 사용자 소유 콘텐츠에 대한 정보 검색을 제공하는 완전 관리형 클라우드 검색 서비스입니다.
데이터 평면 REST API는 인덱싱 및 쿼리 워크플로에 사용되며 이 섹션에 설명되어 있습니다.
컨트롤 플레인 작업은 별도의 관리 REST API를 통해 액세스됩니다.
버전이 지정된 API 문서
이제 REST API 문서의 버전이 지정됩니다. API 참조 페이지를 열면 버전 선택기가 목차 위에 표시됩니다. API 참조가 참조 > 데이터 평면 폴더에 있는지 확인합니다.
주요 개념
Azure AI Search 검색 서비스, 인덱스, 문서, 인덱서, 데이터 원본, 기술 세트 및 동의어 맵의 개념을 가지고 있습니다.
- 검색 서비스는 인덱스, 인덱서, 데이터 원본, 기술 세트 및 동의어 맵을 최상위 개체로 호스트합니다.
- 검색 인덱스가 검색 문서의 영구 스토리지를 제공합니다. Search 문서는 필드 컬렉션으로 명시되고 외부 원본에서 로드되고 검색할 수 있도록 인덱스로 푸시되는 데이터입니다.
- 검색 인덱서는 자동화를 추가하여 네이티브 형식으로 데이터를 읽고 JSON으로 직렬화합니다.
- 인덱서에는 데이터 원본이 있고 인덱스가 있습니다.
- 인덱서에는 AI 보강 및 통합 벡터화를 인덱싱 파이프라인에 추가하는 기술 세트가 있을 수도 있습니다. 기술 세트는 항상 인덱서에 연결됩니다. 기계 학습을 호출하여 텍스트를 추출하거나 청크하거나, 콘텐츠를 벡터화하거나, 기능을 유추하거나, 검색 서비스에서 인덱싱할 수 있도록 콘텐츠에 구조를 추가합니다.
모두 검색 서비스에서 다음 개체를 만들 수 있습니다.
| 개체 | Description |
|---|---|
| 데이터 원본 | 인덱싱을 위해 문서를 검색하고 새로 고치는 데 인덱서에서 사용하는 데이터 원본 연결입니다. 데이터 원본에는 가 있습니다 type. Azure용 Microsoft 제공 연결 또는 파트너를 통해 타사 커넥터를 사용할 수 있습니다. 전체 목록은 데이터 원본 갤러리 를 참조하세요. |
| 문서 | 개념적으로 문서는 인덱스에서 엔터티입니다. 이 개념을 보다 친숙한 데이터베이스에 매핑: 검색 인덱스는 테이블과 동일하며 문서는 테이블의 행과 거의 동일합니다. 문서는 인덱스에만 존재하며 인덱스의 문서 컬렉션(/docs)을 대상으로 하는 쿼리를 통해서만 검색됩니다. 컬렉션에서 수행되는 모든 작업(예: 문서 업로드, 병합, 삭제 또는 쿼리)은 단일 인덱스의 컨텍스트에서 수행되므로 URL 형식 문서 작업은 항상 지정된 인덱스 이름에 대해 포함 /indexes/[index name]/docs 됩니다. |
| 인덱스 | 인덱스는 검색 서비스에 저장되고 정보 검색을 위해 인덱싱되고 토큰화된 JSON 문서로 채워집니다. 인덱스의 필드 컬렉션은 검색 문서의 구조를 정의합니다. 필드에는 사용 방법을 결정하는 이름, 데이터 형식 및 특성이 있습니다. 예를 들어 searchable 필드는 전체 텍스트 검색에 사용되므로 인덱싱 중에 토큰화됩니다. 또한 인덱스는 관련성 튜닝, 제안기, 의미 체계 구성 및 사용자 지정 분석기를 위한 점수 매기기 프로필과 같은 다른 구문을 정의합니다. |
| 인덱서 | 인덱서는 인덱싱 자동화를 제공합니다. 인덱서는 데이터 원본에 연결하고, 데이터를 읽고, 검색 엔진에 전달하여 대상 검색 인덱스로 인덱싱합니다. 인덱서는 데이터 원본의 연결 정보를 사용하여 외부 원본에서 읽고 들어오는 데이터를 JSON 검색 문서로 직렬화합니다. 데이터 원본 외에도 인덱서에는 인덱스도 필요합니다. 인덱스는 검색 문서의 필드와 특성을 지정합니다. |
| 기술 세트 | 기술 세트는 인덱서 실행에 외부 처리 단계를 추가하고, 일반적으로 인덱스에서 검색할 수 있도록 콘텐츠를 분석하거나 변환하는 AI 또는 딥 러닝 모델을 추가하는 데 사용됩니다. 기술 세트의 콘텐츠는 하나 이상의 기술로, Microsoft 에서 만든 기본 제공 기술 , 사용자 지정 기술 또는 둘 다의 조합일 수 있습니다. OCR 및 자연어 처리를 비롯한 이미지 분석을 위한 기본 제공 기술이 있습니다. 기본 제공 기술의 다른 예로는 엔터티 인식, 핵심 구 추출, 텍스트를 논리 페이지로 청크하는 등이 있습니다. 기술 세트는 인덱스, 인덱서 및 데이터 원본과 동일한 수준에 존재하는 상위 수준 독립 실행형 개체이지만 인덱서 처리 내에서만 작동합니다. 개략적인 개체로 기술 세트를 한 번 디자인한 다음 여러 인덱서에서 참조할 수 있습니다. |
| 동의어 맵 | 동의어 맵은 사용자 정의 동의어를 포함하는 서비스 수준 개체입니다. 이 개체는 검색 인덱스와 독립적으로 유지 관리됩니다. 업로드되면 검색 가능한 모든 필드를 동의어 맵(필드당 하나씩)으로 가리킬 수 있습니다. |
권한 및 액세스 제어
Microsoft Entra ID 통해 키 기반 인증 또는 역할 기반 인증을 사용할 수 있습니다.
키 기반 인증 은 검색 서비스에 대해 생성된 API 키를 사용합니다. 유효한 키가 있다면 요청을 기반으로 요청을 보내는 애플리케이션과 이를 처리하는 서비스 사이에 신뢰가 쌓입니다. 읽기/쓰기 작업에는 관리 API 키 또는 검색 인덱스의 문서 컬렉션에 대한 읽기 액세스에 쿼리 API 키를 사용할 수 있습니다.
Microsoft Entra ID 인증 및 역할 기반 액세스 제어를 사용하려면 보안 주체 및 역할 할당을 사용하여 Microsoft Entra ID 설정된 테넌트가 있어야 합니다. 다음 역할의 멤버는 데이터 평면에 액세스할 수 있습니다. 기본 제공 역할이 부족한 경우 사용자 지정 역할을 만들 수 있습니다.
역할 Access Search 서비스 참가자 개체에 액세스하지만 인덱스 콘텐츠에 대한 액세스 권한은 없습니다. 이 역할은 검색 인덱스 쿼리 또는 검색 인덱스에서 문서를 추가, 제거 또는 업데이트할 수 없습니다. 이 역할은 개체를 관리해야 하지만 개체 데이터를 보거나 액세스할 수 없는 관리자를 위한 것입니다. Search 데이터 인덱스 기여자 인덱스 콘텐츠에 대한 읽기-쓰기 액세스 이 역할은 인덱스의 문서 컬렉션을 가져오거나 새로 고치거나 쿼리해야 하는 개발자 또는 인덱스 소유자를 위한 것입니다. Search 데이터 인덱스 판독기 인덱스 콘텐츠에 대한 읽기 권한입니다. 이 역할은 쿼리를 실행하는 앱 및 사용자를 위한 것입니다.
연결에서 역할을 사용하는 경우 클라이언트 앱은 권한 부여 헤더에 전달자 토큰을 제공합니다. 이 설정에 대한 도움말은 Microsoft Entra ID 사용하여 검색 앱에 대한 액세스 권한 부여를 참조하세요.
키 기반 인증 또는 역할 기반 인증을 사용하지 않도록 설정할 수 있습니다. 역할 기반 인증을 사용하지 않도록 설정하면 일부 기본 제공 역할에 계속 액세스할 수 있습니다. 자세한 내용은 Azure AI Search 대한 Microsoft Entra ID 인증 및 역할 기반 액세스 제어를 참조하세요.
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간주됩니다.