Azure Blob Storage의 데이터 인덱싱

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

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

Blob 인덱서는 AI 보강 및 텍스트 기반 처리 모두에 자주 사용됩니다. 이 문서에서는 전체 텍스트 검색 시나리오를 위해 텍스트 콘텐츠 및 메타데이터만 수집하는 텍스트 기반 인덱싱용 인덱서를 중점적으로 살펴봅니다.

필수 조건

  • Azure Blob Storage, 표준 성능(범용 v2)

  • Blob Storage용 액세스 계층에는 핫, 쿨 및 보관이 포함됩니다. 검색 인덱서는 핫 및 쿨에만 액세스할 수 있습니다.

  • 텍스트 콘텐츠 및 메타데이터를 제공하는 Blob. Blob에 이진 콘텐츠 또는 구조화되지 않은 텍스트가 포함된 경우 이미지 및 자연어 처리를 위한 AI 보강을 추가하는 것이 좋습니다. Blob 콘텐츠는 검색 서비스 계층의 인덱스기 한도를 초과할 수 없습니다.

  • 지원되는 네트워크 구성 및 데이터 액세스. 최소한 Azure Storage에 대한 읽기 권한이 필요합니다. 액세스 키가 포함된 스토리지 연결 문자열은 스토리지 콘텐츠에 대한 읽기 권한을 제공합니다. 대신 Microsoft Entra 로그인 및 역할을 사용하는 경우 검색 서비스의 관리 IDStorage Blob 데이터 읽기 권한자 권한이 있는지 확인합니다.

    기본적으로 검색 및 스토리지는 모두 공용 IP 주소의 요청을 수락합니다. 네트워크 보안이 즉각적인 문제가 아닌 경우 연결 문자열 및 읽기 권한만 사용하여 Blob 데이터를 인덱싱할 수 있습니다. 네트워크 보호를 추가할 준비가 되면 Azure 네트워크 보안 기능으로 보호되는 콘텐츠에 대한 인덱서 액세스에서 데이터 액세스에 대한 참고 자료를 참조하세요.

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

지원되는 문서 형식

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

  • 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

인덱싱할 Blob 결정

인덱싱을 설정하기 전에 원본 데이터를 검토하여 미리 변경해야 하는지 여부를 결정합니다. 인덱서는 한 번에 한 컨테이너의 콘텐츠를 인덱싱할 수 있습니다. 기본적으로 컨테이너의 모든 Blob이 처리됩니다. 보다 선택적 처리를 위한 몇 가지 옵션이 있습니다.

  • Blob을 가상 폴더에 배치합니다. 인덱서 데이터 원본 정의에는 가상 폴더를 사용할 수 있는 "쿼리" 매개 변수가 포함되어 있습니다. 가상 폴더를 지정하면 폴더에 있는 Blob만 인덱싱됩니다.

  • 파일 형식별로 Blob을 포함하거나 제외합니다. 지원되는 문서 형식 목록은 제외할 blob을 결정하는 데 도움이 될 수 있습니다. 예를 들어, 검색 가능한 텍스트를 제공하지 않는 이미지 또는 오디오 파일을 제외할 수 있습니다. 이 기능은 인덱서의 구성 설정을 통해 제어됩니다.

  • 임의의 Blob을 포함하거나 제외합니다. 어떤 이유로든 특정 Blob을 건너뛰려는 경우 다음 메타데이터 속성 및 값을 Blob Storage의 Blob에 추가할 수 있습니다. 인덱서가 이 속성을 발견하면 인덱싱 실행에서 Blob 또는 해당 콘텐츠를 건너뜁니다.

    Property name 속성 값 설명
    "AzureSearch_Skip" "true" BLOB 인덱서가 BLOB을 완전히 건너뛰도록 지시합니다. 메타데이터와 콘텐츠 추출이 모두 시도되지 않습니다. 특정 BLOB이 반복적으로 실패하고 인덱싱 프로세스가 중단되는 경우에 유용합니다.
    "AzureSearch_SkipContent" "true" 콘텐츠를 건너뛰고 메타데이터만 추출합니다. 이는 구성 설정에 설명된 "dataToExtract" : "allMetadata" 설정과 동일하며 특정 Blob으로 범위가 지정되었습니다.

포함 또는 제외 기준을 설정하지 않으면 인덱서는 부적합 Blob을 오류로 보고하고 계속 진행합니다. 충분한 오류가 발생하면 처리가 중지될 수 있습니다. 인덱서 구성 설정에서 오류 허용 범위를 지정할 수 있습니다.

