Microsoft 365 SharePoint 콘텐츠 인덱싱(미리 보기)

Microsoft 365의 SharePoint 인덱서(미리 보기)는 SharePoint 문서 라이브러리에서 문서를 가져와 Azure AI 검색에서 검색할 수 있게 합니다. 구성 단계가 먼저 수행되고 동작 및 시나리오가 뒤따릅니다.

Azure AI 검색 인덱서는 데이터 원본에서 검색 가능한 데이터 및 메타데이터를 추출합니다. Microsoft 365 인덱서의 SharePoint 다음과 같은 기능을 제공합니다.

• 하나 이상의 문서 라이브러리에서 파일 및 메타데이터를 인덱싱합니다.
• SharePoint 목록 및 해당 항목 필드 값을 인덱싱하며, 각 목록 열은 필드 매핑을 위한 소스 필드로 사용할 수 있습니다. 이 기능은 2026-05-01-preview REST API부터 미리 보기로 제공됩니다.
• ASPX 사이트 페이지(최신 사이트 페이지)를 인덱싱합니다. 이 기능은 2026-05-01-preview REST API부터 미리 보기로 제공됩니다.
• allSiteContent 컨테이너 값을 사용하여 단일 인덱서에서 혼합된 SharePoint 콘텐츠(문서 라이브러리, 목록 및 사이트 페이지)를 인덱싱합니다. 이 기능은 2026-05-01-preview REST API부터 미리 보기로 제공됩니다.
• 데이터 원본 쿼리에 설정된 경우 includeSubsites=true 하위 사이트 간에 콘텐츠를 인덱싱합니다. 이 기능은 2026-05-01-preview REST API부터 미리 보기로 제공됩니다.
• 새 파일과 변경된 파일, 목록 항목, 페이지 및 메타데이터만 선택하여 증분 방식으로 인덱싱합니다.
• 삭제된 콘텐츠를 자동으로 검색합니다. 다음 인덱서 실행에서 파일, 목록 항목 또는 페이지 삭제가 선택되고 해당 검색 문서가 인덱스에서 제거됩니다.
• 인덱싱된 문서에서 자동으로 텍스트 및 정규화된 이미지를 추출합니다. 필요에 따라 OCR(광학 문자 인식) 또는 엔터티 인식과 같은 더 심층적인 AI 보강을 위한 기술 세트를 추가할 수 있습니다.
• 미리 보기에서 문서 ACL(기본 액세스 제어 목록) 수집 을 지원합니다. 2026-05-01-preview부터 고유한 권한이 있는 항목에 대해 성공한 각 인덱서 실행에서 ACL 변경 내용이 검색되고 증분 방식으로 업데이트됩니다. 또한 이 릴리스는 ACL 수집을 목록 항목, ASPX 사이트 페이지 및 SharePoint 그룹으로 확장합니다. 주의 사항 및 구성 단계는 SharePoint 인덱서를 사용하여 권한 메타데이터 수집을 참조하세요.
• Microsoft Purview 민감도 레이블을 수집하고 쿼리 시점에 이를 적용하는 기능을 지원합니다. 이 기능은 미리 보기로 제공됩니다.

필수 구성 요소

• 인덱서 미리 보기 등록 양식을 작성합니다. 등록이 자동으로 승인됩니다.

• Azure AI 검색, 기본 가격 책정 등급 이상

• Microsoft 365 클라우드 서비스의 SharePoint(OneDrive는 지원되는 데이터 원본이 아님).

• 문서 라이브러리의 파일입니다.

• Visual Studio Code 인덱서 파이프라인을 설정하고 실행하기 위한 REST 클라이언트 확장.

사용 권한 설정 선택

3단계에서 앱 등록을 만들기 전에 다음 표에서 시나리오를 식별합니다. 필요한 Microsoft Graph 권한, SharePoint API 권한 및 자격 증명 유형을 확인합니다. 그런 다음 이 문서의 뒷부분에 있는 연결된 단계에 따라 적용합니다.

