Azure Files에서 데이터 인덱싱

아티클
12/13/2023

Important

Azure Files Indexer는 현재 추가 사용 약관에 따라 공개 미리 보기로 제공됩니다. 미리 보기 REST API(2020-06-30-preview 이상)를 사용하여 인덱서 데이터 원본을 만듭니다.

이 문서에서는 Azure Files에서 콘텐츠를 가져오고 Azure AI 검색에서 검색할 수 있도록 만드는 인덱서를 구성하는 방법에 대해 알아봅니다. 인덱서에 대한 입력은 단일 공유의 파일입니다. 출력은 개별 필드에 저장된 검색 가능한 콘텐츠 및 메타데이터가 포함된 검색 인덱스입니다.

이 문서는 Azure Storage의 인덱싱 파일과 관련된 정보로 인덱서 만들기를 보완합니다. REST API를 사용하여 모든 인덱서에 공통적인 세 부분으로 구성된 워크플로(데이터 원본 만들기, 인덱스 만들기, 인덱서 만들기)를 보여 줍니다. 데이터 추출은 인덱서 만들기 요청을 제출할 때 발생합니다.

필수 조건

Azure Files 트랜잭션 최적화 계층입니다.
원본 콘텐츠를 제공하는 SMB 파일 공유입니다. NFS 공유는 지원되지 않습니다.
텍스트가 포함된 파일입니다. 이진 파일 데이터가 있는 경우 이미지 분석을 위해 AI 보강을 포함할 수 있습니다.
Azure Storage에 대한 읽기 권한. "모든 액세스" 연결 문자열에는 콘텐츠에 대한 액세스 권한을 부여하는 키가 포함됩니다.
이 문서에 표시된 것과 유사한 REST 호출을 작성하려면 REST 클라이언트를 사용합니다.

지원되는 문서 형식

Azure Files 인덱서는 다음과 같은 문서 형식에서 텍스트를 추출할 수 있습니다.

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

Azure Files를 인덱싱하는 방법

기본적으로 대부분의 파일은 단일 텍스트 청크로 인덱싱되는 JSON 또는 CSV와 같이 구조화된 콘텐츠가 있는 파일을 포함하여 인덱스에서 단일 검색 문서로 인덱싱됩니다.

복합 또는 포함된 문서(예: ZIP 보관 파일, 첨부 파일이 있는 Outlook 메일이 포함된 Word 문서 또는 첨부 파일이 포함된 .MSG 파일)도 단일 문서로 인덱싱됩니다. 예를 들어 .MSG 첨부 파일에서 추출한 모든 이미지는 normalized_images 필드에 반환됩니다. 이미지가 있는 경우 AI 보강을 추가하여 해당 콘텐츠에서 더 많은 검색 유틸리티를 가져올 수 있습니다.

문서의 텍스트 콘텐츠는 “content”라는 문자열 필드로 추출됩니다. 표준 및 사용자 정의 메타데이터를 추출할 수도 있습니다.

데이터 원본 정의

데이터 원본 정의는 인덱싱할 데이터, 자격 증명 및 데이터 변경 내용을 식별하기 위한 정책을 지정합니다. 데이터 원본은 여러 인덱서에서 사용할 수 있도록 독립적인 리소스로 정의됩니다.

“type”에 대해 미리 보기 API 버전 2020-06-30-Preview 이상을 사용하여 해당 정의를 설정하도록 데이터 원본을 만들거나 업데이트합니다. "azurefile"

{
    "name" : "my-file-datasource",
    "type" : "azurefile",
    "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
    "container" : { "name" : "my-file-share", "query" : "<optional-directory-name>" }
}

"type"을 "azurefile"(필수)으로 설정합니다.
“credentials”를 Azure Storage 연결 문자열로 설정합니다. 다음 섹션에서는 지원되는 형식에 대해 설명합니다.
“container”를 루트 파일 공유로 설정하고 “query”를 사용하여 하위 폴더를 지정합니다.

원본 문서가 삭제 플래그가 지정되었을 때 인덱서가 검색 문서를 삭제하도록 하려면 데이터 원본 정의에 일시 삭제 정책도 포함될 수 있습니다.

