SharePoint 문서 라이브러리의 데이터 인덱싱

중요합니다

SharePoint Online 인덱서 지원은 공개 미리 보기 상태입니다. 추가 사용 약관에 따라 "있는 그대로" 제공되며 최선의 노력으로만 지원됩니다. 미리 보기 기능은 프로덕션 워크로드에 권장되지 않으며 일반 공급이 보장되지 않습니다.

시작하기 전에 알려진 제한 사항 섹션을 참조하세요.

미리 보기에 등록하려면 이 양식을 작성합니다. 모든 요청은 자동으로 승인됩니다. 양식을 작성한 후 미리 보기 REST API 를 사용하여 콘텐츠를 인덱싱합니다.

이 문서에서는 Azure AI 검색에서 전체 텍스트 검색을 위해 SharePoint 문서 라이브러리에 저장된 문서를 인덱싱하도록 검색 인덱서를 구성하는 방법을 설명합니다. 구성 단계가 먼저 수행되고 동작 및 시나리오가 뒤따릅니다.

Azure AI Search에서 인덱서는 데이터 원본에서 검색 가능한 데이터 및 메타데이터를 추출합니다. SharePoint Online 인덱서는 SharePoint 사이트에 연결한 후 하나 이상의 문서 라이브러리에 있는 문서를 인덱싱합니다. 인덱서는 다음과 같은 기능을 제공합니다.

• 하나 이상의 문서 라이브러리에서 파일 및 메타데이터를 인덱싱합니다.
• 새 파일과 변경된 파일 및 메타데이터만 선택하여 증분 방식으로 인덱싱합니다.
• 삭제된 콘텐츠를 자동으로 검색합니다. 라이브러리의 문서 삭제는 다음 인덱서 실행에서 선택되고 해당 검색 문서는 인덱스에서 제거됩니다.
• 인덱싱된 문서에서 자동으로 텍스트 및 정규화된 이미지를 추출합니다. 필요에 따라 OCR 또는 텍스트 번역과 같은 심층적인 AI 보강을 위한 기술 세트를 추가할 수 있습니다.

필수 조건

• Azure AI Search, 기본 가격 책정 계층 이상.

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

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

지원되는 문서 형식

SharePoint Online 인덱서는 다음 문서 형식에서 텍스트를 추출할 수 있습니다.

• CSV(CSV Blob 인덱싱 참조)
• EML
• 에퍽
• GZ
• HTML
• JSON(JSON BLOB 인덱싱 참조)
• KML(지리적 표현을 위한 XML)
• 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

제한 사항 및 고려 사항

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

• 인덱서는 문서 라이브러리에서 지원되는 문서 형식의 콘텐츠를 인덱싱할 수 있습니다. SharePoint 목록, ASPX 사이트 콘텐츠, 또는 OneNote 전자 필기장 파일에 대한 인덱서 지원은 없습니다. 또한 특정 사이트에서 재귀적으로 하위 사이트를 인덱싱하는 것은 지원되지 않습니다.

• 증분 인덱싱 제한 사항:

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

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

• 보안 제한 사항:

  • 프라이빗 엔드포인트에 대한 지원이 없습니다.

  • Microsoft Entra ID 조건부 액세스를 위해 구성된 문서 라이브러리 또는 콘텐츠에 대한 지원이 없습니다.

  • 사용자 암호화 파일, IRM(정보 권한 관리) 보호된 파일, 암호가 있는 ZIP 파일 또는 이와 유사한 암호화된 콘텐츠는 지원되지 않습니다.

  • 문서 수준에서 사용자별 액세스를 결정하는 SharePoint의 세분화된 권한 부여 모델에 대한 지원은 없습니다. 인덱서는 이러한 권한을 인덱스로 끌어오지 않습니다. 인덱스 읽기 권한이 있는 모든 사용자가 콘텐츠를 사용할 수 있습니다. 문서 수준 권한이 필요한 경우 보안 필터를 사용하여 결과를 트리밍 하고 파일 수준의 사용 권한을 인덱스의 필드로 복사하는 작업을 자동화하는 것이 좋습니다.

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