사용 권한을 설정할 때 다음 정보를 고려합니다.

• 위임된 권한은 소규모 테스트에만 사용할 수 있으며 ACL 수집을 지원하지 않습니다.
• 페더레이션 자격 증명은 권장되는 비밀 없는 인증입니다. 인덱서 인증과 쿼리 시 SharePoint 그룹 확인을 모두 다룹니다.
• Sites.Selected 사용하는 경우 인덱싱하기 전에 앱에 각 대상 SharePoint 사이트에 대한 명시적 액세스 권한을 부여합니다. Microsoft Entra ID 관리자 Sites.Selected 동의는 그 자체로 앱이 사이트 콘텐츠에 액세스할 수 있는 권한을 부여하지 않습니다. 또한 각 대상 사이트에 대한 사용 권한을 할당해야 합니다. 명시적 사이트 권한 부여 없이 데이터 원본에 사이트를 추가하면 인덱서가 실패합니다. Sites.Selected 사용 시 사이트 액세스 권한 부여를 참조하세요.

지원되는 문서 형식

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
• Pdf
• 일반 텍스트 파일( 일반 텍스트 인덱싱 참조)
• RTF
• Xml
• ZIP

제한 사항 및 고려 사항

이 기능의 제한 사항은 다음과 같습니다.

• OneNote Notebook 파일은 지원되지 않습니다.

• 증분 인덱싱 제한 사항:

  • SharePoint 폴더의 이름을 바꾸면 증분 인덱싱이 중단됩니다. 이름이 바뀐 폴더는 새 콘텐츠로 처리됩니다.

  • SharePoint 파일 시스템 메타데이터를 업데이트하는 Microsoft 365 프로세스는 콘텐츠에 다른 변경 내용이 없더라도 증분 인덱싱을 트리거할 수 있습니다. 인덱서 또는 AI 보강에 의존하기 전에 설정을 테스트합니다. Microsoft 365 문서를 처리하는 방법을 확인합니다.

• 보안 제한 사항:

  • 프라이빗 엔드포인트에 대한 지원이 없습니다. 방화벽을 통해 보안 네트워크 구성을 사용하도록 설정해야 합니다.

  • Microsoft Entra ID 조건부 액세스 사용하도록 설정된 테넌트에 대한 지원은 없습니다.

  • 사용자 암호화 파일 및 암호로 보호된 ZIP 파일은 지원되지 않습니다. 그러나 암호화된 콘텐츠는 Microsoft Purview 민감도 레이블로 보호되고 해당 레이블(미리 보기) 유지 및 적용하기 위한 구성이 사용되는 경우 허용됩니다.

  • 문서 수준 액세스 권한에 대한 지원이 제한되어 있습니다. ACL 동기화의 기본 수준은 현재 미리 보기로 제공됩니다. 자세한 내용 및 설정은 SharePoint ACL 구성 설명서 참조하세요. 시나리오당 필요한 사용 권한은 사용 권한 설정 선택을 참조하세요.

이 기능을 사용할 때 몇 가지 고려 사항은 다음과 같습니다.

• Azure AI 검색를 사용하여 SharePoint 데이터와 상호 작용하는 사용자 지정 Copilot 또는 RAG(검색 강화 생성) 앱을 빌드하려면 Microsoft는 원격 SharePoint 지식 원본을 사용하는 것을 권장합니다. 이 지식 원본은 Copilot 검색 API를 사용하여 Microsoft 365 SharePoint 텍스트 콘텐츠를 직접 쿼리하고 결과를 병합, 순위 및 응답 공식화에 대한 에이전트 검색 엔진으로 반환합니다. 이 지식 원본에서 사용하는 검색 인덱스는 없으며 텍스트 콘텐츠만 쿼리됩니다. Azure AI 검색 데이터를 복제하지 않습니다. 각 사용자에게 표시할 권한이 있는 결과만 반환하여 SharePoint 권한 모델을 적용합니다.