지원되는 자격 증명 및 연결 문자열

인덱서는 다음 연결을 사용하여 파일 공유에 연결할 수 있습니다.

전체 액세스 스토리지 계정 연결 문자열
`{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }`
왼쪽 탐색 창에서 액세스 키를 선택하여 Azure Portal의 스토리지 계정 페이지에서 연결 문자열을 가져올 수 있습니다. 키 외에도 전체 연결 문자열을 선택해야 합니다.

인덱스에 검색 필드 추가

검색 인덱스에서 Azure 파일의 콘텐츠 및 메타데이터를 허용하는 필드를 추가합니다.

인덱스를 만들거나 업데이트하여 파일 콘텐츠와 메타데이터를 저장할 검색 필드를 정의합니다.

POST /indexes?api-version=2020-06-30
{
  "name" : "my-search-index",
  "fields": [
      { "name": "ID", "type": "Edm.String", "key": true, "searchable": false },
      { "name": "content", "type": "Edm.String", "searchable": true, "filterable": false },
      { "name": "metadata_storage_name", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true  },
      { "name": "metadata_storage_path", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true },
      { "name": "metadata_storage_size", "type": "Edm.Int64", "searchable": false, "filterable": true, "sortable": true  },
      { "name": "metadata_storage_content_type", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true }        
  ]
}

문서 키 필드("key": true)를 만듭니다. Blob 콘텐츠의 경우 가장 적합한 후보는 메타데이터 속성입니다. 메타데이터 속성에는 종종 문서 키에 유효하지 않은 / 및 -와 같은 문자가 포함됩니다. 인덱서에는 "base64EncodeKeys" 속성(기본적으로 true)이 있으므로 구성이나 필드 매핑이 필요하지 않고 메타데이터 속성을 자동으로 인코딩합니다.
- metadata_storage_path(기본값) 개체 또는 파일의 전체 경로입니다.
- metadata_storage_name, 이름이 고유한 경우에만 사용할 수 있습니다.
- Blob에 추가하는 사용자 지정 메타데이터 속성입니다. 이 옵션에는 해당 메타데이터 속성을 모든 BLOB에 추가하는 BLOB 업로드 프로세스가 필요합니다. 키는 필수 속성이므로 값이 누락된 Blob은 인덱싱되지 않습니다. 사용자 지정 메타데이터 속성을 키로 사용하는 경우 해당 속성을 변경하지 마세요. 키 속성이 변경되면 인덱서는 동일한 Blob에 대해 중복 문서를 추가합니다.
Blob 의 “content” 속성을 통해 각 파일에서 추출된 텍스트를 저장하는 “content” 필드를 추가합니다. 이 이름을 반드시 사용해야 하는 것은 아니지만 이렇게 하면 암시적 필드 매핑을 활용할 수 있습니다.
표준 메타데이터 속성에 대한 필드를 추가합니다. 파일 인덱싱에서 표준 메타데이터 속성은 Blob 메타데이터 속성과 동일합니다. Azure Files 인덱서는 하이픈을 넣은 속성 이름을 밑줄 속성 이름으로 변환하는 이러한 속성에 대한 내부 필드 매핑을 자동으로 만듭니다. 인덱스 정의를 사용하려는 필드도 추가해야 하지만 데이터 원본에서 필드 매핑을 만드는 과정을 생략해도 됩니다.
- metadata_storage_name(Edm.String) - 파일 이름입니다. 예를 들어 /my-share/my-folder/subfolder/resume.pdf 파일을 포함하는 경우 이 필드의 값은 resume.pdf입니다.
- metadata_storage_path(Edm.String) - 스토리지 계정을 포함하는 파일의 전체 URI입니다. 예를 들어 https://myaccount.file.core.windows.net/my-share/my-folder/subfolder/resume.pdf
- metadata_storage_content_type(Edm.String) - 파일을 업로드하기 위해 사용한 코드에 지정된 콘텐츠 형식입니다. 예: application/octet-stream.
- metadata_storage_last_modified(Edm.DateTimeOffset) - 파일에 대해 마지막으로 수정된 타임스탬프입니다. Azure AI 검색은 이 타임스탬프로 변경된 파일을 식별하여 초기 인덱싱 후 모든 항목을 다시 인덱싱하는 것을 방지합니다.
- metadata_storage_size(Edm.Int64) - 파일 크기(바이트)입니다.
- metadata_storage_content_md5(Edm.String) - 파일 콘텐츠의 MD5 해시(사용 가능한 경우)입니다.
- metadata_storage_sas_token(Edm.String) - 사용자 지정 기술이 파일에 액세스하는 데 사용할 수 있는 임시 SAS 토큰입니다. 이 토큰은 만료될 수 있으므로 나중에 사용하기 위해 저장하면 안 됩니다.

