Azure Data Lake Storage Gen2의 데이터 인덱싱

아티클
02/19/2024

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

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

C#의 코드 샘플은 GitHub에서 Microsoft Entra ID를 사용하여 Data Lake Gen2 인덱스 생성을 참조하세요.

필수 조건

계층 구조 네임스페이스가 사용 설정된 ADLS Gen2. ADLS Gen2는 Azure Storage를 통해 사용할 수 있습니다. 스토리지 계정을 설정할 때 계층 구조 네임스페이스를 사용하도록 설정하고 파일을 디렉터리 및 중첩된 하위 디렉터리의 계층 구조로 구성하는 옵션이 있습니다. 계층 구조 네임스페이스를 사용하도록 설정하면 ADLS Gen2가 사용하도록 설정됩니다.
핫, 쿨 및 보관이 포함된 ADLS Gen2의 액세스 계층. 핫 및 쿨만 검색 인덱서에서 액세스할 수 있습니다.
텍스트를 포함하는 Blob. 이진 파일 데이터가 있는 경우 이미지 분석을 위해 AI 보강을 포함할 수 있습니다. Blob 콘텐츠는 검색 서비스 계층의 인덱스기 한도를 초과할 수 없습니다.
Azure Storage에 대한 읽기 권한. "모든 권한" 연결 문자열에는 콘텐츠에 대한 액세스 권한을 부여하는 키가 포함되지만 대신 Azure 역할을 사용하는 경우 검색 서비스 관리 ID에 Storage Blob 데이터 읽기 권한자 권한이 있는지 확인합니다.
이 문서에 표시된 것과 유사한 REST 호출을 작성하려면 REST 클라이언트를 사용합니다.

참고 항목

ADLS Gen2는 BLOB 수준에서 Azure RBAC(Azure 역할 기반 액세스 제어) 및 POSIX와 유사한 ACL(액세스 제어 목록)을 모두 지원하는 액세스 제어 모델을 구현합니다. Azure AI 검색은 문서 수준 권한을 지원하지 않습니다. 모든 사용자는 인덱스에서 검색 및 검색 가능한 모든 콘텐츠에 대해 동일한 수준의 액세스 권한을 가집니다. 문서 수준 권한이 애플리케이션 요구 사항인 경우 잠재적 솔루션으로 보안 조정을 고려합니다.

지원되는 문서 형식

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

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 파일의 행을 구문 분석하여 행당 하나의 검색 문서를 만들 수 있습니다.

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의 문서 형식과 관련된 모든 메타데이터 속성을 인덱스 스키마에 표시할 수도 있습니다. 콘텐츠 관련 메타데이터에 대한 자세한 내용은 콘텐츠 메타데이터 속성을 참조하세요.

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

데이터 원본 정의

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

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

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

"type"을 "adlsgen2"(필수)으로 설정합니다.
"credentials"를 Azure Storage 연결 문자열로 설정합니다. 다음 섹션에서는 지원되는 형식에 대해 설명합니다.
"container"를 Blob 컨테이너로 설정하고 "쿼리"를 사용하여 하위 폴더를 지정합니다.

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

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

인덱서는 다음 연결을 사용하여 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)에 대한 읽기 권한 및 목록이 있어야 합니다.

참고 항목

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

인덱스에 검색 필드 추가

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

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

{
    "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 }     
    ]
}

문서 키 필드("key": true)를 만듭니다. Blob 콘텐츠의 경우 가장 적합한 후보는 메타데이터 속성입니다.
- metadata_storage_path(기본값) 개체 또는 파일의 전체 경로입니다. 키 필드(이 예에서는 "ID")는 기본값이기 때문에 metadata_storage_path의 값으로 채워집니다.
- metadata_storage_name, 이름이 고유한 경우에만 사용할 수 있습니다. 이 필드를 키로 사용하려면 "key": true를 이 필드 정의로 이동합니다.
- Blob에 추가하는 사용자 지정 메타데이터 속성입니다. 이 옵션에는 해당 메타데이터 속성을 모든 BLOB에 추가하는 BLOB 업로드 프로세스가 필요합니다. 키는 필수 속성이므로 값이 누락된 Blob은 인덱싱되지 않습니다. 사용자 지정 메타데이터 속성을 키로 사용하는 경우 해당 속성을 변경하지 마세요. 키 속성이 변경되면 인덱서는 동일한 Blob에 대해 중복 문서를 추가합니다.
메타데이터 속성에는 종종 문서 키에 유효하지 않은 / 및 -와 같은 문자가 포함됩니다. 인덱서에는 "base64EncodeKeys" 속성(기본적으로 true)이 있으므로 구성이나 필드 매핑이 필요하지 않고 메타데이터 속성을 자동으로 인코딩합니다.
Blob 의 “content” 속성을 통해 각 파일에서 추출된 텍스트를 저장하는 “content” 필드를 추가합니다. 이 이름을 반드시 사용해야 하는 것은 아니지만 이렇게 하면 암시적 필드 매핑을 활용할 수 있습니다.
표준 메타데이터 속성에 대한 필드를 추가합니다. 인덱서는 사용자 지정 메타데이터 속성, 표준 메타데이터 속성 및 콘텐츠 관련 메타데이터 속성을 읽을 수 있습니다.