• 프로덕션 환경에서 SharePoint 데이터와 채팅할 사용자 지정 Copilot/RAG 애플리케이션 또는 AI 에이전트를 만들어야 하는 경우 먼저 Microsoft Copilot Studio 통해 직접 빌드하는 것이 좋습니다. Copilot Studio 요구 사항을 충족하지 않는 경우 다음을 고려합니다.

  • SharePoint 웹후크를 사용하여 사용자 지정 커넥터를 만들고, Microsoft Graph API 호출하여 데이터를 Azure Blob 컨테이너로 내보낸 다음, 증분 인덱싱을 위해 Azure Blob 인덱서 사용합니다.

  • Azure Logic Apps SharePoint 커넥터 및 Azure AI 검색 커넥터 사용하는 고유한 Azure Logic Apps 워크플로 만들기 Azure AI 검색 커넥터는 정식 출시되면 사용할 수 있게 됩니다. Azure 포털 마법사에서 생성된 워크플로를 시작점으로 사용한 다음, Azure Logic Apps 디자이너 사용자 지정하여 필요한 변환 단계를 추가합니다. Azure AI 검색 마법사가 만드는 워크플로는 소비 워크플로입니다. 프로덕션 워크로드의 경우 표준 논리 앱 워크플로 로 전환하여 추가 엔터프라이즈 기능을 사용합니다.

선택한 방법에 관계없이 SharePoint 웹후크를 사용하여 사용자 지정 커넥터를 빌드하든 Azure Logic Apps 워크플로를 만들든 강력한 보안 조치를 구현해야 합니다. 이러한 조치에는 공유 프라이빗 링크 구성, 방화벽 설정, 원본의 사용자 권한 유지 및 쿼리 시 해당 사용 권한 적용이 포함됩니다. 또한 파이프라인을 정기적으로 감사하고 모니터링해야 합니다.

SharePoint ACL을 인덱싱하는 경우 지원되는 그룹 관계를 검토합니다. SharePoint 그룹 내에 중첩된 Microsoft Entra 그룹은 확장되지 않습니다.

Microsoft 365 인덱서에서 SharePoint 구성

Microsoft 365 인덱서에서 SharePoint 설정하려면 미리 보기 REST API를 사용합니다. 이 섹션에서는 단계를 제공합니다.

(선택 사항) 1단계: 시스템 할당 관리 ID 사용

시스템이 할당한 관리 ID를 사용하도록 설정하여 검색 서비스가 프로비전되는 Microsoft Entra 테넌트를 자동으로 검색합니다.

SharePoint 사이트 및 검색 서비스가 동일한 Microsoft Entra 테넌트에 있는 경우 이 단계를 수행합니다. 다른 Microsoft Entra 테넌트에 있는 경우 이 단계를 건너뜁니다. ID는 테넌트 검색에 사용됩니다. 연결 문자열에 Microsoft Entra 테넌트 ID를 포함하려는 경우 이 단계를 건너뛸 수도 있습니다. 시스템 할당 또는 사용자가 할당한 관리 ID를 비밀 없는 인덱싱에 사용하려면 비밀 없는 인증을 사용하여 애플리케이션 권한을 구성합니다.

저장을 선택하면 검색 서비스에 할당된 개체 ID가 표시됩니다.

2단계: 인덱서에 필요한 권한 결정

ACL 및 비 ACL 시나리오를 다루는 의사 결정 매트릭스는 사용 권한 설정 선택을 참조하세요. 위임된 권한을 선택하는 경우 사용자 위임 토큰은 75분마다 만료되며 만료될 때 인덱서 실행(미리 보기) 을 사용하여 수동 인덱싱이 필요합니다. 위임된 권한은 소규모 테스트 작업에만 권장됩니다.

3단계: Microsoft Entra 애플리케이션 등록 만들기

Microsoft 365 인덱서의 SharePoint 인증에 Microsoft Entra 애플리케이션을 사용합니다. 권한 및 자격 증명을 구성하기 전에 애플리케이션 등록을 만듭니다.