• SharePoint 데이터와 채팅하기 위해 사용자 지정 코필로트 또는 RAG(검색 증강 세대) 애플리케이션을 만들어야 하는 경우 이 미리 보기 기능 대신 Microsoft Copilot Studio 를 사용하는 것이 좋습니다.

• Microsoft Copilot Studio를 사용하는 권장 사항에도 불구하고 프로덕션 환경에서 Azure AI Search를 사용하는 사용자 지정 SharePoint Online 콘텐츠 인덱싱 솔루션이 여전히 필요한 경우 다음을 고려하세요.

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

  • 일반 공급에 도달하면 Azure Logic Apps SharePoint 커넥터 및 Azure AI Search 커넥터를 사용하여 고유한 Azure Logic Apps 워크플로를 만듭니다. Azure Portal 마법사에서 생성된 워크플로를 시작 지점으로 사용한 다음, 필요한 변환 단계를 포함하도록 Azure Logic Apps 디자이너에서 사용자 지정할 수 있습니다. Azure AI Search 마법사를 사용하여 SharePoint Online 데이터를 인덱싱할 때 만든 Azure Logic App 워크플로는 소비 워크플로입니다. 프로덕션 워크로드를 설정하는 경우 표준 논리 앱 워크플로 로 전환하고 추가 엔터프라이즈 기능을 활용해야 합니다.

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

SharePoint Online 인덱서 구성

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

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

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

SharePoint 사이트가 검색 서비스와 동일한 테넌트에 있는 경우 이 단계를 수행합니다. SharePoint 사이트가 다른 테넌트에 있는 경우에는 이 단계를 건너뜁니다. ID는 인덱싱에 사용되지 않으며 테넌트 감지에만 사용됩니다. 테넌트 ID를 연결 문자열에 입력하려는 경우 이 단계를 건너뛸 수도 있습니다.

저장을 선택하면 검색 서비스에 할당된 개체 ID를 가져옵니다.

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

SharePoint Online 인덱서는 위임된 권한과 애플리케이션 권한을 모두 지원합니다. 시나리오에 따라 사용할 권한을 선택합니다.

앱 기반 사용 권한이 권장됩니다. 위임된 권한과 관련된 알려진 문제는 제한 사항을 참조하세요.

• 애플리케이션 권한(권장) - 인덱서가 모든 사이트 및 파일에 액세스할 수 있는 SharePoint 테넌트 ID로 실행됩니다. 인덱서에는 클라이언트 암호가 필요합니다. 또한 인덱서가 콘텐츠를 인덱싱하려면 테넌트 관리자 승인이 필요합니다.

• 위임된 권한 - 인덱서가 요청을 보내는 사용자 또는 앱의 ID로 실행됩니다. 데이터 액세스는 호출자가 액세스할 수 있는 사이트 및 파일로 제한됩니다. 위임된 권한을 지원하려면 인덱서에 사용자를 대신하여 로그인하라는 디바이스 코드 프롬프트가 필요합니다. 사용자 위임 권한은 이 인증 유형을 구현하는 데 사용되는 가장 최근의 보안 라이브러리에 따라 75분마다 토큰 만료를 적용합니다. 이는 조정할 수 있는 동작이 아닙니다. 만료된 토큰에는 인덱서 실행(미리 보기)을 사용한 수동 인덱싱이 필요합니다. 이러한 이유로 앱 기반 권한을 대신 사용해야 합니다.

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

SharePoint Online 인덱서는 인증에 Microsoft Entra 애플리케이션을 사용합니다. Azure AI Search와 동일한 테넌트에 애플리케이션 등록을 만듭니다.

1. Azure Portal에 로그인합니다.

2. Microsoft Entra ID를 검색하거나 탐색한 다음앱 등록추가>를 선택합니다.

3. + 새 등록을 선택합니다.

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