Azure Files 인덱서 구성 및 실행

인덱스와 데이터 원본이 만들어지면 인덱서를 만들 준비가 된 것입니다. 인덱서 구성은 런타임 동작을 제어하는 입력, 매개 변수 및 속성을 지정합니다.

이름을 지정하고 데이터 원본 및 대상 인덱스를 참조하여 인덱서를 만들거나 업데이트합니다.

POST https://[service name].search.windows.net/indexers?api-version=2020-06-30
{
  "name" : "my-file-indexer",
  "dataSourceName" : "my-file-datasource",
  "targetIndexName" : "my-search-index",
  "parameters": {
     "batchSize": null,
     "maxFailedItems": null,
     "maxFailedItemsPerBatch": null,
     "base64EncodeKeys": null,
     "configuration": {
        "indexedFileNameExtensions" : ".pdf,.docx",
        "excludedFileNameExtensions" : ".png,.jpeg" 
    }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

선택적 “구성” 섹션에서 포함 또는 제외 조건을 제공합니다. 지정되지 않은 상태로 두면 파일 공유의 모든 파일이 검색됩니다.

indexedFileNameExtensions 및 excludedFileNameExtensions 매개 변수가 모두 있는 경우 Azure AI 검색은 먼저 indexedFileNameExtensions를 확인한 후 excludedFileNameExtensions를 찾습니다. 동일한 파일 확장명이 두 목록 모두에 있는 경우 인덱싱에서 제외됩니다.
필드 이름 또는 형식이 다르거나 검색 인덱스에서 여러 버전의 원본 필드가 필요한 경우 필드 매핑을 지정합니다.

파일 인덱싱에서는 인덱서가 “content” 및 메타데이터 속성을 인덱스의 유사한 이름 및 형식 필드에 매핑하는 기능을 기본 제공하므로 필드 매핑을 종종 생략할 수 있습니다. 메타데이터 속성의 경우 인덱서는 검색 인덱스에서 하이픈 -을 밑줄로 자동으로 바꿉니다.
다른 속성에 대한 자세한 내용은 인덱서 만들기를 참조하세요.

인덱서가 만들어지면 자동으로 실행됩니다. 이는 "disabled"를 true로 설정하여 방지할 수 있습니다. 인덱서 실행을 제어하려면 요청 시 인덱서를 실행하거나 일정에 배치합니다.

인덱서 상태 확인

인덱서 상태 및 실행 기록을 모니터링하려면 인덱서 상태 가져오기 요청을 보냅니다.

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2020-06-30
  Content-Type: application/json  
  api-key: [admin key]

응답에는 상태 및 처리된 항목 수가 포함됩니다. 다음 예와 유사해야 합니다.

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2022-02-21T00:23:24.957Z",
            "endTime":"2022-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2022-02-21T00:23:24.957Z",
                "endTime":"2022-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

실행 기록에는 최대 50개의 가장 최근에 완료된 실행이 포함되며, 가장 최근의 실행이 먼저 나오도록 시간 역순으로 정렬됩니다.

다음 단계

이제 인덱서를 실행하거나, 상태를 모니터링하거나, 인덱서 실행을 예약할 수 있습니다. 다음 문서는 Azure Storage에서 콘텐츠를 가져오는 인덱서에 적용됩니다.