1. Azure 포털 로그인합니다.

2. Microsoft Entra ID를 검색하거나 해당 항목으로 이동하세요.

3. 개요 페이지에서 +앱 등록>를 선택합니다.

   1. 앱의 이름을 입력합니다.
   2. 단일 테넌트만 선택 - 테넌트 이름.
   3. URI 지정 단계를 건너뜁니다. 리디렉션 URI가 필요하지 않습니다.
   4. 등록을 선택합니다.

4. 왼쪽 창에서API 권한> 선택합니다.

5. + 사용 권한 추가를 선택한 다음, Microsoft Graph 선택합니다.

   • 인덱서가 애플리케이션 API 권한을 사용하는 경우 애플리케이션 권한을 선택합니다.

     • 표준 인덱싱의 경우 다음을 선택합니다.

       • Files.Read.All
       • Sites.Read.All

       

     • ACL 수집(미리 보기)을 사용하도록 설정하는 경우 필요한 권한은 인덱싱하는 항목 유형(문서 라이브러리 파일, 목록 항목, ASPX 페이지) 및 그룹 유형(Microsoft Entra 및 SharePoint 사이트 그룹)에 따라 달라집니다. 이 단계를 완료하기 전에 ACL별 사용 권한 시나리오를 참조하세요. 교차 시나리오 요약은 사용 권한 설정 선택을 참조하세요.

       애플리케이션 권한을 사용하면 인덱서가 서비스 컨텍스트에서 SharePoint 사이트에 액세스합니다. 따라서 인덱서가 실행되면 테넌트 관리자 승인이 필요한 SharePoint 테넌트에 있는 모든 콘텐츠에 액세스할 수 있습니다. 인증에는 클라이언트 비밀 또는 비밀 없는 구성도 필요합니다. 인증 메커니즘 설정은 이 문서의 뒷부분에서 애플리케이션 API 권한에 대해서만 사용 가능한 인증 방법에 대해 설명합니다.

   • 인덱서가 위임된 API 권한을 사용하는 경우 위임된 권한을 선택한 다음, 다음을 선택합니다.

     • Files.Read.All
     • Sites.Read.All
     • User.Read

     

     위임된 권한을 사용하면 검색 클라이언트가 현재 사용자의 보안 ID 아래 SharePoint 연결할 수 있습니다.

6. 테넌트 이름에 대한 관리자 동의 부여를 선택합니다.

   애플리케이션 API 권한을 사용하는 경우 테넌트 관리자 동의가 필요합니다. 일부 테넌트는 위임된 API 권한에도 테넌트 관리자 동의가 필요한 방식으로 잠겨 있습니다. 두 조건 중 하나가 적용되는 경우 테넌트 관리자는 인덱서를 만들기 전에 이 Microsoft Entra 애플리케이션에 대한 동의를 부여해야 합니다.

   Microsoft Entra 앱 관리자가 권한을 승인하는 스크린샷을 보여줌.

7. 왼쪽 창에서 인증 관리>(미리 보기)를 선택합니다.

8. 리디렉션 URI 구성 탭에서 + 리디렉션 URI 추가를 선택합니다.

   1. 모바일 및 데스크톱 애플리케이션을 선택합니다.
   2. 리디렉션 URI를 https://login.microsoftonline.com/common/oauth2/nativeclient 선택합니다.
   3. 설정을 선택합니다.

9. 설정 탭에서 공용 클라이언트 흐름 허용 토글을 사용하도록 설정한 다음 저장을 선택합니다.

10. 솔루션 요구 사항에 따라 인덱서 인증 방법을 구성합니다.

사이트 액세스 권한 부여(Sites.Selected 사용 시)