4. 관리 아래의 탐색 창에서 API 사용 권한을 선택한 다음, 사용 권한을 추가한 다음, Microsoft Graph를 선택합니다.

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

     • 애플리케이션 - Files.Read.All
     • 애플리케이션 - Sites.Read.All

     

     애플리케이션 권한을 사용하면 인덱서가 서비스 컨텍스트에서 SharePoint 사이트에 액세스하게 됩니다. 따라서 인덱서가 실행되면 SharePoint 테넌트에서 모든 콘텐츠에 액세스할 수 있으므로 테넌트 관리자의 승인이 필요합니다. 인증을 위해 클라이언트 암호도 필요합니다. 클라이언트 암호를 설정하는 방법은 이 문서의 뒷부분에 설명되어 있습니다.

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

     • 위임됨 - Files.Read.All
     • 위임됨 - Sites.Read.All
     • 위임됨 - User.Read

     

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

5. 관리자 동의를 제공합니다.

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

   

6. 인증 탭을 선택합니다.

7. 퍼블릭 클라이언트 흐름 허용을 예로 설정한 후 저장을 선택합니다.

8. + 플랫폼 추가, 모바일 및 데스크톱 애플리케이션을 차례로 선택하고 https://login.microsoftonline.com/common/oauth2/nativeclient 및 구성을 차례로 선택합니다.

   

9. (애플리케이션 API 권한만 해당) 애플리케이션 권한을 사용하여 Microsoft Entra 애플리케이션에 인증하려면 인덱서에 클라이언트 암호가 필요합니다.

   • 왼쪽 메뉴에서 인증서 및 암호를 선택한 다음, 클라이언트 암호, 새 클라이언트 암호를 차례로 선택합니다.

     

   • 팝업 메뉴에서 새 클라이언트 암호에 대한 설명을 입력합니다. 필요한 경우 만료 날짜를 조정합니다. 암호가 만료되면 다시 만들어야 하며 인덱서를 새 암호로 업데이트해야 합니다.

     

   • 새 클라이언트 암호가 암호 목록에 표시됩니다. 페이지에서 나가면 암호가 더 이상 표시되지 않으므로 복사 단추를 사용하여 복사하고 안전한 위치에 저장합니다.

     

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

이 섹션에서 시작하여 나머지 단계에 대해 미리 보기 REST API를 사용합니다. 최신 미리 보기 API를 사용하는 것이 좋습니다.

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

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

• name은 검색 서비스 내 데이터 원본의 고유 이름입니다.
• type은 "sharepoint"여야 합니다. 이 값은 대/소문자를 구분합니다.
• credentials는 SharePoint 엔드포인트와 Microsoft Entra 애플리케이션(클라이언트) ID를 제공합니다. SharePoint 엔드포인트의 예는 https://microsoft.sharepoint.com/teams/MySharePointSite입니다. SharePoint 사이트의 홈페이지로 이동하고 브라우저에서 URL을 복사하여 엔드포인트를 가져올 수 있습니다.
• container는 인덱싱할 문서 라이브러리를 지정합니다. 속성은 인덱싱되는 문서를 제어합니다.

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

POST https://[service name].search.windows.net/datasources?api-version=2025-05-01-preview
Content-Type: application/json
api-key: [admin key]

{
    "name" : "sharepoint-datasource",
    "type" : "sharepoint",
    "credentials" : { "connectionString" : "[connection-string]" },
    "container" : { "name" : "defaultSiteLibrary", "query" : null }
}

연결 문자열 형식

연결 문자열의 형식은 인덱서가 위임된 API 권한 또는 애플리케이션 API 권한 중 무엇을 사용하는지에 따라 변경됩니다.

• 위임된 API 권한 연결 문자열 형식

  SharePointOnlineEndpoint=[SharePoint site url];ApplicationId=[Azure AD App ID];TenantId=[SharePoint site tenant id]

• 애플리케이션 API 권한 연결 문자열 형식

  SharePointOnlineEndpoint=[SharePoint site url];ApplicationId=[Azure AD App ID];ApplicationSecret=[Azure AD App client secret];TenantId=[SharePoint site tenant id]

참고 항목

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

