참고
Foundry IQ (Azure AI 검색)는 관리형 검색을 위한 상위 수준의 지식 원본 및 지식 베이스 API와 함께 직접 인덱싱 및 쿼리 API를 제공합니다. Azure 포털, REST API 또는 Azure SDK 사용하여 이러한 기능을 구성하거나 Microsoft Foundry 포털의 기술 자료에 에이전트를 연결합니다.
중요
이 문서에서 (미리 보기)로 표시된 기능 또는 성능은 공개 미리 보기로 제공되며 Microsoft Azure 미리 보기에 대한 추가 사용 약관의 적용을 받습니다.
Foundry IQ(Azure AI 검색)에 대한 미리 보기 약관은 미리 보기 기능을 참조하세요.
외부 데이터 원본에 연결할 때 적용되는 용어는 외부 데이터 원본을 참조하세요.
Microsoft 365의 SharePoint 인덱서는 파일, 목록 항목 및 최신 사이트 페이지를 Foundry IQ로 가져옵니다.
2026-10-01 REST API와 함께 일반 공급됩니다. 이 문서에서는 구성 단계에 해당 버전을 사용하고 동작 및 시나리오를 수행합니다.
지원되는 문서의 레이아웃 인식 추출 및 청킹은 Foundry IQ에서 SharePoint 문서 추출 및 보강을 참조하세요. 더 간단한 설정을 위해 지식 소스 API를 사용하거나 더 많은 제어를 위해 인덱서 및 스킬 세트를 직접 구성합니다.
Foundry IQ에서 인덱서는 데이터 원본에서 검색 가능한 데이터 및 메타데이터를 추출합니다. Microsoft 365 인덱서의 SharePoint 다음과 같은 기능을 제공합니다.
- 하나 이상의 문서 라이브러리에서 파일 및 메타데이터를 인덱싱합니다.
- SharePoint 목록 및 해당 항목 필드 값을 인덱싱하며, 각 목록 열은 필드 매핑을 위한 소스 필드로 사용할 수 있습니다.
- ASPX 사이트 페이지(최신 사이트 페이지)를 인덱싱합니다.
-
allSiteContent컨테이너 값을 사용하여 단일 인덱서에서 혼합된 SharePoint 콘텐츠(문서 라이브러리, 목록 및 사이트 페이지)를 인덱싱합니다. - 데이터 원본 쿼리에 설정된 경우
includeSubsites=true하위 사이트 간에 콘텐츠를 인덱싱합니다. - 새 파일과 변경된 파일, 목록 항목, 페이지 및 메타데이터만 선택하여 증분 방식으로 인덱싱합니다.
- 삭제된 콘텐츠를 자동으로 검색합니다. 다음 인덱서 실행에서 파일, 목록 항목 또는 페이지 삭제가 선택되고 해당 검색 문서가 인덱스에서 제거됩니다.
- 인덱싱된 문서에서 자동으로 텍스트 및 정규화된 이미지를 추출합니다. 필요에 따라 OCR(광학 문자 인식) 또는 엔터티 인식과 같은 더 심층적인 AI 보강을 위한 기술 세트를 추가할 수 있습니다.
- 문서 수준 권한 수집을 지원합니다. 지원되는 권한 하위 집합, 그룹 확인 및 권한 동기화에 대한 연결된 문서를 참조하세요.
- Microsoft Purview 민감도 레이블을 수집하고 쿼리 시점에 이를 적용하는 기능을 지원합니다. 이 기능은 미리 보기로 제공됩니다.
필수 구성 요소
Foundry IQ, 기본 가격 책정 계층 이상이 필요합니다.
Microsoft 365의 SharePoint 클라우드 서비스(OneDrive는 지원되는 데이터 원본이 아닙니다).
인덱싱할 SharePoint 콘텐츠: 문서 라이브러리의 파일, 목록 항목 또는 최신 사이트 페이지.
Visual Studio Code에서 인덱서 파이프라인을 설정하고 실행하기 위한 REST Client 확장
사용 권한 설정 선택
3단계에서 앱 등록을 만들기 전에 다음 표에서 시나리오를 식별합니다. 필요한 Microsoft Graph 권한, SharePoint API 권한 및 자격 증명 유형을 확인합니다. 그런 다음 이 문서의 뒷부분에 있는 연결된 단계에 따라 적용합니다.
| Scenario | Microsoft Graph 권한 | SharePoint API 권한 | 자격 증명 | 다음에서 적용 |
|---|---|---|---|---|
| 문서 라이브러리만 인덱싱, ACL 수집 안 함 |
Files.Read.All, Sites.Read.All (애플리케이션) 또는 위임된 동등한 권한 |
없음 | 클라이언트 암호(애플리케이션) 또는 디바이스 코드(위임됨) | 3단계, 6단계 |
| 인덱스 목록, ASPX 페이지 또는 혼합 콘텐츠(ACL 수집 없음) |
Files.Read.All, Sites.Read.All (애플리케이션) |
없음 | 클라이언트 비밀 또는 페더레이션 자격 증명 | 3단계 |
| SharePoint 사이트 그룹의 ACL 수집 또는 쿼리 시간 확인 | ACL 권한 매트릭스를 참조하세요. | ACL 권한 매트릭스를 참조하세요. | ACL 권한 매트릭스를 참조하세요. | ACL 시나리오별 사용 권한 |
사용 권한을 설정할 때 다음 정보를 고려합니다.
- 위임된 권한은 소규모 테스트에만 사용할 수 있으며 ACL 수집을 지원하지 않습니다.
- 페더레이션 자격 증명은 권장되는 비밀 없는 인증입니다. 인덱서 인증과 쿼리 시 SharePoint 그룹 확인을 모두 다룹니다.
-
Sites.Selected사용하는 경우 인덱싱하기 전에 앱에 각 대상 SharePoint 사이트에 대한 명시적 액세스 권한을 부여합니다. Microsoft Entra ID 관리자Sites.Selected동의는 그 자체로 앱이 사이트 콘텐츠에 액세스할 수 있는 권한을 부여하지 않습니다. 또한 각 대상 사이트에 대한 사용 권한을 할당해야 합니다. 명시적 사이트 권한 부여 없이 데이터 원본에 사이트를 추가하면 인덱서가 실패합니다.Sites.Selected사용 시 사이트 액세스 권한 부여를 참조하세요.
수집에 대한 애플리케이션 권한은 최종 사용자의 쿼리 권한을 부여하지 않습니다. 사용자 대상 권한 필터링 애플리케이션에서 Authorization은(는) 호출자를 Search에 인증하고, x-ms-query-source-authorization은(는) 사용자의 권한 컨텍스트를 제공합니다.
쿼리 시간 권한 적용을 참조하세요.
애플리케이션 토큰은 로그인한 사용자가 아닌 애플리케이션을 나타냅니다. Microsoft ID 플랫폼 on-behalf-of 흐름은 사용자 보안 주체만 지원합니다. 앱 전용 토큰을 해당 흐름에 대한 사용자 어설션으로 사용하지 마세요.
지원되는 문서 형식
Microsoft 365 인덱서의 SharePoint 다음 문서 형식에서 텍스트를 추출할 수 있습니다.
- CSV( CSV Blob 인덱싱 참조)
- EML
- EPUB
- GZ
- Html
- JSON( JSON Blob 인덱싱 참조)
- KML(지리적 표현을 위한 XML)
- Markdown
- Microsoft Office 형식: DOCX/DOC/DOCM, XLSX/XLS/XLSM, PPTX/PPT/PPTM, MSG(Outlook 메일), XML(2003 및 2006 WORD XML 모두)
- 문서 형식 열기: ODT, ODS, ODP
- 일반 텍스트 파일( 일반 텍스트 인덱싱 참조)
- RTF
- Xml
- ZIP
제한 사항 및 고려 사항
이 기능의 제한 사항은 다음과 같습니다.
OneNote Notebook 파일은 지원되지 않습니다.
증분 인덱싱 제한 사항:
SharePoint 폴더의 이름을 바꾸면 증분 인덱싱이 중단됩니다. 이름이 바뀐 폴더는 새 콘텐츠로 처리됩니다.
인덱서는 콘텐츠가 변경되지 않은 경우에도 이전에 인덱싱된 문서를 다시 처리할 수 있습니다. 이 동작은 의도적으로 수행되며 누락된 변경 내용을 방지하고 데이터 무결성을 유지하는 데 도움이 됩니다. 재처리는 원본 시스템의 일시적인 오류에서 복구하는 동안 또는 Microsoft 365 프로세스가 SharePoint 메타데이터를 업데이트할 때 발생할 수 있습니다. 이러한 내부 이벤트는 고객 관련 문서 속성을 통해 표시되지 않을 수 있습니다.
파이프라인 구성에 따라 재처리는 AI 보강 및 임베딩 생성을 포함하여 다운스트림 서비스를 다시 호출할 수 있습니다. 인덱싱 시간, 용량 및 비용을 계획할 때 이 추가 처리를 고려하세요. 문제 해결은 동기화 재시도 이해를 참조하세요.
보안 제한 사항:
Foundry IQ에서 SharePoint Online으로의 연결은 퍼블릭 엔드포인트를 사용합니다. SharePoint Online은 지원되는 공유 프라이빗 링크 대상이 아니므로 이 원본에는 프라이빗 아웃바운드 연결을 사용할 수 없습니다. 애플리케이션은 여전히 인바운드 프라이빗 엔드포인트를 통해 검색에 연결할 수 있습니다. 인바운드 및 아웃바운드 네트워크 트래픽을 참조하세요.
Microsoft Entra ID 조건부 액세스 사용하도록 설정된 테넌트에 대한 지원은 없습니다.
사용자 암호화 파일 및 암호로 보호된 ZIP 파일은 지원되지 않습니다. 그러나 암호화된 콘텐츠는
Microsoft Purview 민감도 레이블 로 보호되고 해당 레이블(미리 보기) 유지 및 적용하기 위한구성이 사용되는 경우 허용됩니다. 문서 수준 액세스 권한은 SharePoint 권한 모델의 하위 집합을 지원합니다. SharePoint ACL 수집 및 필터링은 REST API
2026-10-01와 함께 일반 공급됩니다. 자세한 내용 및 설정은 SharePoint ACL 구성 설명서 참조하세요. 시나리오당 필요한 사용 권한은 사용 권한 설정 선택을 참조하세요.
SharePoint 그룹 권한 확인은 사이트 컨텍스트 필드가 로 표시된 경우
sharepointSiteUrl: true이 있습니다. 이 제한은 모든 권한 구성에 적용되지 않습니다. 더 많은 사이트에서 SharePoint 그룹 권한이 필요한 경우 별도의 인덱스 및 인덱싱된 지식 원본을 평가합니다. SharePoint 그룹 권한에 대한 토폴로지 계획 참조문서 라이브러리, 목록 및 최신 페이지 원본에는 별도의 인덱싱 범위 기본값이 있습니다. 개별 파일, 목록 항목 또는 페이지가 아닌 선택한 원본 위치 수를 계산합니다.
이 기능을 사용할 때 몇 가지 고려 사항은 다음과 같습니다.
Foundry IQ에서 SharePoint 콘텐츠 인덱스 없이 검색하려면 원격 SharePoint 지식 원본(미리 보기)을 고려하세요. Copilot 검색 API를 사용하여 사용자를 대신하여 SharePoint 텍스트 콘텐츠를 쿼리합니다. 이 옵션을 SharePoint 아키텍처 선택에서 인덱싱된 및 사용자 지정 수집 방법과 비교합니다.
프로덕션 환경에서 SharePoint 데이터와 채팅할 사용자 지정 Copilot/RAG 애플리케이션 또는 AI 에이전트를 만들어야 하는 경우 먼저 Microsoft Copilot Studio 통해 직접 빌드하는 것이 좋습니다. Copilot Studio 요구 사항을 충족하지 않는 경우 다음을 고려합니다.
SharePoint 웹후크를 사용하여 사용자 지정 커넥터를 만들고, Microsoft Graph API 호출하여 데이터를 Azure Blob 컨테이너로 내보낸 다음, 증분 인덱싱을 위해 Azure Blob 인덱서 사용합니다.
Azure Logic Apps 워크플로를 만들고, Azure Logic Apps SharePoint 커넥터 및 Foundry IQ 커넥터를 사용합니다. Foundry IQ 커넥터는 정식 출시되면 사용할 수 있습니다. Azure 포털 마법사에서 생성된 워크플로를 시작점으로 사용한 다음, Azure Logic Apps 디자이너 사용자 지정하여 필요한 변환 단계를 추가합니다. Foundry IQ 마법사에서 만드는 워크플로는 소비 워크플로입니다. 프로덕션 워크로드의 경우 표준 논리 앱 워크플로 로 전환하여 추가 엔터프라이즈 기능을 사용합니다.
선택한 방법에 관계없이 SharePoint 웹후크를 사용하여 사용자 지정 커넥터를 빌드하든 Azure Logic Apps 워크플로를 만들든 강력한 보안 조치를 구현해야 합니다. 이러한 조치에는 방화벽 설정 및 원본의 사용자 권한 유지 및 쿼리 시 해당 사용 권한 적용이 포함됩니다. 또한 파이프라인을 정기적으로 감사하고 모니터링해야 합니다.
SharePoint ACL 수집의 경우 SharePoint 그룹 내에 중첩된 Microsoft Entra 그룹은 최대 5개의 중첩된 수준까지 지원됩니다. 별도의 사이트 수준 보안 주체 제한도 적용됩니다. 구성 요구 사항 및 제한은 지원되는 그룹 관계를 참조하여 확인하세요.
인덱싱 토폴로지 계획
직접 구성된 파이프라인의 경우 리소스에는 별도의 책임이 있습니다.
| Resource | 책임 |
|---|---|
| Microsoft Entra 애플리케이션 및 SharePoint 사이트 권한 부여 | 선택한 콘텐츠에 대한 수집 액세스 권한을 부여합니다.
Sites.Selected를 사용하는 경우 선택한 각 사이트에 대한 액세스 권한을 부여합니다. |
| 데이터 원본 | 연결을 정의하고 사이트, 라이브러리, 목록, 페이지 또는 폴더를 선택합니다. 선택 영역은 액세스 권한을 부여하지 않습니다. |
| 인덱서 | 하나의 데이터 원본을 읽고 대상 인덱스 하나의 이름을 지정합니다 targetIndexName. 여러 사이트를 선택해도 여러 대상 인덱스가 자동으로 생성되지는 않습니다. |
| 검색 인덱스 | 필드를 정의하고 검색 가능한 콘텐츠, 메타데이터 및 검색 결과 검색에 사용되는 사용 권한 필드를 저장합니다. |
| 검색 인덱스 지식 원본 및 지식 기반 | 필요에 따라 에이전틱 검색을 위해 채워진 인덱스를 노출합니다. 이러한 검색 리소스는 인덱싱 구성 또는 사용자의 문서 권한을 대체하지 않습니다. |
예를 들어:
| Scenario | 리소스 정렬 |
|---|---|
| 여러 라이브러리 또는 폴더가 있는 하나의 사이트 | 한 데이터 원본에서 필요한 라이브러리 또는 폴더를 선택하고 콘텐츠가 대상 스키마 및 처리 요구 사항을 공유할 때 인덱서 하나를 사용합니다. |
| 기본 엔드포인트 A가 있는 선택된 사이트 B 및 C | 사이트 간 쿼리 구성을 사용하고, B 및 C에 대한 액세스 권한을 부여하고, 하나의 인덱서를 통해 하나의 대상 인덱스로 씁니다. 사용 권한 필터링에 이를 필요로 하는 경우 원래 사이트 컨텍스트를 유지합니다. |
| 별도의 스키마, 처리 일정 또는 거버넌스가 필요한 콘텐츠 | 별도의 인덱싱 파이프라인 및 인덱스를 사용합니다. 에이전트형 검색의 경우 검색 인덱스 지식 원본을 통해 각 인덱스를 노출하고 지식 베이스의 한도 내에서 원본을 할당합니다. |
인덱서의 단일 targetIndexName는 보강된 자식 문서를 다른 인덱스로 보낼 수 있는 인덱스 프로젝션과는 다릅니다. 검색 가능한 모든 청크는 필요한 권한 필드와 원래 사이트 컨텍스트를 유지해야 합니다.
ACL 매핑 및 프로젝션 지침을 따릅니다.
동일한 인덱스에 쓰는 인덱서를 추가해도 SharePoint 그룹 사이트 URL 제한이 증가하지는 않습니다. 해당 권한 흐름에는 기존 파티셔닝 지침을 사용합니다.
서비스 관리 수집을 선호하는 경우 이러한 인덱싱 리소스를 개별적으로 구성하는 대신 인덱싱된 SharePoint 지식 원본을 만듭니다. 아키텍처 및 소유권 선택은 SharePoint 아키텍처 선택 항목을 참조하세요.
Microsoft 365 인덱서에서 SharePoint 구성
2026-10-01 REST API를 사용하여 Microsoft 365의 SharePoint 인덱서를 구성합니다.
(선택 사항) 1단계: 시스템 할당 관리 ID 사용
시스템 할당 관리 ID를 사용하도록 설정하여 Foundry IQ 서비스가 프로비전된 Microsoft Entra 테넌트를 자동으로 검색합니다.
SharePoint 사이트 및 Foundry IQ 서비스가 동일한 Microsoft Entra 테넌트에 있는 경우 이 단계를 수행합니다. 다른 Microsoft Entra 테넌트에 있는 경우 이 단계를 건너뜁니다. ID는 테넌트 검색에 사용됩니다. 연결 문자열에 Microsoft Entra 테넌트 ID를 포함하려는 경우 이 단계를 건너뛸 수도 있습니다. 시스템 할당 또는 사용자가 할당한 관리 ID를 비밀 없는 인덱싱에 사용하려면 비밀 없는 인증을 사용하여 애플리케이션 권한을 구성합니다.
저장을 선택하면 Foundry IQ 서비스에 할당된 개체 ID가 표시됩니다.
2단계: 인덱서에 필요한 권한 결정
ACL 및 비 ACL 시나리오를 다루는 의사 결정 매트릭스는 사용 권한 설정 선택을 참조하세요. 위임된 권한을 선택하는 경우 사용자 위임 토큰은 75분마다 만료되며 만료될 때 Run Indexer 를 사용하여 수동 인덱싱이 필요합니다. 위임된 권한은 소규모 테스트 작업에만 권장됩니다.
3단계: Microsoft Entra 애플리케이션 등록 만들기
Microsoft 365 인덱서의 SharePoint 인증에 Microsoft Entra 애플리케이션을 사용합니다. 권한 및 자격 증명을 구성하기 전에 애플리케이션 등록을 만듭니다.
Azure 포털 로그인합니다.
Microsoft Entra ID를 검색하거나 해당 항목으로 이동하세요.
개요 페이지에서 +앱 등록>를 선택합니다.
- 앱의 이름을 입력합니다.
- 단일 테넌트만 선택 - 테넌트 이름.
- URI 지정 단계를 건너뜁니다. 리디렉션 URI가 필요하지 않습니다.
- 등록을 선택합니다.
왼쪽 창에서API 권한> 선택합니다.
+ 사용 권한 추가를 선택한 다음, Microsoft Graph 선택합니다.
인덱서가 애플리케이션 API 권한을 사용하는 경우 애플리케이션 권한을 선택합니다.
표준 인덱싱의 경우 다음을 선택합니다.
Files.Read.AllSites.Read.All
ACL 수집을 사용하도록 설정하는 경우 필요한 사용 권한은 인덱싱하는 항목 유형(문서 라이브러리 파일, 목록 항목, ASPX 페이지) 및 그룹 유형(Microsoft Entra 및 SharePoint 사이트 그룹)에 따라 달라집니다. 이 단계를 완료하기 전에 ACL별 사용 권한 시나리오를 참조하세요. 교차 시나리오 요약은 사용 권한 설정 선택을 참조하세요.
애플리케이션 권한을 사용하면 인덱서가 서비스 컨텍스트에서 SharePoint 사이트에 액세스합니다. 따라서 인덱서가 실행되면 테넌트 관리자 승인이 필요한 SharePoint 테넌트에 있는 모든 콘텐츠에 액세스할 수 있습니다. 인증에는 클라이언트 비밀 또는 비밀 없는 구성도 필요합니다. 인증 메커니즘 설정은 이 문서의 뒷부분에서 애플리케이션 API 권한에 대해서만 사용 가능한 인증 방법에 대해 설명합니다.
인덱서가 위임된 API 권한을 사용하는 경우 위임된 권한을 선택한 다음, 다음을 선택합니다.
Files.Read.AllSites.Read.AllUser.Read
위임된 권한을 사용하면 검색 클라이언트가 현재 사용자의 보안 ID 아래 SharePoint 연결할 수 있습니다.
테넌트 이름에 대한 관리자 동의 부여를 선택합니다.
애플리케이션 API 권한을 사용하는 경우 테넌트 관리자 동의가 필요합니다. 일부 테넌트는 위임된 API 권한에도 테넌트 관리자 동의가 필요한 방식으로 잠겨 있습니다. 두 조건 중 하나가 적용되는 경우 테넌트 관리자는 인덱서를 만들기 전에 이 Microsoft Entra 애플리케이션에 대한 동의를 부여해야 합니다.
왼쪽 창에서 인증 관리>(미리 보기)를 선택합니다.
리디렉션 URI 구성 탭에서 + 리디렉션 URI 추가를 선택합니다.
- 모바일 및 데스크톱 애플리케이션을 선택합니다.
- 리디렉션 URI를
https://login.microsoftonline.com/common/oauth2/nativeclient선택합니다. - 설정을 선택합니다.
설정 탭에서 공용 클라이언트 흐름 허용 토글을 사용하도록 설정한 다음 저장을 선택합니다.
솔루션 요구 사항에 따라 인덱서 인증 방법을 구성합니다.
사이트 액세스 권한 부여(Sites.Selected 사용 시)
앱 등록 Sites.Selected을 구성하는 경우 인덱서 실행 전에 다음 단계를 완료합니다. Microsoft Entra ID 관리자 Sites.Selected 동의는 앱이 범위가 지정된 SharePoint 권한만 사용할 수 있도록 허용합니다. 사이트 권한을 별도로 할당할 때까지 사이트에 대한 액세스 권한을 부여하지 않습니다.
Microsoft Entra ID에서: 앱 등록에
Sites.Selected를 추가하고 관리자 동의를 부여합니다. 시나리오에 필요한 권한을 API 영역 아래에 추가하세요. 예를 들어 Microsoft Graph를 추가하고, ACL 수집 시나리오의 경우 SharePoint를 추가하세요.SharePoint: 앱에 각 대상 사이트에 대한 권한 역할을 할당합니다. 콘텐츠 인덱싱의 경우 읽기 권한 이상을 부여합니다.
사이트 권한을 부여하려면 Microsoft Graph 사용합니다.
{siteId}를 사이트 ID로 바꾸세요:POST https://graph.microsoft.com/v1.0/sites/{siteId}/permissions Content-Type: application/json { "roles": ["read"], "grantedToIdentities": [ { "application": { "id": "<application-client-id>", "displayName": "<application-display-name>" } } ] }PnP PowerShell을 사용하여 동일한 권한을 부여하려면 다음을 수행합니다.
Grant-PnPEntraIDAppSitePermission ` -AppId "<application-client-id>" ` -DisplayName "<application-display-name>" ` -Site "https://<tenant>.sharepoint.com/sites/<site-name>" ` -Permissions Read
애플리케이션 API 권한에만 사용 가능한 인증 방법
애플리케이션 권한을 사용하여 Microsoft Entra 애플리케이션을 인증하기 위해 인덱서는 클라이언트 암호 또는 비밀 없는 구성을 사용합니다.
클라이언트 암호 사용
이러한 지침은 SharePoint 데이터를 수집할 수 있도록 클라이언트 비밀을 사용하여 인덱서를 인증하도록 애플리케이션을 구성합니다.
왼쪽 메뉴에서 인증서 및 비밀을 선택한 다음 클라이언트 비밀 및 새 클라이언트 암호를 선택합니다.
팝업 메뉴에서 새 클라이언트 비밀에 대한 설명을 입력합니다. 필요한 경우 만료 날짜를 조정합니다. 비밀이 만료되면 비밀을 다시 만들고 인덱서가 새 비밀로 업데이트되어야 합니다.
새 클라이언트 암호가 비밀 목록에 나타납니다. 페이지에서 이동하면 비밀이 표시되지 않으므로 복사 단추를 사용하여 값을 복사하고 안전한 위치에 저장합니다.
비밀 없는 인증을 사용하여 애플리케이션 토큰 가져오기
페더레이션된 자격 증명을 사용하여 클라이언트 암호 없이 로그인합니다. Microsoft Entra 관리 ID를 신뢰하여 애플리케이션 토큰을 가져오므로 인덱서는 저장된 비밀 없이 SharePoint 데이터를 수집할 수 있습니다. 다음 섹션에서는 관리 ID 구성을 안내합니다.
관리 ID를 사용하여 등록된 애플리케이션 구성
시나리오 요구 사항에 따라 사용자 할당 관리 ID를 만들고(또는 선택하고) Foundry IQ 서비스에 할당하거나 시스템 할당 관리 ID를 사용합니다.
개체(보안 주체) ID를 캡처합니다. 데이터 원본을 만들 때 자격 증명 구성의 일부로 이 값을 사용합니다.
왼쪽 메뉴에서 인증서 및 비밀을 선택합니다.
페더레이션된 자격 증명에서 + 자격 증명 추가를 선택합니다.
페더레이션 자격 증명 시나리오에서 관리 ID를 선택합니다.
관리 ID 선택: 1단계에서 만든 관리 ID를 선택합니다.
자격 증명의 이름을 추가하고 저장을 선택합니다.
4단계: 데이터 원본 만들기
나머지 단계에서는 API 버전 2026-10-01 과 함께 REST 클라이언트를 사용합니다.
데이터 원본은 데이터의 변경 내용(새 행, 수정 또는 삭제된 행)을 효율적으로 식별하기 위해 인덱싱할 데이터, 자격 증명 및 정책을 지정합니다. 동일한 Foundry IQ 서비스의 여러 인덱서는 동일한 데이터 원본을 사용할 수 있습니다.
SharePoint 인덱싱의 경우 데이터 원본에는 다음과 같은 필수 속성이 있어야 합니다.
- name은 Foundry IQ 서비스 내의 데이터 원본의 고유한 이름입니다.
- 형식은 "SharePoint"여야 합니다. 이 값은 대/소문자를 구분합니다.
-
자격 증명은 애플리케이션이 Microsoft Entra 토큰을 요청하는 데 허용되는 SharePoint 엔드포인트 및 인증 방법을 제공합니다. SharePoint 엔드포인트의 예는
https://[your-tenant-name].sharepoint.com/teams/MySharePointSite. SharePoint 사이트의 홈페이지로 이동하고 브라우저에서 URL을 복사하여 엔드포인트를 가져올 수 있습니다. 지원되는 구문에 대해 연결 문자열 형식을 검토하세요. - 컨테이너 는 인덱싱할 문서 라이브러리, 목록 또는 사이트 페이지를 선택합니다. 해당 속성은 인덱싱되는 문서를 제어합니다.
데이터 원본을 만들려면 Create Data Source를 호출합니다.
다음은 애플리케이션 비밀 또는 시스템 할당 관리 ID를 사용하는 자격 증명에 대한 데이터 원본 정의 샘플입니다.
POST https://[service name].search.windows.net/datasources?api-version=2026-10-01
Content-Type: application/json
api-key: [admin key]
{
"name" : "sharepoint-datasource",
"type" : "sharepoint",
"credentials" : { "connectionString" : "[connection-string]" },
"container" : { "name" : "defaultSiteLibrary", "query" : null }
}
페더레이션된 자격 증명 구성에는 연결 문자열에 FederatedCredentialApplicationId가 필요합니다. 값은 ID 유형에 따라 다릅니다.
-
시스템 할당 관리 ID:
FederatedCredentialApplicationId를 서비스의 시스템 할당 관리 ID 애플리케이션(클라이언트) ID로 설정합니다. 블록을 생략합니다identity. -
사용자 할당 관리 ID:
identity블록에 사용자 할당 관리 ID의 리소스 경로를 제공합니다.FederatedCredentialApplicationId를 사용자 할당 관리 ID 자체의 애플리케이션(클라이언트) ID로 설정합니다.
참고
ApplicationId와 FederatedCredentialApplicationId은 서로 다른 값입니다.
ApplicationId는 SharePoint 권한을 보유하는 등록된 Entra 수집 앱입니다.
FederatedCredentialApplicationId 는 관리 ID 자체의 애플리케이션(클라이언트) ID로, 이 관리 ID의 토큰이 해당 관리 ID의 신원을 증명하는 주체입니다.
POST https://[service name].search.windows.net/datasources?api-version=2026-10-01
Content-Type: application/json
api-key: [admin key]
{
"name" : "sharepoint-datasource",
"type" : "sharepoint",
"credentials" : { "connectionString" : "[connection-string]" },
"container" : { "name" : "defaultSiteLibrary", "query" : null },
"identity": {
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
"userAssignedIdentity": "/subscriptions/[Azure subscription ID]/resourceGroups/[resource-group]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[user-assigned managed identity]"
}
}
연결 문자열 형식
연결 문자열 형식은 인덱서가 위임된 API 권한 또는 애플리케이션 API 권한을 사용하는지 여부에 따라 변경됩니다.
위임된 API 권한의 연결 문자열 형식
SharePointOnlineEndpoint=[SharePoint site URL];ApplicationId=[Microsoft Entra application ID];TenantId=[SharePoint site's Microsoft Entra tenant ID]애플리케이션 비밀 연결 문자열 형식의 애플리케이션 API 권한
SharePointOnlineEndpoint=[SharePoint site URL];ApplicationId=[Microsoft Entra application ID];ApplicationSecret=[Microsoft Entra application client secret];TenantId=[SharePoint site's Microsoft Entra tenant ID]비밀 없는(페더레이션 ID 자격 증명) 연결 문자열 형식의 애플리케이션 API 권한:
SharePointOnlineEndpoint=[SharePoint site URL];ApplicationId=[Microsoft Entra application ID];FederatedCredentialApplicationId=[managed identity's application (client) ID];TenantId=[SharePoint site's Microsoft Entra tenant ID]
다음 표에서는 각 연결 문자열 필드에 대해 설명합니다.
| Field | 필수 | 설명 |
|---|---|---|
SharePointOnlineEndpoint |
Yes | 기본 SharePoint 사이트 URL(예: https://[your-tenant-name].sharepoint.com)입니다.
useQuery 컨테이너는 동일한 테넌트에서 다른 사이트를 선택할 수 있습니다.
다른 사이트의 콘텐츠 선택을 확인하세요. |
ApplicationId |
Yes | 수집 앱의 Microsoft Entra 애플리케이션(클라이언트) ID입니다. 유효한 GUID여야 합니다. |
TenantId |
Optional | SharePoint 사이트를 소유한 테넌트의 Microsoft Entra 테넌트 ID(GUID) 이 테넌트가 Foundry IQ 서비스와 연관된 Microsoft Entra 테넌트인 것은 아닙니다. SharePoint 사이트 및 Foundry IQ 서비스가 서로 다른 Microsoft Entra 테넌트에 있는 경우 필요합니다. |
ApplicationSecret |
Conditional | 수집 앱의 클라이언트 암호입니다. 비밀 기반 인증에 사용합니다. |
FederatedCredentialApplicationId |
조건부(페더레이션 ID 자격 증명) | 관리 ID의 유효성을 검사하는 데 사용되는 Microsoft Entra 애플리케이션(클라이언트) ID. 유효한 GUID여야 합니다. 시스템 할당 관리 ID의 경우 ID의 애플리케이션(클라이언트) ID를 사용합니다. 사용자 할당 관리 ID의 경우 ID의 자체 애플리케이션(클라이언트) ID를 사용합니다.
federatedIdentityClientId 블록에서 identity가 설정된 교차 테넌트 사용자 할당 관리 ID의 경우 다중 테넌트 앱의 클라이언트 ID를 사용합니다. |
중요
FederatedCredentialApplicationId 및 ApplicationSecret는 상호 배타적입니다. 이러한 문자열을 결합하는 연결 문자열은 데이터 원본 만들기 또는 업데이트에서 거부됩니다.
사용 권한을 설정할 때 다음 정보를 고려합니다.
이전 버전과의 호환성을 위해 SharePoint 인덱서는 연결 문자열에서 여전히
FederatedCredentialObjectId(수집 앱의 페더레이션 ID 자격 증명에 대한 개체/보안 주체 ID)를 허용하므로 기존 데이터 원본은 변경 없이 계속 작동합니다.FederatedCredentialApplicationId을 새 데이터 원본 및 업데이트된 데이터 원본에 사용합니다.
TenantId를 가져오려면 SharePoint 사이트를 소유한 테넌트의 Microsoft Entra 관리 센터를 열고 개요에서 테넌트 ID를 복사합니다.
관리 ID object (principal) ID 섹션을 사용하여 등록된 애플리케이션 구성에서 관리 ID를 가져올 수 있습니다.
사용 권한을 설정할 때 다음 정보를 고려합니다.
SharePoint 사이트 및 Foundry IQ 서비스가 동일한 Microsoft Entra 테넌트에 있고 시스템 할당 관리 ID가 사용하도록 설정된 경우 연결 문자열에
TenantId를 포함할 필요가 없습니다. 서로 다른 Microsoft Entra 테넌트에 있는 경우TenantId를 포함해야 합니다.
다음 예는 FederatedCredentialApplicationId로 생성된 데이터 원본을 보여 줍니다:
페더레이션 자격 증명이 있는 시스템 할당 관리 ID:
POST https://[service name].search.windows.net/datasources?api-version=2026-10-01
Content-Type: application/json
api-key: [admin key]
{
"name": "sharepoint-ds",
"type": "sharepoint",
"credentials": {
"connectionString": "SharePointOnlineEndpoint=https://[your-tenant-name].sharepoint.com;ApplicationId=[Microsoft Entra application ID];TenantId=[SharePoint site's Microsoft Entra tenant ID];FederatedCredentialApplicationId=[system-assigned managed identity's application (client) ID]"
},
"container": { "name": "defaultSiteLibrary" }
}
페더레이션 자격 증명을 사용하는 사용자 할당 관리 ID(단일 테넌트):
{
"name": "sharepoint-uami-fed",
"type": "sharepoint",
"credentials": {
"connectionString": "SharePointOnlineEndpoint=https://[your-tenant-name].sharepoint.com;ApplicationId=[Microsoft Entra application ID];TenantId=[SharePoint site's Microsoft Entra tenant ID];FederatedCredentialApplicationId=[user-assigned managed identity application (client) ID]"
},
"container": { "name": "defaultSiteLibrary" },
"identity": {
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
"userAssignedIdentity": "/subscriptions/[subscription-id]/resourceGroups/[resource-group]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[uami-name]"
}
}
참고
사용자 할당 관리형 ID의 경우 FederatedCredentialApplicationId는 수집 앱의 ID(ApplicationId)가 아니라 사용자 할당 관리형 ID의 애플리케이션(클라이언트) ID와 같아야 합니다. 블록을 생략 identity 하면 인덱서가 시스템 할당 관리 ID로 돌아갑니다.
연동 자격 증명이 있는 테넌트 간 사용자 할당 관리형 ID(고급):
이 구성을 사용하기 전에 사용자가 할당한 관리 ID가 다중 테넌트 Microsoft Entra 앱을 신뢰하는 페더레이션 ID 자격 증명으로 구성되었는지 확인합니다. 설정 단계는 관리 ID를 사용하여 등록된 애플리케이션 구성을 참조하세요.
{
"name": "sharepoint-uami-crosstenantfed",
"type": "sharepoint",
"credentials": {
"connectionString": "SharePointOnlineEndpoint=https://[your-tenant-name].sharepoint.com;ApplicationId=[Microsoft Entra application ID];TenantId=[SharePoint site's Microsoft Entra tenant ID];FederatedCredentialApplicationId=[multitenant app client ID]"
},
"container": { "name": "defaultSiteLibrary" },
"identity": {
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
"userAssignedIdentity": "/subscriptions/[subscription-id]/resourceGroups/[resource-group]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[uami-name]",
"federatedIdentityClientId": "[multi-tenant app client ID]"
}
}
사용자가 할당한 관리 ID 자체가 다중 테넌트 Microsoft Entra 앱에 페더레이션되는 경우 테넌트 간 사용자 할당 관리 ID 구성을 사용합니다. 이 경우 identity 블록에서 federatedIdentityClientId를 다중 테넌트 앱의 클라이언트 ID로 설정하고, 연결 문자열에서 FederatedCredentialApplicationId를 동일한 다중 테넌트 앱의 클라이언트 ID로 설정합니다. 이 시나리오에서 사용자 할당 관리 ID의 자체 클라이언트 ID로 설정 FederatedCredentialApplicationId 하면 유효성 검사가 실패합니다.
인덱서가 SharePoint ACL 구성을 사용하거나 Microsoft Purview 민감도 레이블(미리 보기)을 유지 및 적용하는 경우 인덱서 만들기 전에 관련 문서를 검토합니다. 각 기능에는 특정 데이터 원본, 인덱스 및 기술 세트 구성 단계가 있습니다.
5단계: 인덱스 만들기
인덱스는 검색 환경을 형성하는 문서, 특성 및 기타 구문의 필드를 지정합니다.
인덱스를 만들려면 인덱스 만들기를 선택합니다.
POST https://[service name].search.windows.net/indexes?api-version=2026-10-01
Content-Type: application/json
api-key: [admin key]
{
"name" : "sharepoint-index",
"fields": [
{ "name": "id", "type": "Edm.String", "key": true, "searchable": false },
{ "name": "metadata_spo_item_name", "type": "Edm.String", "key": false, "searchable": true, "filterable": false, "sortable": false, "facetable": false },
{ "name": "metadata_spo_item_path", "type": "Edm.String", "key": false, "searchable": false, "filterable": false, "sortable": false, "facetable": false },
{ "name": "metadata_spo_item_content_type", "type": "Edm.String", "key": false, "searchable": false, "filterable": true, "sortable": false, "facetable": true },
{ "name": "metadata_spo_item_last_modified", "type": "Edm.DateTimeOffset", "key": false, "searchable": false, "filterable": false, "sortable": true, "facetable": false },
{ "name": "metadata_spo_item_size", "type": "Edm.Int64", "key": false, "searchable": false, "filterable": false, "sortable": false, "facetable": false },
{ "name": "content", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false }
]
}
중요
Microsoft 365 인덱서의 SharePoint 채워진 인덱스의 키 필드는 데이터 원본의 컨테이너 형식에 따라 달라집니다.
- 문서 라이브러리 콘텐츠(
defaultSiteLibrary,allSiteLibraries또는 라이브러리 또는 폴더 필터가 있는useQuery)의 경우metadata_spo_site_library_item_id를 사용하세요. 데이터 원본metadata_spo_site_library_item_id에 키 필드가 없으면 키 필드에 자동으로 매핑됩니다. - 목록, 페이지 또는 혼합 콘텐츠(
allSiteLists,allSitePages또는allSiteContent)의 경우,metadata_spo_site_asset_item_id를 사용하세요. 자동 매핑은 이 필드에 적용되지 않습니다.fieldMappings를 인덱스 키 필드에 매핑하는 명시적metadata_spo_site_asset_item_id항목을 정의합니다.
base64Encode 이러한 키 필드를 인덱스 id 필드에 매핑할 때 매핑 함수를 적용합니다.
6단계: 인덱서 만들기
인덱서는 데이터 원본을 대상 검색 인덱스에 연결하고 데이터 새로 고침을 자동화하는 일정을 제공합니다. 데이터 원본 및 인덱스 만들기 후 인덱서 만들기
인덱서 만들기:
인덱서 만들기 요청을 보냅니다.
POST https://[service name].search.windows.net/indexers?api-version=2026-10-01 Content-Type: application/json api-key: [admin key] { "name" : "sharepoint-indexer", "dataSourceName" : "sharepoint-datasource", "targetIndexName" : "sharepoint-index", "parameters": { "batchSize": null, "maxFailedItems": null, "maxFailedItemsPerBatch": null, "configuration": { "indexedFileNameExtensions" : ".pdf, .docx", "excludedFileNameExtensions" : ".png, .jpg", "dataToExtract": "contentAndMetadata" } }, "fieldMappings" : [ { "sourceFieldName" : "metadata_spo_site_library_item_id", "targetFieldName" : "id", "mappingFunction" : { "name" : "base64Encode" } } ] }allSiteLists,allSitePages또는allSiteContent컨테이너 값을 사용하는 데이터 원본의 경우metadata_spo_site_asset_item_id대신metadata_spo_site_library_item_id을 매핑하세요.문서 라이브러리 예제에는
.pdf및.docx파일만 포함됩니다. 인덱싱하려는 콘텐츠와 일치하도록 파일 형식 필터 를 조정합니다.애플리케이션 권한을 사용하는 경우 초기 인덱서 실행이 진행 중인 동안 인덱스를 쿼리할 수 있지만 이미 인덱싱된 항목만 결과를 반환합니다. 전체 검사를 위해 실행이 완료될 때까지 기다립니다. 이 단계의 나머지 지침은 위임된 권한에만 적용됩니다.
인덱서를 처음으로 만들면 다음 단계를 완료할 때까지 인덱서 만들기 요청이 대기합니다. 인덱서 상태 가져오기를 호출하여 링크를 가져와서 새 디바이스 코드를 입력해야 합니다.
GET https://[service name].search.windows.net/indexers/sharepoint-indexer/status?api-version=2026-10-01 Content-Type: application/json api-key: [admin key]10분 이내에 인덱서 상태 가져오기 를 호출하지 않으면 코드가 만료되고 데이터 원본을 다시 만들어야 합니다.
인덱서 상태 가져오기 응답에서 디바이스 로그인 코드를 복사합니다. 디바이스 로그인 코드는 "errorMessage"에서 찾을 수 있습니다.
{ "lastResult": { "status": "transientFailure", "errorMessage": "To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code <CODE> to authenticate." } }오류 메시지에 포함된 코드를 입력합니다.
Microsoft 365의 SharePoint 인덱서는 로그인한 사용자의 자격으로 SharePoint 콘텐츠에 액세스합니다. 이 단계에서 로그인하는 사용자는 로그인한 사용자입니다. 따라서 인덱싱하려는 문서 라이브러리의 문서에 액세스할 수 없는 사용자 계정으로 로그인하면 인덱서에서 해당 문서에 액세스할 수 없습니다.
가능하면 새 조직 사용자 계정을 만들고 인덱서에 부여할 정확한 권한을 부여합니다.
요청 중인 사용 권한을 승인합니다.
앞에서 제공된 모든 권한이 올바르고 10분 이내인 경우 인덱서 만들기 초기 요청이 완료됩니다.
사용 권한을 설정할 때 다음 정보를 고려합니다.
Microsoft Entra 애플리케이션에 관리자 승인이 필요하고 로그인하기 전에 승인되지 않은 경우 다음 화면이 표시될 수 있습니다. 관리자 승인이 필요합니다. 계속하려면.
![]()
7단계: 인덱서 상태 확인
인덱서 만들기 후 인덱서 상태 가져오기를 호출합니다.
GET https://[service name].search.windows.net/indexers/sharepoint-indexer/status?api-version=2026-10-01
Content-Type: application/json
api-key: [admin key]
lastResult 최신 실행status의 , endTime및 itemsProcesseditemsFailed. 실행이 성공을 보고하더라도 오류 및 경고를 검토합니다. 최상위 인덱서 상태 running는 현재 실행이 진행 중임을 의미하는 것이 아니라, 인덱서를 실행할 수 있음을 의미합니다.
인덱서 실행 모니터링을 참조하세요.
실행이 완료된 후 다음 쿼리를 사용하여 문서 수준 권한 필터링이 없는 인덱스를 확인합니다.
GET https://[service-name].search.windows.net/indexes/[index-name]/docs?search=*&$count=true&api-version=2026-10-01
api-key: [admin-api-key]
권한 사용이 설정된 인덱스의 경우 대신 권한 수집 검사를 따르세요. 권한 있는 elevated-read 쿼리를 사용하여 보호된 콘텐츠를 검사합니다. 관리자 키만으로는 ACL로 보호되는 콘텐츠를 반환하지 않습니다.
문서 개수뿐만 아니라 알려진 소스 항목 content 및 메타데이터를 확인합니다. 목록 항목 및 최신 페이지의 경우 예상 콘텐츠 표현과 결과를 비교합니다. SharePoint 그룹 확인 기능을 구성한 경우 문서 및 프로젝팅된 청크에서 원본 사이트 필드도 확인합니다.
권한 필터링된 쿼리를 사용하여 관리자 권한 읽기 헤더 없이 허용된 사용자와 거부된 사용자를 개별적으로 테스트합니다. 승격된 읽기 권한은 최종 사용자 쿼리의 대안으로 사용하지 말고, 권한 있는 관리 조사에만 사용하세요.
데이터 원본 업데이트
인덱서 예제에서는 일정을 구성하지 않습니다. 나중에 원본 변경 내용을 처리하려면 인덱서 일정을 구성하거나인덱서를 수동으로 실행하세요. 위임된 인증도 토큰이 만료되면 다음 섹션에 있는 로그인 절차가 여전히 필요합니다.
디바이스 코드가 만료되는 동안 데이터 원본을 변경하면 다시 로그인하여 인덱서가 실행됩니다. 예를 들어 데이터 원본 쿼리를 변경하는 경우 새 디바이스 코드를 사용하여 https://microsoft.com/devicelogin 다시 로그인합니다.
데이터 원본을 업데이트하려면 만료된 디바이스 코드를 가정하여 다음 단계를 수행합니다.
Run Indexer를 호출하여 인덱서 실행을 수동으로 시작합니다.
POST https://[service name].search.windows.net/indexers/sharepoint-indexer/run?api-version=2026-10-01 Content-Type: application/json api-key: [admin key]-
GET https://[service name].search.windows.net/indexers/sharepoint-indexer/status?api-version=2026-10-01 Content-Type: application/json api-key: [admin key] https://microsoft.com/devicelogin에 방문하라는 오류가 발생하면 해당 페이지를 열고 새 코드를 복사합니다.코드를 대화 상자에 붙여넣습니다.
인덱서를 수동으로 다시 실행하고 인덱서 상태를 확인합니다. 이번에는 인덱서 실행이 성공적으로 시작됩니다.
인덱싱된 콘텐츠 이해하기
content 필드에는 파일, 목록 항목 및 최신 페이지에 대한 다양한 표현이 포함됩니다.
| SharePoint 자산 |
content의 표현 |
|---|---|
| 문서 라이브러리 파일 | 구성된 문서 추출 경로를 사용하여 파일에서 추출된 텍스트입니다. |
| 목록 항목 | JSON 형식의 필드 값입니다. 필드 매핑을 위해 개별 열에 액세스할 수도 있습니다. |
| 최신 ASPX 사이트 페이지 | HTML 태그 및 JSON 이스케이프 시퀀스를 포함할 수 있는 직렬화된 페이지 필드입니다. 이 표현은 렌더링된 페이지와 일치하는 일반 텍스트로 보장되지 않습니다. |
목록 및 페이지의 경우 직렬화된 콘텐츠에는 필드 이름 및 표시되는 텍스트 이외의 다른 값이 포함될 수 있습니다. 청크 분할 또는 임베딩을 구성하기 전에 content에 전달된 입력을 검사합니다.
인덱싱된 SharePoint 지식 원본은 목록 및 페이지 전용 선택 영역에 text 구문 분석을 사용하는 인덱서를 생성합니다.
allSiteContent 구문 분석을 문서 라이브러리 또는 default와 같은 혼합 선택에 사용합니다.
인덱서 구문 분석 모드는 다운스트림 기술 세트 처리와는 별개입니다.
관리되는 다국어 수집의 경우 인덱싱된 SharePoint 지식 원본은 언어별 자동 분석기(미리 보기)를 지원합니다. 인덱스를 직접 구성하는 경우 해당 인덱스의 검색 가능한 문자열 필드에 언어 분석기를 할당합니다. 이러한 구성 경로는 별개입니다.
인덱스 문서 메타데이터
문서 메타데이터()"dataToExtract": "contentAndMetadata"를 인덱싱하는 경우 인덱싱에 다음 메타데이터를 사용할 수 있습니다.
| 식별자 | 타입 | 설명 |
|---|---|---|
| metadata_spo_site_library_item_id | Edm.String | 사이트의 문서 라이브러리에서 항목을 고유하게 식별하는 사이트 ID, 라이브러리 ID 및 항목 ID의 조합 키입니다. 이 필드를 , defaultSiteLibrary및 allSiteLibraries (라이브러리 또는 폴더 필터) 컨테이너 값의 useQuery인덱스 키로 사용합니다. |
| metadata_spo_site_asset_item_id | Edm.String | 목록 항목, ASPX 사이트 페이지 또는 혼합 콘텐츠 모드의 자산을 고유하게 식별하는 조합 키입니다. 이 필드를 , allSiteLists및 allSitePages 컨테이너 값의 allSiteContent인덱스 키로 사용합니다. |
| metadata_spo_site_id | Edm.String | SharePoint 사이트의 ID입니다. |
| metadata_spo_library_id | Edm.String | 문서 라이브러리의 ID입니다. |
| metadata_spo_item_id | Edm.String | 라이브러리에 있는 (문서) 항목의 ID입니다. |
| 메타데이터_SPO_항목_최종_수정 | Edm.DateTimeOffset | 항목의 마지막으로 수정된 날짜/시간(UTC)입니다. |
| metadata_spo_item_name (메타데이터 SPO 항목 이름) | Edm.String | 항목의 이름입니다. |
| metadata_spo_item_size | Edm.Int64 | 항목의 크기(바이트)입니다. |
| 메타데이터_spo_항목_콘텐츠_유형 | Edm.String | 항목의 콘텐츠 형식입니다. |
| metadata_spo_item_extension | Edm.String | 항목의 확장입니다. |
| metadata_spo_item_weburi | Edm.String | 항목의 URI입니다. |
| metadata_spo_item_path | Edm.String | 부모 경로와 항목 이름의 조합입니다. |
| metadata_spo_site_url | Edm.String | SharePoint 사이트의 URL입니다. SharePoint 사이트 그룹 확인 기능을 사용하도록 설정할 때 필요합니다. SharePoint 그룹 지원 구성 참조하세요. |
Microsoft 365 인덱서의 SharePoint 각 문서 유형과 관련된 메타데이터도 지원합니다. 자세한 내용은 Foundry IQ에서 사용되는 콘텐츠 메타데이터 속성을 참조하세요.
직접 구성된 인덱서에서 사용자 지정 문서 라이브러리 메타데이터를 노출하려면 additionalColumns에 를 지정합니다. 그런 다음 필드 매핑을 사용하여 노출된 원본 필드를 호환되는 인덱스 필드에 매핑합니다. 열을 선택하고 매핑하는 단계는 별개의 단계입니다. 매핑은 데이터 원본이 노출하지 않은 열을 가져오지 않습니다.
사용자 지정 필드를 추가할 때 키 매핑 과 필요한 권한 및 원래 사이트 매핑을 유지합니다 . SharePoint list 열의 경우 목록 열을 인덱스 필드에 매핑을 따르세요.
SharePoint 목록 인덱싱
사이트의 모든 container.name 항목을 인덱싱하려면 데이터 원본 을 allSiteLists로 설정합니다.
allSiteContent를 사용하여 목록 항목을 문서 라이브러리 및 사이트 페이지와 결합하여 단일 인덱서로 만듭니다. 하위 사이트 목록을 포함하려면 includeSubsites=true을(를) container.query에 추가하세요.
목록 기반 또는 혼합 콘텐츠 인덱서의 경우 인덱스 키 필드는 metadata_spo_site_asset_item_id에서 매핑되어야 합니다. 목록 항목 콘텐츠는 content 필드에 JSON 형식의 필드 값으로 표시되며, 표준 metadata_spo_item_* 필드(예: metadata_spo_item_name, metadata_spo_item_weburi, metadata_spo_item_last_modified)는 각 목록 항목마다 채워집니다.
목록 열을 인덱스 필드에 매핑
SharePoint list 정의한 각 열은 SharePoint 열과 이름이 같은 원본 필드로 표시됩니다. 필드 매핑을 사용하여 각 열을 인덱스 필드에 매핑합니다.
예를 들어 다음 열이 있는 SharePoint list 고려해 보세요.
| SharePoint 열 | SharePoint 열 형식 |
|---|---|
Title |
단일 텍스트 줄 |
Price |
Number |
InStock |
예/아니요 |
Category |
선택 |
일치하는 필드를 인덱스 정의에 추가한 다음 각 열을 인덱서의 대상 필드에 매핑합니다.
{
"name": "my-sharepoint-list-indexer",
"dataSourceName": "my-sharepoint-list-ds",
"targetIndexName": "products-index",
"fieldMappings": [
{
"sourceFieldName": "metadata_spo_site_asset_item_id",
"targetFieldName": "id",
"mappingFunction": { "name": "base64Encode" }
},
{ "sourceFieldName": "Title", "targetFieldName": "productName" },
{ "sourceFieldName": "Price", "targetFieldName": "price" },
{ "sourceFieldName": "InStock", "targetFieldName": "available" },
{ "sourceFieldName": "Category", "targetFieldName": "category" },
{ "sourceFieldName": "metadata_spo_item_last_modified", "targetFieldName": "lastUpdated" },
{ "sourceFieldName": "metadata_spo_item_weburi", "targetFieldName": "itemUrl" }
]
}
각 대상 필드가 호환되는 형식(예 Edm.StringTitleEdm.DoubleEdm.Int64: 의 경우)을 사용하여 인덱스에 PriceEdm.BooleanInStock있는지 확인합니다.
ASPX 사이트 페이지 인덱싱
사이트의 모든 최신 ASPX 사이트 페이지를 인덱싱하도록 allSitePages 데이터 원본 container.name 을 설정합니다.
allSiteContent를 사용하여 페이지를 문서 라이브러리 및 목록과 결합해 단일 인덱서에서 처리합니다. 하위 사이트 페이지를 포함하려면 includeSubsites=true에 container.query를 추가합니다.
페이지 기반 또는 혼합 콘텐츠 인덱서의 경우 인덱스 키 필드는 metadata_spo_site_asset_item_id에서 매핑되어야 합니다. 이 content 필드는 브라우저에서 렌더링된 일반 텍스트가 아닌 HTML 태그 및 JSON 이스케이프 시퀀스를 포함할 수 있는 직렬화된 페이지 필드를 받습니다. 표준 metadata_spo_item_* 필드(예: metadata_spo_item_name, metadata_spo_item_weburi및 metadata_spo_item_last_modified)는 각 페이지에 대해 채워집니다.
파일 형식별 포함 또는 제외
인덱서 정의의 "매개 변수" 섹션에서 포함 및 제외 조건을 설정하여 인덱싱되는 파일을 제어합니다.
특정 파일 확장자를 포함하려면 선행 점이 있는 쉼표로 구분된 파일 확장자 목록으로 설정합니다 "indexedFileNameExtensions" . 특정 파일 확장자를 제외하려면 "excludedFileNameExtensions"를 건너뛸 확장자로 설정하세요. 동일한 확장이 두 목록에 모두 표시되면 인덱서는 인덱싱에서 제외합니다.
PUT /indexers/[indexer name]?api-version=2026-10-01
{
"parameters" : {
"configuration" : {
"indexedFileNameExtensions" : ".pdf, .docx",
"excludedFileNameExtensions" : ".png, .jpeg"
}
}
}
인덱싱되는 문서 제어
Microsoft 365 인덱서의 단일 SharePoint 하나 이상의 문서 라이브러리에서 콘텐츠를 인덱싱할 수 있습니다. 인덱싱할 사이트 및 문서 라이브러리를 지정하려면 데이터 원본 정의에서 "컨테이너" 매개 변수를 사용합니다.
데이터 원본 "컨테이너" 섹션에는 이 작업에 대한 두 가지 속성인 "name" 및 "query"가 있습니다.
이름
이 속성은 name 필수이며 다음 값 중 하나여야 합니다.
| 값 | 설명 |
|---|---|
| defaultSiteLibrary | 사이트의 기본 문서 라이브러리에서 모든 콘텐츠를 인덱싱합니다. |
| 모든사이트라이브러리 | 사이트의 모든 문서 라이브러리에서 모든 콘텐츠를 인덱싱합니다.
includeSubsites=true를 쿼리에서 설정하지 않는 한 하위 사이트의 문서 라이브러리는 범위를 벗어납니다.
useQuery을 선택하고 includeLibrariesInSite을 지정하여 특정 사이트 또는 하위 사이트로 범위를 지정할 수도 있습니다. |
| allSiteLists | 사이트의 모든 SharePoint list 항목을 인덱싱합니다. |
| allSitePages | 사이트의 모든 최신 ASPX 사이트 페이지를 인덱싱합니다. |
| allSiteContent | 단일 인덱서의 사이트에서 라이브러리, 목록 및 페이지를 인덱싱합니다. |
| useQuery | 에 정의된 콘텐츠만 인덱싱합니다 query. |
allSiteLists, allSitePages 또는 allSiteContent를 사용하는 데이터 원본의 경우, 인덱서 키 필드 매핑은 metadata_spo_site_asset_item_id 대신 metadata_spo_site_library_item_id를 사용해야 합니다. 자세한 내용은 6단계: 인덱서 만들기를 참조하세요.
쿼리
데이터 원본의 "query" 매개 변수는 키워드/값 쌍으로 구성됩니다. 다음 키워드를 사용합니다. 값은 사이트 URL 또는 문서 라이브러리 URL입니다.
사용 권한을 설정할 때 다음 정보를 고려합니다.
특정 키워드의 값을 얻으려면 포함하거나 제외하려는 문서 라이브러리로 이동하여 브라우저에서 URI를 복사합니다. 이 메서드는 쿼리에서 키워드와 함께 사용할 값을 가져오는 가장 쉬운 방법입니다.
| 키워드 | 값 설명 및 예제 |
|---|---|
| Null | null이거나 비어 있는 경우 컨테이너 이름에 따라 기본 문서 라이브러리 또는 모든 문서 라이브러리를 인덱싱합니다. 예제: "container" : { "name" : "defaultSiteLibrary", "query" : null } |
| 하위 사이트 포함 |
true로 설정하면 인덱서는 해당 순회 제한 내에서 루트 사이트 및 하위 사이트를 트래버스합니다.
allSiteLibraries, allSiteLists, allSitePages 또는 allSiteContent와 결합합니다. 예제: "container" : { "name" : "allSiteLibraries", "query" : "includeSubsites=true" } |
| 사이트에 라이브러리 포함 | 이 키워드 값으로 지정된 사이트 또는 하위 사이트 아래에 있는 모든 라이브러리의 콘텐츠를 인덱싱합니다. 이 사이트는 연결 문자열의 SharePointOnlineEndpoint와 다를 수 있습니다. 키워드를 반복하여 여러 사이트를 선택합니다.
다른 사이트에서 콘텐츠 선택을 참조하세요. 예제 1: "container" : { "name" : "useQuery", "query" : "includeLibrariesInSite=https://mycompany.sharepoint.com/mysite" } 예제 2(몇 개의 하위 사이트만 포함): "container" : { "name" : "useQuery", "query" : "includeLibrariesInSite=https://mycompany.sharepoint.com/sites/TopSite/SubSite1;includeLibrariesInSite=https://mycompany.sharepoint.com/sites/TopSite/SubSite2" } |
| includeLibrary | 이 라이브러리의 모든 콘텐츠를 인덱싱합니다. 값은 브라우저에서 복사할 수 있는 라이브러리에 대한 정규화된 경로입니다. 예제 1(정규화된 경로): "container" : { "name" : "useQuery", "query" : "includeLibrary=https://mycompany.sharepoint.com/mysite/MyDocumentLibrary" } 예제 2(브라우저에서 복사한 URI): "container" : { "name" : "useQuery", "query" : "includeLibrary=https://mycompany.sharepoint.com/teams/mysite/MyDocumentLibrary/Forms/AllItems.aspx" } |
| 라이브러리 제외(excludeLibrary) | 이 라이브러리의 콘텐츠를 인덱싱하지 마세요. 값은 브라우저에서 복사할 수 있는 라이브러리에 대한 정규화된 경로입니다. 예제 1(정규화된 경로): "container" : { "name" : "useQuery", "query" : "includeLibrariesInSite=https://mysite.sharepoint.com/subsite1; excludeLibrary=https://mysite.sharepoint.com/subsite1/MyDocumentLibrary" } 예제 2(브라우저에서 복사한 URI): "container" : { "name" : "useQuery", "query" : "includeLibrariesInSite=https://mycompany.sharepoint.com/teams/mysite; excludeLibrary=https://mycompany.sharepoint.com/teams/mysite/MyDocumentLibrary/Forms/AllItems.aspx" } |
| 폴더포함 | 특정 폴더 및 해당 하위 폴더의 콘텐츠를 인덱싱합니다. 값은 전체 SharePoint 폴더 URL이어야 합니다. 동작: 모든 하위 폴더에 재귀적으로 적용됩니다. 세미콜론으로 매개 변수를 반복하여 여러 폴더를 지정할 수 있습니다. 폴더 필터는 단일 문서 라이브러리로 범위가 지정됩니다. 루트 전용 경로는 지원되지 않습니다. 참조된 폴더의 이름이 바뀐 경우 쿼리를 업데이트해야 합니다. 예제 1(단일 폴더): "container": { "name": "useQuery", "query": "includeFolder=[your-tenant-name].sharepoint.com/sites/hr/Shared Documents/Policies" }예제 2(여러 폴더): "container": { "name": "useQuery", "query": "includeFolder=[your-tenant-name].sharepoint.com/sites/hr/Shared Documents/Specs;includeFolder=[your-tenant-name].sharepoint.com/sites/hr/Shared Documents/Designs" } |
| 폴더 제외 | 특정 폴더 및 해당 하위 폴더의 콘텐츠를 인덱싱하지 마세요. 값은 전체 SharePoint 폴더 URL이어야 합니다. 동작: 모든 하위 폴더에 재귀적으로 적용됩니다. 파일이 포함 규칙과 제외 규칙 모두와 일치하는 경우 제외가 우선적으로 적용되고 파일을 건너뜁습니다. 폴더 필터는 단일 문서 라이브러리로 범위가 지정됩니다. 예제 1(폴더 제외): "container": { "name": "useQuery", "query": "excludeFolder=[your-tenant-name].sharepoint.com/sites/hr/Shared Documents/Policies/Archive" }예제 2(포함과 제외를 결합하기 위해): "container": { "name": "useQuery", "query": "includeFolder=[your-tenant-name].sharepoint.com/sites/hr/Shared Documents/Policies;excludeFolder=[your-tenant-name].sharepoint.com/sites/hr/Shared Documents/Policies/Drafts" } |
| additionalColumns | 문서 라이브러리의 열을 인덱싱합니다. 값은 인덱싱할 열 이름의 쉼표로 구분된 목록입니다. 열 이름에 포함된 세미콜론과 쉼표를 이스케이프 처리하려면 이중 백슬래시를 사용하세요. 예제 1(additionalColumns=MyCustomColumn,MyCustomColumn2): "container" : { "name" : "useQuery", "query" : "includeLibrary=https://mycompany.sharepoint.com/mysite/MyDocumentLibrary;additionalColumns=MyCustomColumn,MyCustomColumn2" } 예제 2(이중 백슬래시를 사용하는 이스케이프 문자): "container" : { "name" : "useQuery", "query" : "includeLibrary=https://mycompany.sharepoint.com/teams/mysite/MyDocumentLibrary/Forms/AllItems.aspx;additionalColumns=MyCustomColumnWith\\,,MyCustomColumnWith\\;" } |
다른 사이트에서 콘텐츠 선택
연결 문자열 SharePointOnlineEndpoint 기본 사이트를 식별합니다. 쿼리를 설정 container.name 하여 useQuery인덱싱할 사이트 또는 라이브러리를 선택합니다. 선택한 사이트는 해당 기본 사이트와 다를 수 있습니다.
다음 구성 예제에서는 동일한 테넌트에서 사이트 A, 사이트 B 및 사이트 C의 세 사이트를 사용합니다. 해당 사이트가 있는 연결 문자열SharePointOnlineEndpointhttps://contoso.sharepoint.com/sites/site-a바꿉 {{sharepoint-site-a-connection-string}} 니다. 선택한 모든 사이트에 대한 수집 애플리케이션의 권한을 구성합니다.
이 데이터 원본은 연결 문자열이 사이트 A를 식별하더라도 사이트 B를 선택합니다.
{
"name": "sharepoint-site-b",
"type": "sharepoint",
"credentials": {
"connectionString": "{{sharepoint-site-a-connection-string}}"
},
"container": {
"name": "useQuery",
"query": "includeLibrariesInSite=https://contoso.sharepoint.com/sites/site-b"
}
}
참조:데이터 원본 - 만들기
사이트 B 및 C를 선택하려면 쿼리에서 includeLibrariesInSite를 반복합니다.
{
"name": "sharepoint-sites-b-c",
"type": "sharepoint",
"credentials": {
"connectionString": "{{sharepoint-site-a-connection-string}}"
},
"container": {
"name": "useQuery",
"query": "includeLibrariesInSite=https://contoso.sharepoint.com/sites/site-b;includeLibrariesInSite=https://contoso.sharepoint.com/sites/site-c"
}
}
참조:데이터 원본 - 만들기
쿼리 선택은 액세스 권한을 부여하지 않습니다.
Sites.Selected를 사용하는 경우 선택한 각 사이트에 대한 액세스 권한을 앱에 부여합니다.
Sites.Selected 사용 시 사이트 액세스 권한 부여를 참조하세요.
데이터 원본 만들기 및 런타임 액세스는 별도의 검사입니다. 설치 유효성 검사에서 연결 문자열 엔드포인트를 검색하는 경우 사이트 A에 성공적으로 액세스해도 사이트 B 또는 C에 대한 액세스가 확인되지 않습니다. 인덱서의 상태 및 실행 기록을 확인하여 선택한 사이트의 처리를 확인합니다.
사용 권한 인식 인덱싱의 경우 SharePoint 권한 구성에 따라 metadata_spo_site_url를 매핑하고 인덱스 및 프로젝션된 문서에서 원래 사이트 컨텍스트를 유지합니다.
sharepointSiteUrl: true 필드 속성은 SharePoint 그룹 조회에 사용되는 사이트 컨텍스트 필드를 식별합니다. 사이트 선택 규칙이나 허용 목록이 아닙니다.
인덱스당 사이트 제한은 계속 적용됩니다.
오류를 처리하십시오.
실패한 연결 식별
Foundry IQ에 대한 성공적인 요청은 인덱서가 SharePoint를 읽을 수 있음을 증명하지 않습니다. 성공적인 수집은 최종 사용자가 보호된 항목을 검색할 수 있음을 증명하지도 않습니다. 사용 권한 또는 네트워크 설정을 변경하기 전에 실패한 단계를 식별합니다.
| Connection | 확인할 ID 또는 자격 증명 | 진단 작업 |
|---|---|---|
| Foundry IQ에 대한 클라이언트 또는 애플리케이션 | 호출자의 Microsoft Entra 신원 또는 구성된 API 키입니다. | 검색 엔드포인트, 해당 데이터 평면 역할 및 검색 서비스 네트워크 액세스를 확인합니다. 호출자 인증은 사용자의 문서 권한과 별개입니다. |
| Microsoft Graph 및 SharePoint용 인덱서 | 구성된 SharePoint 수집 앱 및 필요한 경우 위임된 로그인 | 인덱서 상태 및 실행 기록을 검토합니다. 선택한 각 사이트에 대한 테넌트, 자격 증명, 관리자 동의 및 사이트 부여를 확인합니다. 연결 문자열 엔드포인트만으로는 쿼리에서 선택한 모든 사이트에 대한 액세스가 설정되지 않습니다. |
| Microsoft Graph 및 SharePoint에 대한 쿼리 시점 권한 분석 | 최종 사용자의 권한 컨텍스트 및 구성된 SharePoint 그룹 확인 앱 | SharePoint 권한 필터링 진단을 따르세요. 수집 앱의 액세스 범위를 넓히는 대신 쿼리 토큰, 인덱싱된 권한/사이트 메타데이터 및 그룹 확인 구성을 확인합니다. |
| 모델 또는 Foundry 엔드포인트에 대한 보강 | 키 없는 호출을 위한 검색 관리 ID 또는 구성된 리소스 키입니다. | 실패한 스킬과 해당 리소스 엔드포인트, 권한 부여, 입력 제한 및 네트워크 구성을 검사합니다. |
인바운드 및 아웃바운드 연결을 별도로 확인합니다. 검색을 위한 인바운드 프라이빗 엔드포인트는 SharePoint Online에 대한 퍼블릭 아웃바운드 연결과 공존할 수 있습니다. 공유 프라이빗 링크는 지원되는 대상에만 적용되며 SharePoint Online에는 적용되지 않습니다. 조건부 액세스 제한은 여전히 적용됩니다.
지원을 위해 실패 단계, UTC 타임스탬프, HTTP 상태 및 요청 또는 상관 관계 ID를 캡처합니다. 공유 진단에서 토큰, API 키, 비밀 및 테넌트별 식별 세부 정보를 제거합니다.
인덱싱 실패 처리
Invalid AAD tenant 메시지, 누락된 Microsoft Entra 테넌트 ID 또는 인덱서 실행 기록에 나타나는 테넌트 불일치는 일반적인 인덱서 오류 및 경고 문제 해결을 참조하세요.
다음 섹션의 문서 건너뛰기 설정은 인증 또는 권한 오류를 수정하지 않습니다.
기본적으로 Microsoft 365 인덱서의 SharePoint 이미지와 같이 지원되지 않는 콘텐츠 형식의 문서를 발견하면 즉시 중지됩니다. 매개 변수를 excludedFileNameExtensions 사용하여 특정 콘텐츠 형식을 건너뜁니다. 그러나 가능한 모든 콘텐츠 형식을 미리 알지 못하고 문서를 인덱싱해야 할 수 있습니다. 인덱서가 지원되지 않는 콘텐츠 형식을 발견할 때 인덱싱을 계속하려면 구성 매개 변수를 failOnUnsupportedContentType false로 설정합니다.
PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=2026-10-01
Content-Type: application/json
api-key: [admin key]
{
... other parts of indexer definition
"parameters" : { "configuration" : { "failOnUnsupportedContentType" : false } }
}
일부 문서의 경우 Foundry IQ에서 콘텐츠 형식을 확인할 수 없거나 지원되지 않는 콘텐츠 형식의 문서를 처리할 수 없습니다. 이 실패 모드를 무시하려면 구성 매개 변수를 failOnUnprocessableDocument false로 설정합니다.
"parameters" : { "configuration" : { "failOnUnprocessableDocument" : false } }
SharePoint 원본 파일은 Blob과 유사한 인덱서에 대해 공유 소스 파일 크기 및 추출된 문자 제한을 사용합니다. 기본적으로 대형 문서는 오류로 처리됩니다. 그러나 구성 매개 변수를 true로 설정한 경우에도 대형 문서의 스토리지 메타데이터를 indexStorageMetadataOnlyForOversizedDocuments 인덱싱할 수 있습니다.
"parameters" : { "configuration" : { "indexStorageMetadataOnlyForOversizedDocuments" : true } }
기술 세트를 추가하는 경우 각 기술의 입력 및 다운스트림 서비스 제한을 별도로 확인합니다. 기술은 SharePoint 인덱서 추출보다 적은 데이터를 허용할 수 있습니다.
문서를 구문 분석하는 동안 또는 인덱스에 문서를 추가하는 동안 처리할 때 오류가 발생하는 경우 인덱싱을 계속할 수도 있습니다. 특정 수의 오류를 무시하려면 maxFailedItems 및 maxFailedItemsPerBatch 구성 매개 변수를 원하는 값으로 설정합니다. 예를 들어:
{
... other parts of indexer definition
"parameters" : { "maxFailedItems" : 10, "maxFailedItemsPerBatch" : 10 }
}
동기화 재시도 이해하기
SharePoint 변경 내용을 추적하는 프로세스는 동기화 재시도를 요청할 수 있습니다. 그런 다음 Foundry IQ는 이전에 인덱싱된 항목을 다시 처리하여 누락된 변경 내용을 방지하고 해당 항목을 편집하지 않은 경우에도 데이터 무결성을 유지할 수 있습니다.
이 동작은 ACL 수집 여부에 관계없이 적용됩니다. 파이프라인에 따라 재처리는 보강 및 임베딩 생성을 다시 실행하여 처리 시간과 비용을 늘릴 수 있습니다.
동기화 재시도는 보강 또는 임베딩을 다시 실행하지 않고 인덱싱된 권한을 새로 고치는 권한 재동기화와는 별개입니다. 이후 일반 실행 중에 콘텐츠 재처리가 발생하더라도, 권한 전용 실행이 해당 작업을 수행했다는 의미는 아닙니다.
재시도가 반복되거나 처리가 예기치 않은 경우 인덱서 실행 기록을 검토합니다. 지원에 문의할 때 영향을 받은 실행들의 UTC 시간, 상태, 오류 및 사용 가능한 요청 ID를 제공하세요. 자격 증명, 사용자 토큰 또는 문서 콘텐츠를 포함하지 마세요.