앱 등록 Sites.Selected을 구성하는 경우 인덱서 실행 전에 다음 단계를 완료합니다. Microsoft Entra ID 관리자 Sites.Selected 동의는 앱이 범위가 지정된 SharePoint 권한만 사용할 수 있도록 허용합니다. 사이트 권한을 별도로 할당할 때까지 사이트에 대한 액세스 권한을 부여하지 않습니다.

1. Microsoft Entra ID에서: 앱 등록에 Sites.Selected을 추가하고 관리자 동의를 승인합니다. 시나리오에 필요한 권한을 API 영역 아래에 추가하세요. 예를 들어 Microsoft Graph를 추가하고, ACL 수집 시나리오의 경우 SharePoint를 추가하세요.

2. 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를 사용하여 등록된 애플리케이션 구성

1. 시나리오 요구 사항에 따라 사용자가 할당한 관리 ID를 만들고 검색 서비스 또는 시스템 할당 관리 ID에 할당합니다.

2. 개체(보안 주체) ID를 캡처합니다. 데이터 원본을 만들 때 자격 증명 구성의 일부로 이 값을 사용합니다.

3. 왼쪽 메뉴에서 인증서 및 비밀을 선택합니다.

4. 페더레이션된 자격 증명에서 + 자격 증명 추가를 선택합니다.

5. 페더레이션 자격 증명 시나리오에서 관리 ID를 선택합니다.

6. 관리 ID 선택: 1단계에서 만든 관리 ID를 선택합니다.

7. 자격 증명의 이름을 추가하고 저장을 선택합니다.

4단계: 데이터 원본 만들기

이 섹션에서는 최신 미리 보기 REST API 및 REST 클라이언트 또는 나머지 단계에 대한 기본 설정의 지원되는 최신 베타 SDK를 사용합니다.

데이터 원본은 데이터의 변경 내용(새 행, 수정 또는 삭제된 행)을 효율적으로 식별하기 위해 인덱싱할 데이터, 자격 증명 및 정책을 지정합니다. 동일한 검색 서비스의 여러 인덱서는 동일한 데이터 원본을 사용할 수 있습니다.

SharePoint 인덱싱의 경우 데이터 원본에는 다음과 같은 필수 속성이 있어야 합니다.

• 이름은 검색 서비스 내의 데이터 원본의 고유한 이름입니다.
• 형식 은 "sharepoint"여야 합니다. 이 값은 대/소문자를 구분합니다.
• 자격 증명은 애플리케이션이 Microsoft Entra 토큰을 요청하기 위해 허용된 SharePoint 엔드포인트와 인증 방법을 제공합니다. SharePoint 엔드포인트의 예는 https://[your-tenant-name].sharepoint.com/teams/MySharePointSite. SharePoint 사이트의 홈페이지로 이동하고 브라우저에서 URL을 복사하여 엔드포인트를 가져올 수 있습니다. 지원되는 구문에 대해 연결 문자열 형식을 검토하세요.
• 컨테이너 는 인덱싱할 문서 라이브러리를 지정합니다. 속성 은 인덱싱되는 문서를 제어합니다.

데이터 원본을 만들려면 데이터 원본 만들기(미리 보기)를 호출합니다.

다음은 애플리케이션 비밀 또는 시스템 할당 관리 ID를 사용하는 자격 증명에 대한 데이터 원본 정의 샘플입니다.

POST https://[service name].search.windows.net/datasources?api-version=2026-08-01-preview
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: 서비스의 시스템 할당 관리 ID 애플리케이션(클라이언트) ID로 설정합니다 FederatedCredentialApplicationId . 블록을 생략합니다 identity .
• 사용자 할당 관리 ID: 사용자가 할당한 관리 ID 리소스 경로를 블록에 제공합니다 identity . FederatedCredentialApplicationId를 사용자 할당 관리 ID 자체의 애플리케이션(클라이언트) ID로 설정합니다.

POST https://[service name].search.windows.net/datasources?api-version=2026-08-01-preview
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]

다음 표에서는 각 연결 문자열 필드에 대해 설명합니다.

사용 권한을 설정할 때 다음 정보를 고려합니다.