5단계: 인덱스 만들기

인덱스는 문서의 필드, 특성 및 검색 경험을 형성하는 기타 항목을 지정합니다.

인덱스를 만들려면 인덱스 만들기(미리 보기)를 호출합니다.

POST https://[service name].search.windows.net/indexes?api-version=2025-05-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 }
    ]
}

중요합니다

SharePoint Online 인덱서로 채워진 인덱스의 키 필드로는 metadata_spo_site_library_item_id만 사용할 수 있습니다. 데이터 원본에 키 필드가 없는 경우 키 필드에 metadata_spo_site_library_item_id가 자동으로 매핑됩니다.

6단계: 인덱서 만들기

인덱서는 데이터 원본을 대상 검색 인덱스와 연결하고 데이터 새로 고침을 자동화하는 일정을 제공합니다. 인덱스와 데이터 원본이 만들어지면 인덱서를 만들 수 있습니다.

위임된 권한을 사용하는 경우 이 단계에서 SharePoint 사이트에 액세스할 수 있는 조직 자격 증명으로 로그인하라는 메시지가 표시됩니다. 가능하면 새 조직 사용자 계정을 만들고 해당 새 사용자에게 인덱서에 필요한 정확한 사용 권한을 부여하는 것이 좋습니다.

인덱스를 만들려면 다음과 같은 몇 가지 단계를 수행해야 합니다.

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

   POST https://[service name].search.windows.net/indexers?api-version=2025-05-01-preview
   Content-Type: application/json
   api-key: [admin key]
   
   {
       "name" : "sharepoint-indexer",
       "dataSourceName" : "sharepoint-datasource",
       "targetIndexName" : "sharepoint-index",
       "parameters": {
       "batchSize": null,
       "maxFailedItems": null,
       "maxFailedItemsPerBatch": null,
       "base64EncodeKeys": null,
       "configuration": {
           "indexedFileNameExtensions" : ".pdf, .docx",
           "excludedFileNameExtensions" : ".png, .jpg",
           "dataToExtract": "contentAndMetadata"
         }
       },
       "schedule" : { },
       "fieldMappings" : [
           { 
             "sourceFieldName" : "metadata_spo_site_library_item_id", 
             "targetFieldName" : "id", 
             "mappingFunction" : { 
               "name" : "base64Encode" 
             } 
            }
       ]
   }
   

   애플리케이션 권한을 사용하는 경우 인덱스 쿼리를 시작하기 전에 초기 실행이 완료될 때까지 기다려야 합니다. 이 단계에서 제공하는 다음 지침은 위임된 권한과 관련이 있으며 애플리케이션 권한에는 적용되지 않습니다.

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

   GET https://[service name].search.windows.net/indexers/sharepoint-indexer/status?api-version=2025-05-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. SharePoint Online 인덱서는 로그인한 사용자로 SharePoint 콘텐츠에 액세스합니다. 이 단계 중에 로그인하는 사용자는 로그인한 사용자가 됩니다. 따라서 인덱싱할 문서 라이브러리의 문서에 대한 액세스 권한이 없는 사용자 계정으로 로그인하는 경우 인덱서에도 해당 문서에 대한 액세스 권한이 없습니다.

   가능하면 새 사용자 계정을 만들고 해당 사용자에게 인덱서에 필요한 정확한 사용 권한을 부여하는 것이 좋습니다.

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

   

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

참고 항목

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

7단계: 인덱서 상태 확인

인덱서가 만들어지면 인덱서 상태 가져오기를 호출할 수 있습니다.

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

데이터 원본 업데이트

데이터 원본 개체에 대한 업데이트가 없는 경우 인덱서는 사용자 상호 작용 없이 일정대로 실행됩니다.

그러나 디바이스 코드가 만료된 상태에서 데이터 원본 개체를 수정하는 경우 인덱서를 실행하려면 다시 로그인해야 합니다. 예를 들어, 데이터 원본 쿼리를 변경하는 경우 https://microsoft.com/devicelogin을 사용하여 다시 로그인하고 새로운 디바이스 코드를 가져옵니다.

