Azure Blob Storage의 데이터 인덱싱

비고

Foundry IQ (Azure AI 검색)는 관리형 검색을 위한 상위 수준의 지식 원본 및 지식 베이스 API와 함께 직접 인덱싱 및 쿼리 API를 제공합니다. Azure 포털, REST API 또는 Azure SDK 사용하여 이러한 기능을 구성하거나 Microsoft Foundry 포털의 기술 자료에 에이전트를 연결합니다.

Important

이 문서에서 (미리 보기)로 표시된 기능 또는 성능은 공개 미리 보기로 제공되며 Microsoft Azure 미리 보기에 대한 추가 사용 약관의 적용을 받습니다.

Foundry IQ(Azure AI 검색) 관련 미리 보기 약관은 미리 보기 기능을 참조하세요.

Blob 인덱서는 Azure Blob Storage 콘텐츠를 가져와 Foundry IQ에서 검색할 수 있게 합니다. 인덱서는 단일 컨테이너의 Blob을 입력으로 받습니다. 출력은 검색 가능한 콘텐츠 및 메타데이터를 개별 필드에 저장하는 검색 인덱스입니다.

이 문서에서는 Search Service REST API 를 사용하여 인덱서 구성 및 실행 방법을 보여 줍니다. 그러나 다음을 사용할 수도 있습니다.

비고

표준 Blob 컨테이너 RBAC 범위 수집 및 쿼리 권한 필터링은 REST API 2026-10-01에서 일반적으로 사용할 수 있습니다. 이 제공 범위에는 ADLS 파일 또는 디렉터리 ACL이 포함되지 않습니다. 저장된 범위와 쿼리 시간 권한 부여 간의 설정 및 구분은 수집 Blob RBAC 범위를 참조하세요.

필수 조건

  • Azure Blob Storage 표준 성능(범용 v2)입니다.

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

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

    Blob 인덱서 제한은 최대 Blob 크기 및 Foundry IQ가 Blob에서 추출하는 문자 수를 포함합니다. 기술 세트를 사용하는 경우 각 기술의 입력 또는 서비스 제한은 문서 크래킹 후에 별도로 적용됩니다.

  • 지원되는 네트워크 구성 및 데이터 액세스. 최소한 Azure Storage에 대한 읽기 권한이 필요합니다. 액세스 키가 포함된 스토리지 연결 문자열은 스토리지 콘텐츠에 대한 읽기 권한을 제공합니다. 대신 Microsoft Entra 로그인 및 역할을 사용하는 경우 Foundry IQ 서비스의 관리 ID에 스토리지 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을 가상 폴더에 배치합니다. 인덱서 데이터 원본 정의 에는 가상 폴더를 query 사용할 수 있는 매개 변수가 포함됩니다. 가상 폴더를 지정하는 경우 인덱서는 폴더의 해당 Blob만 인덱싱합니다.

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

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

    속성 이름 속성 값 Explanation
    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 인덱스 태그 인덱싱을 지원하지 않습니다.

Important

인덱서는 검색 인덱스에 이미 정의된 메타데이터 필드만 채웁니다. 이 요구 사항은 표준 Blob 메타데이터와 사용자 지정 메타데이터 모두에 적용됩니다. 필드가 정의되지 않은 경우 메타데이터 값은 인덱싱 중에 추출되지만 자동으로 삭제되므로 검색 결과에 표시되지 않습니다. 검색 결과에서 null 메타데이터 필드의 가장 일반적인 소스입니다. 자세한 내용은 검색 결과에서 메타데이터 필드가 null인 경우를 참조하세요.

표준 Blob 메타데이터 속성

표준 Blob 메타데이터의 경우 동일한 밑줄 이름을 사용하여 인덱스 필드를 정의합니다. 단계별 필드 정의 예제는 인덱스에 검색 필드 추가를 참조하세요.

추출할 메타데이터를 dataToExtract 제어하는 설정을 포함하여 인덱서 구성은 Blob 인덱서 구성 및 실행을 참조하세요.

인덱서에서 해당 필드를 정의하는 경우 인덱서는 이러한 표준 메타데이터 속성을 인식하고 매핑할 수 있습니다.

  • 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. 탐색 또는 원본 특성에 대한 검색 결과에 Blob URL을 포함하려면 이 속성을 사용합니다.

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

  • metadata_storage_last_modified (Edm.DateTimeOffset)는 Blob에 대해 마지막으로 수정된 타임스탬프입니다. Foundry IQ는 이 타임스탬프를 사용하여 변경된 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의 메타데이터 키와 정확히 동일한 이름의 필드를 정의합니다. 예를 들어, blob에 값이 Sensitivity인 메타데이터 키 High가 있는 경우 인덱스에서 이름이 Sensitivity이고 형식이 Edm.String인 필드를 정의합니다.