이전 버전과의 호환성을 위해 SharePoint 인덱서는 연결 문자열에서 여전히 FederatedCredentialObjectId(수집 앱의 페더레이션 ID 자격 증명에 대한 개체/보안 주체 ID)를 허용하므로 기존 데이터 원본은 변경 없이 계속 작동합니다. FederatedCredentialApplicationId을 새 데이터 원본 및 업데이트된 데이터 원본에 사용합니다.

TenantId를 가져오려면 SharePoint 사이트를 소유한 테넌트의 Microsoft Entra 관리 센터를 열고 개요에서 테넌트 ID를 복사합니다.

관리 ID object (principal) ID 섹션을 사용하여 등록된 애플리케이션 구성에서 관리 ID를 가져올 수 있습니다.

사용 권한을 설정할 때 다음 정보를 고려합니다.

SharePoint 사이트와 검색 서비스가 동일한 Microsoft Entra 테넌트에 있고 시스템 할당 관리형 ID가 사용하도록 설정된 경우 연결 문자열에 TenantId를 포함할 필요가 없습니다. 서로 다른 Microsoft Entra 테넌트에 있는 경우 TenantId를 포함해야 합니다.

다음 예는 FederatedCredentialApplicationId로 생성된 데이터 원본을 보여 줍니다:

페더레이션된 자격 증명이 있는 시스템 할당 관리 ID:

POST https://[service name].search.windows.net/datasources?api-version=2026-08-01-preview
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(고급):

이 구성을 사용하기 전에 사용자가 할당한 관리 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-08-01-preview
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 }
    ]
}

6단계: 인덱서 만들기

인덱서는 데이터 원본을 대상 검색 인덱스에 연결하고 데이터 새로 고침을 자동화하는 일정을 제공합니다. 데이터 원본 및 인덱스 만들기 후 인덱서 만들기

인덱서 만들기:

1. 인덱서 만들기(미리 보기) 요청을 보냅니다.

   POST https://[service name].search.windows.net/indexers?api-version=2026-08-01-preview
   Content-Type: application/json
   api-key: [admin key]
   
   {
       "name" : "sharepoint-indexer",
       "dataSourceName" : "sharepoint-datasource",
       "targetIndexName" : "sharepoint-index",
       "parameters": {
       "batchSize": null,
       "maxFailedItems": null,
       "base64EncodeKeys": null,
       "maxFailedItemsPerBatch": null,
       "configuration": {
           "indexedFileNameExtensions" : ".pdf, .docx",
           "excludedFileNameExtensions" : ".png, .jpg",
           "dataToExtract": "contentAndMetadata"
         }
       },
       "schedule" : { },
       "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을 매핑하세요.

   애플리케이션 권한을 사용하는 경우 초기 인덱서 실행이 진행 중인 동안 인덱스를 쿼리할 수 있지만 이미 인덱싱된 항목만 결과를 반환합니다. 전체 검사를 위해 실행이 완료될 때까지 기다립니다. 이 단계의 나머지 지침은 위임된 권한에만 적용됩니다.

2. 인덱서를 처음으로 만들면 다음 단계를 완료할 때까지 인덱서 만들기(미리 보기) 요청이 대기합니다. 인덱서 상태 가져오기를 호출하여 링크를 가져와서 새 디바이스 코드를 입력해야 합니다.

   GET https://[service name].search.windows.net/indexers/sharepoint-indexer/status?api-version=2026-08-01-preview
   Content-Type: application/json
   api-key: [admin key]
   

   10분 이내에 인덱서 상태 가져오기 를 호출하지 않으면 코드가 만료되고 데이터 원본을 다시 만들어야 합니다.

3. 인덱서 상태 가져오기 응답에서 디바이스 로그인 코드를 복사합니다. 디바이스 로그인 코드는 "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."
       }
   }
   

4. 오류 메시지에 포함된 코드를 입력합니다.

   

