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

아티클
03/07/2024

Important

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

시작하기 전에 알려진 제한 사항 섹션을 확인하십시오.

이 미리 보기를 사용하려면 이 양식을 작성합니다. 액세스 요청은 제출 후 자동으로 수락되므로 승인 알림이 바로 전송되지 않습니다. 액세스를 사용하도록 설정한 후 콘텐츠를 인덱싱하려면 미리 보기 REST API(2023-10-01-Preview 이상)를 사용합니다.

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

기능

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

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

필수 조건

Microsoft 365의 SharePoint 클라우드 서비스
문서 라이브러리의 파일

지원되는 문서 형식

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

CSV(CSV Blob 인덱싱 참조)
EML
EPUB
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 목록 인덱싱은 지원되지 않습니다.
SharePoint .ASPX 사이트 콘텐츠 인덱싱은 지원되지 않습니다.
OneNote Notebook 파일은 지원되지 않습니다.
프라이빗 엔드포인트는 지원되지 않습니다.
SharePoint 폴더의 이름을 바꾸면 증분 인덱싱이 트리거되지 않습니다. 이름이 변경된 폴더는 새로운 콘텐츠로 처리됩니다.
SharePoint는 문서 수준에서 사용자별 액세스를 결정하는 세분화된 권한 부여 모델을 지원합니다. 인덱서는 이러한 권한을 인덱스에 가져오지 않으며 Azure AI 검색은 문서 수준 권한 부여를 지원하지 않습니다. 문서가 SharePoint에서 검색 서비스로 인덱싱되는 경우 인덱스에 대한 읽기 액세스 권한이 있는 사용자는 누구든지 해당 콘텐츠를 사용할 수 있습니다. 문서 수준 권한이 필요한 경우 보안 필터를 사용하여 결과를 트리밍하고 파일 수준의 사용 권한을 인덱스의 필드로 복사하는 작업을 자동화해야 합니다.
사용자 암호화된 파일, IRM(정보 권한 관리) 보호된 파일, 암호가 있는 ZIP 파일 또는 이와 유사한 암호화된 콘텐츠의 인덱싱은 지원되지 않습니다. 암호화된 콘텐츠를 처리하기 위해서는 인덱서가 예약된 다음 반복을 실행할 때 항목이 적절하게 인덱싱될 수 있도록 특정 파일에 대한 적절한 권한이 있는 사용자가 암호화를 제거해야 합니다.

이 기능을 사용할 때 고려해야 할 사항은 다음과 같습니다.

프로덕션 환경에서 SharePoint 콘텐츠 인덱싱 솔루션이 필요한 경우 SharePoint 웹후크를 사용하여 사용자 지정 커넥터를 만들고, Microsoft Graph API를 호출하여 데이터를 Azure Blob 컨테이너로 내보낸 다음, 증분 인덱싱에 Azure Blob 인덱서를 사용하는 것이 좋습니다.

SharePoint 구성을 통해 Microsoft 365 프로세스가 SharePoint 파일 시스템 메타데이터를 업데이트할 수 있는 경우, 이러한 업데이트로 인해 SharePoint Online 인덱서가 트리거되어 인덱서가 문서를 여러 번 수집할 수 있습니다. SharePoint Online 인덱서는 Azure에 대한 타사 커넥터이므로 인덱서는 구성을 읽거나 동작을 변경할 수 없습니다. 업데이트 방법에 관계없이 새 콘텐츠와 변경된 콘텐츠의 변경 내용에 응답합니다. 따라서 인덱서와 AI 보강을 사용하기 전에 설정을 테스트하고 문서 처리 횟수를 파악해야 합니다.

SharePoint Online 인덱서 구성

SharePoint Online 인덱서를 설정하려면 Azure Portal과 미리 보기 REST API를 모두 사용합니다.

이 섹션에서는 해당 단계를 제공합니다. 또한 다음 비디오를 시청할 수도 있습니다.

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

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

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

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

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

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

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

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

Microsoft Entra 조직에 조건부 액세스가 사용하도록 설정되어 있고 관리자가 디바이스에 위임된 권한을 부여할 수 없는 경우 앱 기반 권한을 대신 고려해야 합니다. 자세한 내용은 Microsoft Entra 조건부 액세스 정책을 참조하세요.

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

SharePoint Online 인덱서는 인증을 위해 이 Microsoft Entra 애플리케이션을 사용합니다.

