Azure Files 데이터 인덱싱(미리 보기)

Azure Files 인덱서(미리 보기)는 파일 공유의 콘텐츠를 Azure AI 검색 인덱스로 가져옵니다. 인덱서에 대한 입력은 단일 공유 폴더의 파일입니다. 출력은 검색 가능한 콘텐츠와 메타데이터가 개별 필드에 저장된 검색 인덱스입니다.

인덱서 구성 및 실행하려면 다음을 사용할 수 있습니다.

• Search Service 미리 보기 REST API, 모든 미리 보기 버전.
• Azure SDK 패키지, 모든 버전.
• Azure 포털에서 데이터 가져오기 마법사.

필수 구성 요소

• Azure Files 트랜잭션 최적화 계층입니다.

• 원본 콘텐츠를 제공하는 SMB 파일 공유 입니다. NFS 공유 는 지원되지 않습니다.

• 텍스트가 포함된 파일입니다. 이진 데이터가 있는 경우 이미지 분석을 위한 AI 보강을 포함할 수 있습니다.

• Azure Files 인덱서에서 처리되는 원본 파일은 Blob과 유사한 인덱서에 대해 공유 소스 파일 크기 및 추출된 문자 제한을 사용합니다.

• Azure Storage에 대한 읽기 권한. "풀 액세스" 연결 문자열에는 콘텐츠에 대한 액세스 권한을 부여하는 키가 포함되어 있습니다.

• REST 클라이언트를 사용하여 이 문서에 표시된 것과 유사한 REST 호출을 작성합니다.

지원되는 작업

이 인덱서는 다음 작업에 사용할 수 있습니다.

• 데이터 인덱싱 및 증분 인덱싱: 인덱서는 테이블에서 파일 및 관련 메타데이터를 인덱싱할 수 있습니다. 기본 제공 변경 검색을 통해 새 파일 및 업데이트된 파일 및 메타데이터를 검색합니다. 일정 또는 요청 시 데이터 새로 고침을 구성할 수 있습니다.
• 삭제 검색: 인덱서는 사용자 지정 메타데이터를 통해 삭제를 검색할 수 있습니다.
• 기술 세트를 통한 적용된 AI:기술 세트 는 인덱서에서 완전히 지원됩니다. 여기에는 데이터 청크 및 포함 단계를 추가하는 통합 벡터화 와 같은 주요 기능이 포함됩니다.
• 구문 분석 모드: JSON 배열 또는 줄을 개별 검색 문서로 구문 분석하려는 경우 인덱서는 JSON 구문 분석 모드 를 지원합니다. Markdown 구문 분석 모드도 지원합니다.
• 다른 기능과의 호환성: 인덱서는 디버그 세션, 증분 보강을 위한 인덱서 캐시 및 지식 저장소와 같은 다른 인덱서 기능과 원활하게 작동하도록 설계되었습니다.

지원되는 문서 형식

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

• 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

Azure Files 인덱싱되는 방법

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

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

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

데이터 원본 정의

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

"type" "azurefile"에 2020-06-30-preview 이후 버전을 사용할 수 있습니다. 최신 미리 보기 API를 사용하는 것이 좋습니다.

1. "type"에 대한 미리 보기 API를 사용하여 해당 정의를 설정하는 "azurefile"다.

   POST /datasources?api-version=2026-08-01-preview
   {
       "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>" }
   }
   

2. "type"을 (필수)로 "azurefile" 설정합니다.

3. "자격 증명"을 "Azure Storage 연결 문자열"으로 설정하십시오. 다음 섹션에서는 지원되는 형식에 대해 설명합니다.

4. "컨테이너"를 루트 파일 공유로 설정하고 "쿼리"를 사용하여 하위 폴더를 지정합니다.

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

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

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

인덱스에 검색 필드 추가

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

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

   POST /indexes?api-version=2026-04-01
   {
     "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 }        
     ]
   }
   

2. 문서 키 필드("키": true)를 만듭니다. Blob 콘텐츠의 경우 가장 적합한 후보는 메타데이터 속성입니다. 메타데이터 속성에는 문서 키에 유효하지 않은 문자(예: / 및 -)가 포함되는 경우가 많습니다. 인덱서는 구성 또는 필드 매핑 없이 키 메타데이터 속성을 자동으로 인코딩합니다.

   • metadata_storage_path (기본값) 개체 또는 파일에 대한 전체 경로

   • metadata_storage_name 이름이 고유한 경우에만 사용할 수 있습니다.

   • Blob에 추가하는 사용자 지정 메타데이터 속성입니다. 이 옵션을 사용하려면 Blob 업로드 프로세스에서 해당 메타데이터 속성을 모든 Blob에 추가해야 합니다. 키가 필수 속성이므로 값이 누락된 Blob은 인덱싱되지 않습니다. 사용자 지정 메타데이터 속성을 키로 사용하는 경우 해당 속성을 변경하지 마세요. 키 속성이 변경되면 인덱서는 동일한 Blob에 대해 중복 문서를 추가합니다.

3. Blob의 "content" 속성을 통해 각 파일에서 추출된 텍스트를 저장할 "콘텐츠" 필드를 추가합니다. 이 이름을 사용할 필요는 없지만 이렇게 하면 암시적 필드 매핑을 활용할 수 있습니다.

4. 표준 메타데이터 속성에 대한 필드를 추가합니다. 파일 인덱싱에서 표준 메타데이터 속성은 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 인덱서 구성 및 실행

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

1. 인덱서에 이름을 지정하고 데이터 원본 및 대상 인덱스 참조를 사용하여 인덱서 만들기 또는 업데이트:

   POST /indexers?api-version=2026-04-01
   {
     "name" : "my-file-indexer",
     "dataSourceName" : "my-file-datasource",
     "targetIndexName" : "my-search-index",
     "parameters": {
        "batchSize": null,
        "maxFailedItems": null,
        "maxFailedItemsPerBatch": null,
        "configuration": {
           "indexedFileNameExtensions" : ".pdf,.docx",
           "excludedFileNameExtensions" : ".png,.jpeg" 
       }
     },
     "schedule" : { },
     "fieldMappings" : [ ]
   }
   

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

   indexedFileNameExtensions 및 excludedFileNameExtensions 매개 변수가 모두 있는 경우 Azure AI 검색 먼저 indexedFileNameExtensions, excludedFileNameExtensions 찾습니다. 동일한 파일 확장명은 두 목록에 모두 있으면 인덱싱에서 제외됩니다.

3. 필드 이름 또는 형식에 차이가 있거나 검색 인덱스에 여러 버전의 원본 필드가 필요한 경우 필드 매핑을 지정합니다.

   파일 인덱싱에서는 인덱서가 "콘텐츠" 및 메타데이터 속성을 인덱스의 비슷한 이름 및 형식화된 필드에 매핑할 수 있도록 기본적으로 지원하므로 필드 매핑을 생략할 수 있습니다. 메타데이터 속성의 경우 인덱서는 하이픈을 검색 인덱스의 - 밑줄로 자동으로 바꿉니다.

4. 다른 속성에 대한 자세한 내용은 인덱서 만들기 를 참조하세요.

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

인덱서 상태 확인

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

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2026-04-01
  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 콘텐츠를 끌어오는 인덱서에 적용됩니다.

• 변경 검색 및 삭제 검색
• 큰 데이터 집합 인덱싱