5. Microsoft 365의 SharePoint 인덱서는 로그인한 사용자의 자격으로 SharePoint 콘텐츠에 액세스합니다. 이 단계에서 로그인하는 사용자는 로그인한 사용자입니다. 따라서 인덱싱하려는 문서 라이브러리의 문서에 액세스할 수 없는 사용자 계정으로 로그인하면 인덱서에서 해당 문서에 액세스할 수 없습니다.

   가능하면 새 조직 사용자 계정을 만들고 인덱서에 부여할 정확한 권한을 부여합니다.

6. 요청 중인 사용 권한을 승인합니다.

   

7. 이전에 제공된 모든 권한이 올바르고 10분 내에 있는 경우 인덱서 만들기(미리 보기) 초기 요청이 완료됩니다.

사용 권한을 설정할 때 다음 정보를 고려합니다.

Microsoft Entra 애플리케이션에 관리자 승인이 필요하고 로그인하기 전에 승인되지 않은 경우 다음 화면이 표시될 수 있습니다. 계속하려면 관리자 승인 이 필요합니다.

7단계: 인덱서 상태 확인

인덱서 만들기 후 인덱서 상태 가져오기를 호출합니다.

GET https://[service name].search.windows.net/indexers/sharepoint-indexer/status?api-version=2026-08-01-preview
Content-Type: application/json
api-key: [admin key]

GET https://[service-name].search.windows.net/indexes/[index-name]/docs?search=*&$count=true&api-version=2026-08-01-preview
api-key: [admin-api-key]

데이터 원본 업데이트

데이터 원본 개체를 업데이트하지 않으면 인덱서는 사용자 상호 작용 없이 일정에 따라 실행됩니다.

디바이스 코드가 만료되는 동안 데이터 원본을 변경하면 다시 로그인하여 인덱서가 실행됩니다. 예를 들어 데이터 원본 쿼리를 변경하는 경우 새 디바이스 코드를 사용하여 https://microsoft.com/devicelogin 다시 로그인합니다.

데이터 원본을 업데이트하려면 만료된 디바이스 코드를 가정하여 다음 단계를 수행합니다.

1. 인덱서 실행(미리 보기)을 호출하여 인덱서 실행을 수동으로 시작합니다.

   POST https://[service name].search.windows.net/indexers/sharepoint-indexer/run?api-version=2026-08-01-preview
   Content-Type: application/json
   api-key: [admin key]
   

2. 인덱서 상태를 확인합니다.

   GET https://[service name].search.windows.net/indexers/sharepoint-indexer/status?api-version=2026-08-01-preview
   Content-Type: application/json
   api-key: [admin key]
   

3. https://microsoft.com/devicelogin에 방문하라는 오류가 발생하면 해당 페이지를 열고 새 코드를 복사합니다.

4. 코드를 대화 상자에 붙여넣습니다.

5. 인덱서를 수동으로 다시 실행하고 인덱서 상태를 확인합니다. 이번에는 인덱서 실행이 성공적으로 시작됩니다.

인덱스 문서 메타데이터

문서 메타데이터()"dataToExtract": "contentAndMetadata"를 인덱싱하는 경우 인덱싱에 다음 메타데이터를 사용할 수 있습니다.

Microsoft 365 인덱서의 SharePoint 각 문서 유형과 관련된 메타데이터도 지원합니다. 자세한 내용은 Azure AI 검색 사용되는 Content 메타데이터 속성을 참조하세요.

사용 권한을 설정할 때 다음 정보를 고려합니다.

사용자 지정 메타데이터를 인덱싱하려면 데이터 원본의 쿼리 매개 변수에 "additionalColumns"를 지정합니다.

SharePoint 목록 인덱싱

SharePoint 목록은 2026-05-01-preview REST API부터 미리 보기로 인덱싱할 수 있습니다. 사이트의 모든 목록 항목을 인덱싱하거나 목록 항목을 단일 인덱서의 문서 라이브러리 및 사이트 페이지와 결합하도록 container.name 데이터 원본 allSiteListsallSiteContent 을 설정합니다. 하위 사이트 목록을 포함하려면 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 고려해 보세요.