인덱서는 일반적으로 Blob당 하나의 검색 문서를 만들며 여기서 텍스트 콘텐츠 및 메타데이터는 인덱스에서 검색 가능한 필드로 캡처됩니다. Blob이 전체 파일인 경우 잠재적으로 여러 검색 문서로 구문 분석할 수 있습니다. 예를 들어, CSV 파일의 행을 구문 분석하여 행당 하나의 검색 문서를 만들 수 있습니다.

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

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

Blob 메타데이터 인덱싱

Blob 메타데이터도 인덱싱할 수 있으며, 이는 표준 또는 사용자 지정 메타데이터 속성이 필터 및 쿼리에 유용하다고 생각하는 경우에 유용합니다.

사용자 지정 메타데이터 속성은 그대로 추출됩니다. 값을 받으려면 Blob의 메타데이터 키와 이름이 같은 Edm.String 형식의 검색 인덱스에 필드를 정의해야 합니다. 예를 들어, Blob의 메타데이터 키 Sensitivity의 값이 High인 경우 검색 인덱스에 Sensitivity라는 필드를 정의하면 High 값으로 채워집니다.

표준 Blob 메타데이터 속성은 아래에 나열된 것과 같이 유사한 이름과 형식의 필드로 추출할 수 있습니다. Blob 인덱서는 이러한 Blob 메타데이터 속성에 대한 내부 필드 매핑을 자동으로 만들어 하이픈으로 연결된 원래 이름("metadata-storage-name")을 밑줄이 있는 해당 이름("metadata_storage_name")으로 변환합니다.

여전히 밑줄이 있는 필드를 인덱스 정의에 추가해야 하지만 인덱서가 자동으로 연결을 만들기 때문에 필드 매핑을 생략할 수 있습니다.

  • metadata_storage_name(Edm.String) - Blob의 파일 이름입니다. 예를 들어 blob /my-container/my-folder/subfolder/resume.pdf를 포함하는 경우 이 필드의 값은 resume.pdf입니다.

  • metadata_storage_path(Edm.String) - 스토리지 계정을 포함하는 Blob의 전체 URI입니다. 예를 들어 https://myaccount.blob.core.windows.net/my-container/my-folder/subfolder/resume.pdf

  • metadata_storage_content_type(Edm.String) - Blob을 업로드하기 위해 사용한 코드에 지정된 콘텐츠 형식입니다. 예: application/octet-stream.

  • metadata_storage_last_modified(Edm.DateTimeOffset) - Blob에 대해 마지막으로 수정된 타임스탬프입니다. Azure AI Search는 이 타임스탬프로 변경된 Blob을 식별하여 초기 인덱싱 후 모든 항목을 다시 인덱싱하는 것을 방지합니다.

  • metadata_storage_size(Edm.Int64) - Blob 크기(바이트)입니다.

  • metadata_storage_content_md5(Edm.String) - Blob 콘텐츠의 MD5 해시(사용 가능한 경우)입니다.

  • metadata_storage_sas_token(Edm.String) - 사용자 지정 기술이 Blob에 액세스하는 데 사용할 수 있는 임시 SAS 토큰입니다. 이 토큰은 만료될 수 있으므로 나중에 사용하기 위해 저장하면 안 됩니다.

마지막으로 인덱싱 중인 Blob의 문서 형식과 관련된 모든 메타데이터 속성을 인덱스 스키마에 표시할 수도 있습니다. 콘텐츠 관련 메타데이터에 대한 자세한 내용은 콘텐츠 메타데이터 속성을 참조하세요.

검색 인덱스에서 위의 모든 속성에 대한 필드를 정의하지 않아도 되는 경우 애플리케이션에 필요한 속성만 캡처하는 것이 중요합니다.

현재 인덱싱 Blob 인덱스 태그는 이 인덱서에서 지원되지 않습니다.

데이터 원본 정의

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

  1. 데이터 원본을 만들거나 업데이트하여 정의를 설정합니다.

    {
        "name" : "my-blob-datasource",
        "type" : "azureblob",
        "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
        "container" : { "name" : "my-container", "query" : "<optional-virtual-directory-name>" }
    }
    
  2. "type"을 "azureblob"(필수)으로 설정합니다.

  3. “credentials”를 Azure Storage 연결 문자열로 설정합니다. 다음 섹션에서는 지원되는 형식에 대해 설명합니다.

  4. "container"를 Blob 컨테이너로 설정하고 "query"를 사용하여 하위 폴더를 지정합니다.

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

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

인덱서는 다음 연결을 사용하여 Blob 컨테이너에 연결할 수 있습니다.