ADLS Gen2 인덱서 구성 및 실행

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

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

{
  "name" : "my-adlsgen2-indexer",
  "dataSourceName" : "my-adlsgen2-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" : [ ]
}

기본값(문서 10개)이 사용 가능한 리소스를 충분히 활용하지 못하거나 초과하는 경우 "batchSize"를 설정합니다. 기본 일괄 처리 크기는 데이터 원본에 따라 다릅니다. Blob 인덱싱은 더 큰 평균 문서 크기를 인식하여 일괄 처리 크기를 10개 문서로 설정합니다.
"구성"에서 파일 형식에 따라 인덱싱되는 Blob을 제어하거나 모든 Blob을 검색하려면 지정하지 않은 상태로 둡니다.

"indexedFileNameExtensions"의 경우 쉼표로 구분된 파일 확장명 목록(선행 점이 있음)을 제공합니다. "excludedFileNameExtensions"에 대해 동일한 작업을 수행하여 건너뛰어야 하는 확장을 나타냅니다. 동일한 확장자가 두 목록에 있으면 인덱싱에서 제외됩니다.
"configuration"에서 "dataToExtract"를 설정하여 인덱싱되는 Blob 부분을 제어합니다.
- "contentAndMetadata"는 Blob에서 추출된 모든 메타데이터 및 텍스트 콘텐츠가 인덱싱되도록 지정합니다. 기본값입니다.
- "storageMetadata"는 표준 blob 속성 및 사용자 지정 메타데이터만 인덱싱되도록 지정합니다.
- "allMetadata"는 표준 Blob 속성 및 찾은 콘텐츠 형식에 대한 메타데이터를 Blob 콘텐츠에서 추출하고 인덱싱하도록 지정합니다.
Blob이 여러 검색 문서에 매핑되어야 하거나 일반 텍스트, JSON 문서 또는 CSV 파일로 구성된 경우 "parsingMode"를 설정합니다.
필드 이름 또는 형식이 다르거나 검색 인덱스에서 여러 버전의 원본 필드가 필요한 경우 필드 매핑을 지정합니다.

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

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

인덱서 상태 확인

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

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

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

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2024-02-21T00:23:24.957Z",
            "endTime":"2024-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2024-02-21T00:23:24.957Z",
                "endTime":"2024-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=2023-11-01
{
  "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 크기에 제한은 서비스 제한을 참조하세요.

제한 사항

Blob 인덱서와 달리 ADLS Gen2 인덱서는 스토리지 계정에서 콘텐츠를 열거하고 인덱싱하기 위해 컨테이너 수준 SAS 토큰을 사용할 수 없습니다. 인덱서가 Filesystem - Get 속성 API를 호출하여 스토리지 계정에 계층 구조 네임스페이스를 사용하도록 설정했는지 확인하기 때문입니다. 계층 구조 네임스페이스를 사용하도록 설정하지 않은 스토리지 계정의 경우 대신 Blob 인덱서를 활용하여 Blob의 열거 성능을 보장하는 것이 좋습니다.
속성 metadata_storage_path가 인덱스 키 필드로 매핑된 경우 디렉터리 이름이 바뀔 때 Blob이 다시 인덱싱되지 않습니다. 이름이 바뀐 디렉터리에 포함된 Blob을 다시 인덱싱하려면 모든 디렉터리에 대한 LastModified 타임스탬프를 업데이트합니다.

다음 단계

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