Azure Portal에 로그인합니다.
Microsoft Entra ID를 검색하거나 여기로 이동한 다음, 앱 등록을 선택합니다.
+ 새 등록을 선택합니다.
1. 앱의 이름을 입력합니다.
2. 단일 테넌트를 선택합니다.
3. URI 지정 단계를 건너뜁니다. 리디렉션 URI는 필요하지 않습니다.
4. 등록을 선택합니다.
왼쪽에서 API 권한, 권한 추가, Microsoft Graph를 차례로 선택합니다.
- 인덱서가 애플리케이션 API 권한을 사용하는 경우 애플리케이션 권한을 선택하고 다음을 추가합니다.
  - 애플리케이션 - Files.Read.All
  - 애플리케이션 - Sites.Read.All
  애플리케이션 권한을 사용하면 인덱서가 서비스 컨텍스트에서 SharePoint 사이트에 액세스하게 됩니다. 따라서 인덱서가 실행되면 SharePoint 테넌트에서 모든 콘텐츠에 액세스할 수 있으므로 테넌트 관리자의 승인이 필요합니다. 인증을 위해 클라이언트 암호도 필요합니다. 클라이언트 암호를 설정하는 방법은 이 문서의 뒷부분에 설명되어 있습니다.
- 인덱서가 위임된 API 권한을 사용하는 경우 위임된 권한을 선택하고 다음을 추가합니다.
  - 위임됨 - Files.Read.All
  - 위임됨 - Sites.Read.All
  - 위임됨 - User.Read
  위임된 권한을 사용하면 검색 클라이언트가 현재 사용자의 보안 ID로 SharePoint에 연결할 수 있습니다.
관리자 동의를 제공합니다.

애플리케이션 API 권한을 사용하는 경우 테넌트 관리자 동의가 필요합니다. 일부 테넌트는 잠겨 있으므로 위임된 API 권한에 테넌트 관리자 동의도 필요합니다. 이러한 조건 중 하나에 해당하는 경우 인덱서를 만들기 전에 테넌트 관리자가 이 Microsoft Entra 애플리케이션에 대한 동의를 허용해야 합니다.
인증 탭을 선택합니다.
퍼블릭 클라이언트 흐름 허용을 예로 설정한 후 저장을 선택합니다.
+ 플랫폼 추가, 모바일 및 데스크톱 애플리케이션을 차례로 선택하고 https://login.microsoftonline.com/common/oauth2/nativeclient 및 구성을 차례로 선택합니다.
(애플리케이션 API 권한만 해당) 애플리케이션 권한을 사용하여 Microsoft Entra 애플리케이션에 인증하려면 인덱서에 클라이언트 암호가 필요합니다.
- 왼쪽 메뉴에서 인증서 및 암호를 선택한 다음, 클라이언트 암호, 새 클라이언트 암호를 차례로 선택합니다.
- 팝업 메뉴에서 새 클라이언트 암호에 대한 설명을 입력합니다. 필요한 경우 만료 날짜를 조정합니다. 암호가 만료되면 다시 만들어야 하며 인덱서를 새 암호로 업데이트해야 합니다.
- 새 클라이언트 암호가 암호 목록에 표시됩니다. 페이지에서 나가면 암호가 더 이상 표시되지 않으므로 복사 단추를 사용하여 복사하고 안전한 위치에 저장합니다.

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

Important

이 섹션부터는 나머지 단계 동안 미리 보기 REST API를 사용합니다. 2023-10-01-preview 최신 미리 보기 API를 사용하는 것이 좋습니다. Azure AI 검색 REST 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=2023-10-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=2023-10-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 }
    ]
}

Important

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

6단계: 인덱서 만들기

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

이 단계를 진행하는 동안 SharePoint 사이트에 대한 액세스 권한이 있는 조직 자격 증명을 사용하여 로그인해야 합니다. 가능하면 새 조직 사용자 계정을 만들고 해당 새 사용자에게 인덱서에 필요한 정확한 사용 권한을 부여하는 것이 좋습니다.

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

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

POST https://[service name].search.windows.net/indexers?api-version=2023-10-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" 
          } 
         }
    ]
}