만료된 디바이스 코드를 가정하여 데이터 원본을 업데이트하는 단계는 다음과 같습니다.

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

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

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

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

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

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

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

문서 메타데이터 인덱싱

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

식별자	유형	설명
metadata_spo_사이트_라이브러리_아이템_id	Edm.String	사이트의 문서 라이브러리에서 항목을 고유하게 식별하는 사이트 ID, 라이브러리 ID 및 항목 ID의 조합 키입니다.
메타데이터_spo_사이트_아이디	Edm.String	SharePoint 사이트의 ID입니다.
metadata_spo_library_id	Edm.String	문서 라이브러리의 ID입니다.
metadata_spo_item_id (메타데이터 SPO 항목 ID)	Edm.String	문서에 있는 (문서) 항목의 ID입니다.
메타데이터_spo_항목_최종_수정	Edm.DateTimeOffset	항목의 마지막으로 수정한 날짜/시간(UTC)입니다.
metadata_spo_item_name	Edm.String	항목의 이름입니다.
메타데이터_스포_아이템_크기	Edm.Int64	항목의 크기(바이트)입니다.
메타데이터_spo_항목_콘텐츠_유형	Edm.String	항목의 콘텐츠 유형입니다.
메타데이터_SPO_아이템_확장	에드엠.스트링	항목의 확장입니다.
metadata_spo_item_weburi	Edm.String	항목의 URI입니다.
메타데이터_spo_아이템_경로	Edm.String	부모 경로와 항목 이름의 조합입니다.

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

참고 항목

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

파일 형식별로 Blob 포함 또는 제외

인덱서 정의의 "parameters" 섹션에서 포함 및 제외 조건을 설정하여 인덱싱되는 파일을 제어할 수 있습니다.

"indexedFileNameExtensions"을 쉼표로 구분된 파일 확장자 목록(선행 점이 있음)으로 설정하여 특정 파일 확장자를 포함합니다. "excludedFileNameExtensions"를 건너뛰어야 하는 확장명으로 설정하여 특정 파일 확장명을 제외합니다. 동일한 확장명이 두 목록에 있으면 인덱싱에서 제외됩니다.

PUT /indexers/[indexer name]?api-version=2025-05-01-preview
{
    "parameters" : { 
        "configuration" : { 
            "indexedFileNameExtensions" : ".pdf, .docx",
            "excludedFileNameExtensions" : ".png, .jpeg" 
        } 
    }
}

인덱싱되는 문서 제어

단일 SharePoint Online 인덱서는 하나 이상의 문서 라이브러리에 있는 콘텐츠를 인덱싱할 수 있습니다. 데이터 원본 정의에서 "container" 매개 변수를 사용하여 인덱싱할 사이트 및 문서 라이브러리를 나타냅니다.

데이터 원본 "container" 섹션에는 이 작업의 두 가지 속성인 "name" 및 "query"가 있습니다.

이름

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

값	설명
기본 사이트 라이브러리	사이트 기본 문서 라이브러리의 모든 콘텐츠를 인덱싱합니다.
모든 사이트 라이브러리 (allSiteLibraries)	사이트의 모든 문서 라이브러리에 있는 모든 콘텐츠를 인덱싱합니다. 하위 사이트의 문서 라이브러리가 범위를 벗어났습니다. 하위 사이트의 콘텐츠가 필요한 경우 "useQuery"를 선택하고 "includeLibrariesInSite"를 지정합니다.
useQuery (쿼리 사용하기)	"query"에 정의된 콘텐츠만 인덱싱합니다.

쿼리

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

참고 항목

특정 키워드에 대한 값을 가져오려면 포함/제외하려는 문서 라이브러리로 이동하고 브라우저에서 해당 URI를 복사하는 것이 좋습니다. 이 방법이 쿼리에서 키워드에 사용할 값을 가져오는 가장 쉬운 방법입니다.