문서 키 또는 권한에 사용하기 전에 사용자 지정 메타데이터를 작성할 수 있는 사용자를 검토합니다. 일치하는 필드 이름은 값의 권위를 부여하는 것이 아니라, 매핑을 형성합니다. 문서 ID 및 사용 권한 출처 보호를 참조하세요.

인덱싱하는 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. Blob 컨테이너에 container을(를) 설정하고, query을(를) 사용하여 하위 폴더를 지정합니다.

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

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

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

전체 액세스 스토리지 계정 연결 문자열
{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }
왼쪽 창에서 액세스 키를 선택하여 Azure Portal의 Storage 계정 페이지에서 연결 문자열을 가져올 수 있습니다. 키 외에도 전체 연결 문자열을 선택해야 합니다.
관리 ID 연결 문자열
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" }
이 연결 문자열은 계정 키가 필요하지 않지만, 이전에 Foundry IQ 서비스가 관리 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(공유 액세스 서명)를 사용하여 Azure Storage 리소스에 대한 제한된 액세스 권한 부여를 참조하세요.

비고

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

인덱스에 검색 필드 추가

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

  1. Blob 콘텐츠 및 메타데이터를 저장하는 검색 필드를 정의하기 위해 인덱스 만들기 또는 업데이트:

    POST https://[service name].search.windows.net/indexes?api-version=2026-10-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_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)를 만듭니다. 의도한 문서 ID를 나타내는 키 원본을 선택하고 누가 해당 값을 제어할 수 있는지 검토합니다.

    • metadata_storage_path 는 기본 Blob 키 원본이며 개체 또는 파일에 대한 전체 경로를 포함합니다. 파서와 매핑을 검토하여 실제로 적용되는 키를 판별하세요. 이 기본값이 소유권을 보장하는 것은 아닙니다.

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

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

    메타데이터 속성에는 문서 키에 유효하지 않은 / 및 -와 같은 문자가 포함되는 경우가 많습니다. 그러나 인덱서는 구성이나 필드 매핑이 필요하지 않고 키 메타데이터 속성을 자동으로 인코딩합니다.

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

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

문서 식별 및 권한 출처 보호

문서 키는 업데이트 또는 병합의 대상이 되는 인덱스 레코드를 식별합니다. 권한 부여 경계가 아닙니다. 원본 콘텐츠를 쓸 수 있는 권한이 있다고 해서 다른 문서의 인덱싱된 ID를 선택하거나 해당 문서에 액세스할 권한이 부여되는 것은 아닙니다.

Blob 속성, 사용자 지정 메타데이터, 구문 분석된 콘텐츠, 필드 매핑 및 보강 출력 매핑은 인덱스에 값을 제공하는 데 기여합니다. 청크 분할 콘텐츠의 경우 인덱스 프로젝션은 각 자식에 기록되는 필드도 제어합니다. metadata_storage_path라는 이름의 필드는 해당 값이 모든 구성에서 권위 있는 값이라는 증거가 아닙니다. 이름이 다른 입력과의 충돌을 방지하거나 이 필드가 항상 최종 키라고 가정하지 마세요.

Base64 인코딩은 키의 표현을 변경합니다. 키의 출처를 인증하지도 않고 다른 작성자가 동일한 ID를 사용하지 못하게 막지도 않습니다. 필드 이름을 예약하거나 키 접두사만 추가하는 것만으로는 문서 소유권이 적용되지 않습니다.

서로 구분된 상태로 유지되어야 하는 레코드에는 안정적이고 적절히 고유한 식별자를 사용합니다. 애플리케이션 비즈니스 식별자가 의도한 원본 레코드를 고유하게 식별하지 않는 경우 인덱스 키와 별도로 유지합니다. 여러 원본이 의도적으로 하나의 논리적 레코드를 업데이트하는 경우 신뢰할 수 있는 작성자 및 권한 정책에 동의합니다. 여러 데이터 원본 인덱싱을 참조하세요.

다음 예제에서는 소유권 적용 설정이 아니라 검토할 구성 선택을 식별합니다.