인덱서를 처음으로 만들면 인덱서 만들기(미리 보기) 요청이 다음 단계를 완료할 때까지 대기합니다. 인덱서 상태 가져오기를 호출하여 링크를 가져오고 새 디바이스 코드를 입력해야 합니다.
```
GET https://[service name].search.windows.net/indexers/sharepoint-indexer/status?api-version=2023-10-01-Preview
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."
    }
}

오류 메시지에 포함된 코드를 제공합니다.
SharePoint Online 인덱서는 로그인한 사용자로 SharePoint 콘텐츠에 액세스합니다. 이 단계 중에 로그인하는 사용자는 로그인한 사용자가 됩니다. 따라서 인덱싱할 문서 라이브러리의 문서에 대한 액세스 권한이 없는 사용자 계정으로 로그인하는 경우 인덱서에도 해당 문서에 대한 액세스 권한이 없습니다.

가능하면 새 사용자 계정을 만들고 해당 사용자에게 인덱서에 필요한 정확한 사용 권한을 부여하는 것이 좋습니다.
요청된 사용 권한을 승인합니다.
위에 제공된 모든 권한이 올바르고 10분 내에 있으면 인덱서 만들기(미리 보기) 초기 요청이 완료됩니다.

참고 항목

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

7단계: 인덱서 상태 확인

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

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

데이터 원본 업데이트

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

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

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

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

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

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

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

https://microsoft.com/devicelogin에 방문하라는 오류가 발생하면 해당 페이지를 열고 새 코드를 복사합니다.
코드를 대화 상자에 붙여넣습니다.
인덱서를 수동으로 다시 시작하고 인덱서 상태를 확인합니다. 이번에는 인덱서 실행이 성공적으로 시작되어야 합니다.

문서 메타데이터 인덱싱

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

식별자	Type	설명
metadata_spo_site_library_item_id	Edm.String	사이트의 문서 라이브러리에서 항목을 고유하게 식별하는 사이트 ID, 라이브러리 ID 및 항목 ID의 조합 키입니다.
metadata_spo_site_id	Edm.String	SharePoint 사이트의 ID입니다.
metadata_spo_library_id	Edm.String	문서 라이브러리의 ID입니다.
metadata_spo_item_id	Edm.String	문서에 있는 (문서) 항목의 ID입니다.
metadata_spo_item_last_modified	Edm.DateTimeOffset	항목의 마지막으로 수정한 날짜/시간(UTC)입니다.
metadata_spo_item_name	Edm.String	항목의 이름입니다.
metadata_spo_item_size	Edm.Int64	항목의 크기(바이트)입니다.
metadata_spo_item_content_type	Edm.String	항목의 콘텐츠 유형입니다.
metadata_spo_item_extension	Edm.String	항목의 확장입니다.
metadata_spo_item_weburi	Edm.String	항목의 URI입니다.
metadata_spo_item_path	Edm.String	부모 경로와 항목 이름의 조합입니다.

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

참고 항목

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

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

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

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

PUT /indexers/[indexer name]?api-version=2020-06-30
{
    "parameters" : { 
        "configuration" : { 
            "indexedFileNameExtensions" : ".pdf, .docx",
            "excludedFileNameExtensions" : ".png, .jpeg" 
        } 
    }
}

인덱싱되는 문서 제어

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

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

이름

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

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

쿼리

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

참고 항목

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

키워드	값 설명 및 예제
null	null이거나 비어 있는 경우 컨테이너 이름에 따라 기본 문서 라이브러리 또는 모든 문서 라이브러리를 인덱싱합니다. 예: `"container" : { "name" : "defaultSiteLibrary", "query" : null }`
includeLibrariesInSite	연결 문자열에서 지정된 사이트에 있는 모든 라이브러리의 콘텐츠를 인덱싱합니다. 범위에는 사이트의 하위 사이트가 포함됩니다. 값은 사이트 또는 하위 사이트의 URI여야 합니다. 예: `"container" : { "name" : "useQuery", "query" : "includeLibrariesInSite=https://mycompany.sharepoint.com/mysite" }`
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" }`
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\\;" }`

오류 처리

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

PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=2023-10-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 끝에서 실패하는 항목을 식별할 수 있습니다. 그런 다음, 사용자는 항목에서 암호화를 제거하여 문제를 해결할 수 있습니다.

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

기능

필수 조건

지원되는 문서 형식

제한 사항 및 고려 사항

SharePoint Online 인덱서 구성

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

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

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

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

연결 문자열 형식

5단계: 인덱스 만들기

6단계: 인덱서 만들기

7단계: 인덱서 상태 확인

데이터 원본 업데이트

문서 메타데이터 인덱싱

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

인덱싱되는 문서 제어

이름

쿼리

오류 처리

참고 항목

추가 리소스