일치하는 필드를 인덱스 정의에 추가한 다음 각 열을 인덱서의 대상 필드에 매핑합니다.

{
  "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 사이트 페이지 인덱싱

2026-05-01-preview REST API부터 최신 ASPX 사이트 페이지를 미리 보기로 인덱싱할 수 있습니다. 사이트의 모든 페이지를 인덱싱하려면 데이터 원본 container.name을(를) allSitePages(으)로 설정하고, 페이지를 문서 라이브러리 및 목록과 단일 인덱서에서 결합하려면 allSiteContent(으)로 설정합니다. 하위 사이트 페이지를 포함하려면 includeSubsites=true에 container.query를 추가합니다.

페이지 기반 또는 혼합 콘텐츠 인덱서의 경우 인덱스 키 필드는 metadata_spo_site_asset_item_id에서 매핑되어야 합니다. 페이지 텍스트는 content 필드로 추출되고, 각 페이지에 대해 표준 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-08-01-preview
{
    "parameters" : { 
        "configuration" : { 
            "indexedFileNameExtensions" : ".pdf, .docx",
            "excludedFileNameExtensions" : ".png, .jpeg" 
        } 
    }
}

인덱싱되는 문서 제어

Microsoft 365 인덱서의 단일 SharePoint 하나 이상의 문서 라이브러리에서 콘텐츠를 인덱싱할 수 있습니다. 인덱싱할 사이트 및 문서 라이브러리를 지정하려면 데이터 원본 정의에서 "컨테이너" 매개 변수를 사용합니다.

데이터 원본 "컨테이너" 섹션에는 이 작업에 대한 두 가지 속성인 "name" 및 "query"가 있습니다.

이름

이 속성은 name 필수이며 다음 값 중 하나여야 합니다.

allSiteLists, allSitePages 또는 allSiteContent를 사용하는 데이터 원본의 경우, 인덱서 키 필드 매핑은 metadata_spo_site_asset_item_id 대신 metadata_spo_site_library_item_id를 사용해야 합니다. 자세한 내용은 6단계: 인덱서 만들기를 참조하세요.

쿼리

데이터 원본의 "query" 매개 변수는 키워드/값 쌍으로 구성됩니다. 다음 키워드를 사용합니다. 값은 사이트 URL 또는 문서 라이브러리 URL입니다.

사용 권한을 설정할 때 다음 정보를 고려합니다.

특정 키워드의 값을 얻으려면 포함하거나 제외하려는 문서 라이브러리로 이동하여 브라우저에서 URI를 복사합니다. 이 메서드는 쿼리에서 키워드와 함께 사용할 값을 가져오는 가장 쉬운 방법입니다.

오류를 처리하십시오.

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-08-01-preview
Content-Type: application/json
api-key: [admin key]

{
    ... other parts of indexer definition
    "parameters" : { "configuration" : { "failOnUnsupportedContentType" : false } }
}

일부 문서의 경우 Azure AI 검색 콘텐츠 형식을 확인할 수 없거나 지원되지 않는 콘텐츠 형식의 문서를 처리할 수 없습니다. 이 실패 모드를 무시하려면 구성 매개 변수를 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 }
}

관련 콘텐츠

• YouTube 동영상: Microsoft 365 인덱서의 SharePoint
• Azure AI 검색의 인덱서
• Azure AI 검색에 사용되는 콘텐츠 메타데이터 속성
• Azure Logic App 커넥터를 사용하여 SharePoint 콘텐츠 및 기타 원본을 Azure AI 검색에 색인화하기
• SharePoint ACL 구성 수집 (미리 보기)
• SharePoint 인덱스와 인덱스 간에 ACL을 동기화합니다
• SharePoint 그룹 지원 구성
• Microsoft Purview의 민감도 레이블을 보존하고 존중하십시오 (미리 보기)