소스 구성 ID 및 권한 검토
두 컨테이너에는 각각 이름이 policy.pdf인 blob이 포함되어 있습니다. 파일 이름 전용 키는 두 소스 항목을 구분하지 않습니다. 각 컨테이너 내의 파일 이름뿐만 아니라 두 소스 전체에서 최종 매핑된 키를 확인합니다.
독립 Blob의 JSON 레코드에는 동일한 비즈니스 ID가 포함됩니다. 이러한 레코드가 별도의 레코드인지 아니면 의도적인 공유 레코드인지 결정합니다. 구문 분석된 키 및 매핑을 검토한 후 해당 ID가 인덱싱된 레코드를 선택하도록 허용합니다.
신뢰할 수 있는 두 소스는 의도적으로 하나의 레코드에 기여합니다. 각 필드와 최종 권한 정책을 제어하는 작성자를 검토합니다. 사용 권한 컬렉션을 병합하면 권한 부여가 결합되거나 의도한 콘텐츠와의 연결이 유지된다고 가정하지 마세요.

수집 구성 검토

인덱서 배포 또는 해당 매핑 변경 전:

  1. 원본 콘텐츠 및 사용자 지정 메타데이터에 대한 쓰기 액세스를 제한합니다. 데이터 원본, 파서, 매핑, 기술 세트, 프로젝션 및 인덱싱된 문서를 변경할 수 있는 사용자를 별도로 제한합니다.
  2. 각 파서 및 수집 경로에 대한 키 원본을 선택하고 제어합니다. 암시적 매핑과 명시적 매핑 및 보강 출력을 고려합니다. 낮은 신뢰 콘텐츠가 유지 관리 권한이 없는 레코드의 키를 선택하도록 허용하지 마세요.
  3. 모든 기여 원본에서 독립적인 레코드에 대해 키를 서로 구분되도록 유지합니다. 비즈니스 식별자, 변환 및 생성된 자식 키를 고려하십시오. 동일한 논리적 레코드를 유지하도록 권한이 부여된 작성자 간에만 의도적인 병합을 허용합니다.
  4. 권한 있는 정책 원본에서만 권한 부여를 수락합니다. 수집 전과 병합 및 프로젝션을 거치는 동안 의도된 문서 식별자에 바인딩된 부여를 유지합니다. 일반 콘텐츠의 사용 권한과 유사한 값을 신뢰할 수 있는 권한 필드로 복사하지 마세요.
  5. 수집 관리자 및 문서 게시자에 최소 권한을 적용합니다. 인덱스에 업데이트를 제출할 권한이 있는 모든 기록기는 키별로 대상 레코드를 선택할 수 있습니다. 키는 해당 기록기를 자신이 소유한 문서로 제한하지 않습니다.
  6. 적절한 액세스 제어를 사용하여 독립적으로 신뢰할 수 있는 데이터 세트와 작성자를 구분합니다. 공유 서비스 수준 자격 증명 또는 관리자가 그 인덱스들 전반에 걸쳐 쓸 수 있는 경우, 별도의 인덱스만으로는 완전한 경계가 아닙니다.
  7. 동일한 의도된 원본 문서에 대한 콘텐츠, 부모 ID, 원본 컨텍스트 및 사용 권한을 전달하도록 보호된 각 프로젝션을 구성합니다. 동일한 신뢰할 수 있는 수집 프로세스 내에서 권한 업데이트를 유지합니다.

커넥터 파생 Blob RBAC 범위의 경우 지원되는 수집 구성을 사용하고 각 문서와 원본 컨테이너 간의 연결을 검토합니다. 고객 관리 푸시 권한의 경우 권한 있는 게시자는 문서 ID와 권한 값을 모두 담당합니다. 권한 필드 주석이나 성공적인 인덱싱은 일반 콘텐츠 작성자가 액세스 권한을 부여할 권한이 있음을 입증하지 않습니다.

이러한 컨트롤은 수집 디자인의 일부여야 합니다. 인덱싱된 키와 필드 이름은 과거 소유권 또는 값을 제공한 사람에 대한 결정적인 증거를 제공하지 않습니다. 구성 규칙은 권한 있는 작성자가 다른 레코드를 대상으로 하는 것을 방지하지 않습니다.

키 원본 또는 매핑을 변경하면 인덱스 내의 이전 레코드를 유지하면서 새 레코드를 만들 수 있습니다. 재설정, 권한 다시 동기화 또는 API 버전 변경만으로는 신뢰할 수 있는 문서 소유권이 설정되지 않습니다.

Blob 인덱서 구성 및 실행

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

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

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

  3. 아래에서 configuration파일 형식에 따라 인덱싱되는 Blob을 제어하거나 모든 Blob을 검색하기 위해 지정되지 않은 상태로 둡니다.

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

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

  5. 아래에서 configuration을(를) parsingMode으로 설정합니다. 기본 구문 분석 모드는 Blob당 하나의 검색 문서입니다. 문서 수준 권한 수집에서는 default를 유지하세요. 특수 구문 분석 모드는 지원되지 않습니다. 권한 수집에 대한 지원되는 구문 분석 및 콘텐츠 추출을 참조하세요.

    권한 수집이 없으면 일반 텍스트 Blob은 성능 향상을 위해 일반 텍스트 구문 분석을 사용할 수 있습니다. Blob을 여러 검색 문서에 매핑하는 보다 세부적인 구문 분석의 경우 다른 모드를 지정합니다. 다음으로 구성된 Blob에 대해 일대다 구문 분석이 지원됩니다.

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

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

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

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