키워드	값 설명 및 예제
널	null이거나 비어 있는 경우 컨테이너 이름에 따라 기본 문서 라이브러리 또는 모든 문서 라이브러리를 인덱싱합니다. 예: "container" : { "name" : "defaultSiteLibrary", "query" : null }
사이트에 라이브러리 포함	연결 문자열에서 지정된 사이트에 있는 모든 라이브러리의 콘텐츠를 인덱싱합니다. 값은 사이트 또는 하위 사이트의 URI여야 합니다. 예 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" }
라이브러리 포함	이 라이브러리의 모든 콘텐츠를 인덱싱합니다. 값은 라이브러리에 대한 정규화된 경로이며, 이는 브라우저에서 복사할 수 있습니다. 예제 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" }
라이브러리 제외	이 라이브러리의 콘텐츠를 인덱싱하지 않습니다. 값은 라이브러리에 대한 정규화된 경로이며, 이는 브라우저에서 복사할 수 있습니다. 예제 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" }
추가열	문서 라이브러리에서 열을 인덱싱합니다. 값은 인덱싱할 열 이름의 쉼표로 구분된 목록입니다. 열 이름의 세미콜론과 쉼표를 이스케이프하려면 이중 백슬래시를 사용합니다. 예제 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\\;" }

오류 처리

기본적으로 SharePoint Online 인덱서는 지원되지 않는 콘텐츠 형식(예: 이미지)을 포함하는 문서를 발견하는 즉시 중지됩니다. excludedFileNameExtensions 매개 변수를 사용하여 특정 콘텐츠 형식을 건너뛸 수 있습니다. 그러나 있을 수 있는 모든 콘텐츠 형식을 미리 알지 못하는 상태에서 문서를 인덱싱해야 할 수 있습니다. 지원되지 않는 콘텐츠 형식이 발견될 때 인덱싱을 계속하려면 failOnUnsupportedContentType 구성 매개 변수를 false로 설정합니다.

PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=2025-05-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 } }

Azure AI 검색은 인덱싱되는 문서의 크기를 제한합니다. 이러한 제한 사항은 Azure AI 검색의 서비스 제한 사항에서 설명됩니다. 너무 큰 문서는 기본적으로 오류로 처리됩니다. 그러나 indexStorageMetadataOnlyForOversizedDocuments 구성 매개 변수를 true로 설정한 경우 너무 큰문서의 스토리지 메타데이터를 여전히 인덱싱할 수 있습니다.

"parameters" : { "configuration" : { "indexStorageMetadataOnlyForOversizedDocuments" : true } }

또한 문서를 구문 분석하거나 문서를 인덱스를 추가할 때 임의 처리 지점에서 오류가 발생하는 경우에도 인덱싱을 계속할 수 있습니다. 설정 개수의 오류를 무시하려면 maxFailedItems 및 maxFailedItemsPerBatch 구성 매개 변수를 원하는 값으로 설정합니다. 예시:

{
    ... other parts of indexer definition
    "parameters" : { "maxFailedItems" : 10, "maxFailedItemsPerBatch" : 10 }
}

SharePoint 사이트의 파일에 암호화가 설정된 경우 다음 오류 메시지가 표시될 수 있습니다.

Code: resourceModified Message: The resource has changed since the caller last read it; usually an eTag mismatch Inner error: Code: irmEncryptFailedToFindProtector

오류 메시지에는 <sharepoint site id> :: <drive id> :: <drive item id> 패턴으로 SharePoint 사이트 ID, 드라이브 ID 및 드라이브 항목 ID도 포함됩니다. 이 정보를 사용하면 SharePoint 끝에서 실패하는 항목을 식별할 수 있습니다. 그런 다음, 사용자는 항목에서 암호화를 제거하여 문제를 해결할 수 있습니다.

참고 항목

• YouTube 동영상: SharePoint Online 인덱서
• Azure AI 검색의 인덱서
• Azure AI 검색에서 사용하는 콘텐츠 메타데이터 속성
• Azure Logic App 커넥터를 사용하여 Azure AI Search에서 SharePoint Online 콘텐츠 및 기타 원본 인덱싱