전체 액세스 스토리지 계정 연결 문자열
{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }
왼쪽 탐색 창에서 액세스 키를 선택하여 Azure Portal의 스토리지 계정 페이지에서 연결 문자열을 가져올 수 있습니다. 키 외에도 전체 연결 문자열을 선택해야 합니다.
관리 ID 연결 문자열
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" }
이 연결 문자열에는 계정 키가 필요하지 않지만 이전에 관리 ID를 사용하여 연결하도록 검색 서비스를 구성해야 합니다.
스토리지 계정 공유 액세스 서명**(SAS) 연결 문자열
{ "connectionString" : "BlobEndpoint=https://<your account>.blob.core.windows.net/;SharedAccessSignature=?sv=2016-05-31&sig=<the signature>&spr=https&se=<the validity end time>&srt=co&ss=b&sp=rl;" }
SAS에 컨테이너 및 개체(이 경우 Blob)에 대한 읽기 권한 및 목록이 있어야 합니다.
컨테이너 공유 액세스 서명
{ "connectionString" : "ContainerSharedAccessUri=https://<your storage account>.blob.core.windows.net/<container name>?sv=2016-05-31&sr=c&sig=<the signature>&se=<the validity end time>&sp=rl;" }
SAS에 컨테이너에 대한 읽기 권한 및 목록이 있어야 합니다. 자세한 내용은 공유 액세스 서명 사용을 참조하세요.

참고 항목

SAS 자격 증명을 사용하는 경우 자격 증명이 만료되는 것을 방지하기 위해 갱신된 서명을 사용하여 데이터 원본 자격 증명을 주기적으로 업데이트해야 합니다. SAS 자격 증명이 만료되면 "연결 문자열에 제공된 사용자 자격 증명이 잘못되었거나 만료되었습니다."와 유사한 오류 메시지와 함께 인덱서가 실패합니다.

인덱스에 검색 필드 추가

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

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

    POST https://[service name].search.windows.net/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_size", "type": "Edm.Int64", "searchable": false, "filterable": true, "sortable": true  },
            { "name": "metadata_storage_content_type", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true },        
        ]
    }
    
  2. 문서 키 필드("key": true)를 만듭니다. Blob 콘텐츠의 경우 가장 적합한 후보는 메타데이터 속성입니다.

    • metadata_storage_path(기본값) 개체 또는 파일의 전체 경로입니다. 키 필드(이 예에서는 "ID")는 기본값이기 때문에 metadata_storage_path의 값으로 채워집니다.

    • metadata_storage_name, 이름이 고유한 경우에만 사용할 수 있습니다. 이 필드를 키로 사용하려면 "key": true를 이 필드 정의로 이동합니다.

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

    메타데이터 속성에는 문서 키에 유효하지 않은 /-와 같은 문자가 포함되는 경우가 많습니다. 인덱서에는 "base64EncodeKeys" 속성(기본적으로 true)이 있으므로 구성이나 필드 매핑이 필요하지 않고 메타데이터 속성을 자동으로 인코딩합니다.

  3. Blob 의 “content” 속성을 통해 각 파일에서 추출된 텍스트를 저장하는 “content” 필드를 추가합니다. 이 이름을 반드시 사용해야 하는 것은 아니지만 이렇게 하면 암시적 필드 매핑을 활용할 수 있습니다.

  4. 표준 메타데이터 속성에 대한 필드를 추가합니다. 인덱서는 사용자 지정 메타데이터 속성, 표준 메타데이터 속성 및 콘텐츠 관련 메타데이터 속성을 읽을 수 있습니다.