여러 Azure Blob 컨테이너에서 단일 인덱스로 데이터 인덱싱

인덱서는 단일 컨테이너의 데이터만 인덱싱할 수 있습니다. 여러 컨테이너의 데이터를 인덱싱하고 단일 Foundry IQ 인덱스로 통합해야 하는 경우 모두 동일한 인덱스를 가리키는 여러 인덱서를 구성합니다. SKU당 사용할 수 있는 최대 인덱서 수에 유의하세요.

예를 들어, my-blob-datasource1 및 my-blob-datasource2이라는 서로 다른 두 개의 데이터 원본에서 데이터를 끌어오기 위해 두 개의 인덱서를 사용할 수 있습니다. 각 데이터 원본은 별도의 Azure Blob 컨테이너를 가리키지만 둘 다 my-search-index라는 동일한 인덱스를 가리킵니다.

첫 번째 인덱서 정의 예:

POST https://[service name].search.windows.net/indexers?api-version=2026-10-01
{
  "name" : "my-blob-indexer1",
  "dataSourceName" : "my-blob-datasource1",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

병렬로 실행되는 두 번째 인덱서 정의 예:

POST https://[service name].search.windows.net/indexers?api-version=2026-10-01
{
  "name" : "my-blob-indexer2",
  "dataSourceName" : "my-blob-datasource2",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

인덱서 상태 확인

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

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2026-10-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개까지 포함됩니다. 항목은 역순으로 정렬되므로 최신 실행이 먼저 발생합니다.

Troubleshooting

이 섹션을 사용하여 누락된 메타데이터 값 및 일반적인 Blob 인덱싱 오류를 진단합니다.

검색 결과에서 메타데이터 필드가 null입니다.

검색 결과에서 메타데이터 필드에 대한 null 또는 빈 값이 표시되는 경우 다음 검사 목록을 사용합니다.

  1. 필드가 인덱스 스키마에 있는지 확인합니다 . 캡처하려는 각 메타데이터 속성에 대한 필드를 정의한 것을 확인합니다. 인덱스에서 GET 요청을 실행하여 필드가 있는지 확인합니다.

  2. 올바른 필드 이름을 사용하세요: 표준 Blob 속성의 경우 metadata-storage-path 대신 metadata_storage_path와 같은 밑줄이 있는 이름을 사용합니다. 사용자 지정 메타데이터의 경우 필드 이름이 Blob의 메타데이터 키와 정확히 일치해야 합니다.

  3. 인덱서에 dataToExtract가 올바르게 설정되어 있는지 확인하세요:

    • contentAndMetadata (기본값)은 콘텐츠와 표준/사용자 지정 메타데이터를 모두 추출합니다.
    • storageMetadata 는 표준 Blob 속성 및 사용자 지정 메타데이터만 추출합니다.
    • allMetadata 는 표준 속성과 콘텐츠 형식별 메타데이터를 추출합니다.

    인덱서 구성을 확인하여 설정이 의도와 일치하는지 확인합니다.

  4. 스키마 업데이트 후 인덱서 다시 실행: 인덱싱에 새 필드를 추가한 경우 업데이트된 스키마에 대해 문서가 처리되도록 인덱서를 다시 실행합니다. 새 필드를 채우기 전에 기존 문서를 다시 처리해야 할 수 있습니다.

  5. 인덱서 실행 기록을 확인합니다. Azure 포털에서 인덱서로 이동하거나 REST API(인덱서 상태 가져오기)를 사용하여 실행 세부 정보 및 오류 메시지를 봅니다.

인덱서 오류 및 지원되지 않는 콘텐츠 형식

기본적으로 Blob 인덱서는 오디오 파일과 같이 지원되지 않는 콘텐츠 형식의 Blob을 발견하면 즉시 중지됩니다. excludedFileNameExtensions 매개 변수를 사용하여 특정 콘텐츠 형식을 건너뛸 수 있습니다.

일부 문서가 실패할 때 인덱싱을 계속하려면 다음 매개 변수를 조정한 다음 나중에 개별 문서를 조사합니다. 자세한 내용은 인덱서 문제 해결 지침 및 인덱서 오류 및 경고를 참조하세요.

오류가 발생하면 5개의 인덱서 매개 변수가 인덱서의 응답을 제어합니다.

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