Blob 인덱서 구성 및 실행

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

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

    POST https://[service name].search.windows.net/indexers?api-version=2020-06-30
    {
      "name" : "my-blob-indexer",
      "dataSourceName" : "my-blob-datasource",
      "targetIndexName" : "my-search-index",
      "parameters": {
          "batchSize": null,
          "maxFailedItems": null,
          "maxFailedItemsPerBatch": null,
          "base64EncodeKeys": null,
          "configuration": {
              "indexedFileNameExtensions" : ".pdf,.docx",
              "excludedFileNameExtensions" : ".png,.jpeg",
              "dataToExtract": "contentAndMetadata",
              "parsingMode": "default"
          }
      },
      "schedule" : { },
      "fieldMappings" : [ ]
    }
    
  2. 기본값(문서 10개)이 사용 가능한 리소스를 충분히 활용하지 못하거나 초과하는 경우 batchSize를 설정합니다. 기본 일괄 처리 크기는 데이터 원본에 따라 다릅니다. Blob 인덱싱은 더 큰 평균 문서 크기를 인식하여 일괄 처리 크기를 10개 문서로 설정합니다.

  3. "구성"에서 파일 형식에 따라 인덱싱되는 Blob을 제어하거나 모든 Blob을 검색하려면 지정하지 않은 상태로 둡니다.

    "indexedFileNameExtensions"의 경우 쉼표로 구분된 파일 확장명 목록(선행 점이 있음)을 제공합니다. "excludedFileNameExtensions"에 대해 동일한 작업을 수행하여 건너뛰어야 하는 확장을 나타냅니다. 동일한 확장자가 두 목록에 있으면 인덱싱에서 제외됩니다.

  4. "configuration"에서 "dataToExtract"를 설정하여 인덱싱되는 Blob 부분을 제어합니다.

  5. "구성"에서 "parsingMode"를 설정합니다. 기본 구문 분석 모드는 Blob당 하나의 검색 문서입니다. Blob이 일반 텍스트인 경우 일반 텍스트 구문 분석으로 전환하여 성능을 높일 수 있습니다. Blob을 여러 검색 문서에 매핑하는 보다 세분화된 구문 분석이 필요한 경우 다른 모드를 지정합니다. 다음으로 구성된 Blob에 대해 일대다 구문 분석이 지원됩니다.

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

    Blob 인덱싱에서는 인덱서가 "content" 및 메타데이터 속성을 인덱스의 유사한 이름 및 형식 필드에 매핑하는 기능을 기본 제공하므로 필드 매핑을 종종 생략할 수 있습니다. 메타데이터 속성의 경우 인덱서는 검색 인덱스에서 하이픈 -을 밑줄로 자동으로 바꿉니다.

  7. 다른 속성에 대한 자세한 내용은 인덱서 만들기를 참조하세요. 매개 변수 설명의 전체 목록은 REST API의 Blob 구성 매개 변수를 참조하세요.

인덱서가 만들어지면 자동으로 실행됩니다. 이는 "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개의 가장 최근에 완료된 실행이 포함되며, 가장 최근의 실행이 먼저 나오도록 시간 역순으로 정렬됩니다.

오류 처리

인덱싱 중에 일반적으로 발생하는 오류에는 지원되지 않는 콘텐츠 형식, 누락된 콘텐츠 또는 크기가 너무 큰 Blob이 포함됩니다.

기본적으로 Blob 인덱서는 지원되지 않는 콘텐츠 형식(예: 오디오 파일)을 포함하는 Blob을 발견하는 즉시 중지됩니다. "excludedFileNameExtensions" 매개 변수를 사용하여 특정 콘텐츠 형식을 건너뛸 수 있습니다. 그러나 오류가 발생한 경우에도 인덱싱을 진행하고, 나중에 개별 문서를 디버그하려고 할 수 있습니다. 인덱서 오류에 관한 자세한 내용은 인덱서 문제 해결 지침인덱서 오류 및 경고를 참조하세요.

오류가 발생할 때 인덱서의 응답을 제어하는 다섯 가지 인덱서 속성이 있습니다.

PUT /indexers/[indexer name]?api-version=2020-06-30
{
  "parameters" : { 
    "maxFailedItems" : 10, 
    "maxFailedItemsPerBatch" : 10,
    "configuration" : { 
        "failOnUnsupportedContentType" : false, 
        "failOnUnprocessableDocument" : false,
        "indexStorageMetadataOnlyForOversizedDocuments": false
      }
    }
}
매개 변수 유효한 값 설명
"maxFailedItems" -1, null 또는 0, 양의 정수 또한 Blob을 구문 분석하거나 문서를 인덱스를 추가할 때 임의 처리 지점에서 오류가 발생하는 경우에도 인덱싱을 계속 진행합니다. 이러한 속성을 허용 가능한 오류 수로 설정합니다. -1 값을 사용하면 오류가 발생하는 횟수에 관계 없이 처리를 수행할 수 있습니다. 그렇지 않으면 이 값은 양의 정수입니다.
"maxFailedItemsPerBatch" -1, null 또는 0, 양의 정수 위와 동일하지만 일괄 처리 인덱싱에 사용됩니다.
"failOnUnsupportedContentType" true 또는 false 인덱서가 콘텐츠 형식을 결정할 수 없는 경우 작업을 계속할지 또는 실패 처리할지 지정합니다.
"failOnUnprocessableDocument" true 또는 false 인덱서가 지원되는 콘텐츠 형식의 문서를 처리할 수 없는 경우 작업을 계속할지 또는 실패 처리할지 지정합니다.
"indexStorageMetadataOnlyForOversizedDocuments" true 또는 false 너무 큰 Blob은 기본적으로 오류로 처리됩니다. 이 매개 변수를 true로 설정하면 콘텐츠를 인덱싱할 수 없는 경우에도 인덱서가 해당 메타데이터를 인덱싱하려고 시도합니다. Blob 크기에 제한은 서비스 제한을 참조하세요.

참고 항목