자습서: ADLS Gen2 권한 인덱싱 및 필터링된 결과 확인

메모

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

이 자습서에서는 Foundry IQ(Azure AI 검색) 인덱서가 액세스 제어 목록(ACL) 및 역할 기반 액세스 제어(RBAC) 범위 정보를 검색 인덱스에 추가하는 Azure Data Lake Storage(ADLS) Gen2 권한 메타데이터 수집을 설명합니다. 이 기능은 2026-10-01 REST API에서 정식 출시되었습니다.

또한 허용된 사용자 및 거부된 사용자로 쿼리를 수행하고 인덱싱 후 권한 변경 사항을 확인하는 방법도 보여줍니다.

ACL 인덱싱에 대한 자세한 내용은 ADLS Gen2 인덱서를 사용하여 권한 메타데이터를 수집합니다.

이 자습서에서는 다음 방법을 알아봅니다.

  • 데이터 원본에서 adlsgen2의 RBAC 스코프와 ACL을 구성하십시오.
  • 사용 권한 정보 필드가 포함된 Foundry IQ 인덱스 만들기
  • 인덱서를 만들고 실행하여 데이터 원본에서 인덱스로 권한 정보를 수집합니다.
  • 방금 만든 인덱스 검색

REST 클라이언트 및 REST API 2026-10-01을 사용합니다. 현재 Azure 포털에는 ACL 인덱싱이 지원되지 않습니다.

필수 구성 요소

  • 활성 구독이 있는 Azure 계정입니다. 무료로 계정을 만듭니다.

  • Microsoft Entra ID 인증 및 권한 부여. 서비스 및 앱은 동일한 테넌트에 있어야 합니다. 역할 할당은 인증된 각 연결에 사용됩니다. 사용자와 그룹은 동일한 테넌트에 있어야 합니다. 작업할 사용자 및 그룹이 있어야 합니다. 테넌트 및 보안 주체 만들기는 이 자습서의 범위를 벗어납니다.

  • 계층 구조 네임스페이스가 있는 ADLS Gen2입니다.

  • 계층적 폴더 구조의 파일입니다. 이 자습서에서는 파일에 /Oregon/Portland/Data.txt대한 폴더 구조의 ADLS Gen2 데모를 가정합니다. 이 자습서에서는 연습을 성공적으로 완료할 수 있도록 폴더 및 파일에 대한 ACL 할당을 안내합니다.

  • Foundry IQ, 지역에 관계없이. 관리 ID 지원에는 기본 계층 이상이 필요합니다.

  • Visual Studio Code(REST Client extension 포함).

샘플 데이터 준비

ADLS Gen2에 parks라는 이름의 컨테이너를 만듭니다. 내용이 서로 다른 두 개의 일반 텍스트 파일을 업로드합니다.

  • Oregon/Portland/Data.txt
  • Washington/Seattle/Data.txt

이 자습서에서는 기본 구문 분석 모드를 사용하여 파일당 하나의 검색 문서를 만듭니다. 인덱스가 파일 이름과 추출된 텍스트를 저장합니다. .txt 파일에는 문서 수준 사용 권한과 함께 사용할 때 지원되지 않는 특수 text 구문 분석 모드가 필요하지 않습니다. 권한 수집에 대한 지원되는 구문 분석 및 콘텐츠 추출을 참조하세요.

Foundry IQ 서비스 구성 확인

Microsoft Entra ID 인증 및 권한 부여를 위해 Foundry IQ 서비스를 구성합니다. 이 체크리스트를 검토하여 준비가 되었는지 확인하세요.

로컬 테스트를 위한 개인 ID 토큰 가져오기

이 자습서에서는 공용 인터넷 연결을 통해 Azure 연결하는 로컬 시스템의 REST 클라이언트를 가정합니다.

다음 단계에 따라 개인 ID 토큰을 획득하고 Azure 리소스에 대한 로컬 연결용 Visual Studio Code를 설정합니다.

ADLS Gen2에서 권한 설정

최선의 방법으로, Group 집합을 직접 할당하는 대신 을 사용하는 것이 좋습니다.

  1. Foundry IQ 서비스 ID 엔터티에 컨테이너에 대한 읽기 권한을 부여합니다. 인덱서는 Foundry IQ 서비스 ID로 Azure Storage에 연결합니다. Foundry IQ 서비스에는 데이터를 검색하려면 Storage Blob Data Reader 권한이 있어야 합니다.

  2. 파일 계층 구조에서 그룹별 또는 사용자 권한을 부여합니다. 파일 계층 구조에서 컨테이너, 디렉터리, 및 파일에 할당된 모든 Group 및 User 집합을 식별합니다.

  3. Azure 포털을 사용하여 ACL을 관리할 수 있습니다. 스토리지 브라우저에서 Oregon 디렉터리를 선택한 다음 상황에 맞는 메뉴에서 ACL 관리를 선택합니다.

  4. 사용자 및 그룹에 대한 새 보안 주체를 추가합니다.

  5. 테스트 권한 부여에 명명된 사용자 및 명명된 그룹을 사용합니다. 소유 사용자, 소유 그룹 및 기타 항목은 ACL 인덱싱에 지원되지 않습니다. 테스트 ID에 대해서는 이러한 항목에 의존하지 마세요.

인덱싱하기 전에 지원되지 않는 암시적 blocklists 원본 ACL을 확인하고 지원되는 allowlistsACL로 수정합니다.

권한 메타데이터에 대한 검색 인덱스 만들기

콘텐츠 및 권한 메타데이터에 대한 필드가 포함된 인덱스를 만듭니다.

인덱스, 데이터 원본 및 인덱서 요청에 REST API 2026-10-01 을 사용합니다.

데모를 위해 사용 권한 필드를 retrievable 사용하도록 설정하여 인덱스에서 값을 확인할 수 있습니다. 프로덕션 환경에서는 중요한 정보가 누출되는 것을 방지하기 위해 사용하지 않도록 설정 retrievable 해야 합니다.

{
  "name" : "my-adlsgen2-acl-index",
  "fields": [
    {
      "name": "metadata_storage_path", "type": "Edm.String",
      "searchable": false, "filterable": true, "retrievable": true
    },
    {
      "name": "name", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "content", "type": "Edm.String",
      "searchable": true, "retrievable": true, "filterable": false
    },
    {
      "name": "id", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true, "stored": true,
      "key": true
    },
    { 
      "name": "UserIds", "type": "Collection(Edm.String)", 
      "permissionFilter": "userIds", 
      "searchable": false, "filterable": true, "retrievable": true
    },
    { 
      "name": "GroupIds", "type": "Collection(Edm.String)", 
      "permissionFilter": "groupIds", 
      "searchable": false, "filterable": true, "retrievable": true
    },
    { 
      "name": "RbacScope", "type": "Edm.String", 
      "permissionFilter": "rbacScope", 
      "searchable": false, "filterable": true, "retrievable": true
    }
  ],
  "permissionFilterOption": "enabled"
}

데이터 원본 만들기

인덱서 권한 수집 및 인덱싱하려는 권한 메타데이터 유형을 지정하도록 데이터 원본 구성 을 수정합니다.

데이터 원본에는 indexerPermissionOptions이(가) 필요합니다.

이 자습서에서는 인증된 연결에 시스템 할당 관리 ID를 사용합니다.

{
    "name" : "my-adlsgen2-acl-datasource",
    "type": "adlsgen2",
    "indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
    "name": "parks",
    "query": null
    }
}

인덱서 만들기 및 실행

원시 원본 경로에 대한 최상위 및 fieldMappings를 정의합니다. metadata_storage_path 는 RBAC 범위만 수집하는 경우에도 필요합니다. 이 필드를 인코딩하지 마세요.

{
  "name" : "my-adlsgen2-acl-indexer",
  "dataSourceName" : "my-adlsgen2-acl-datasource",
  "targetIndexName" : "my-adlsgen2-acl-index",
  "parameters": {
    "batchSize": null,
    "maxFailedItems": 0,
    "maxFailedItemsPerBatch": 0,
    "configuration": {
      "dataToExtract": "contentAndMetadata",
      "parsingMode": "default",
      "refreshAllAcls": true
    }
  },
  "fieldMappings": [
    { "sourceFieldName": "metadata_storage_path", "targetFieldName": "id", "mappingFunction": { "name": "base64Encode" } },
    { "sourceFieldName": "metadata_storage_name", "targetFieldName": "name" },
    { "sourceFieldName": "metadata_storage_path", "targetFieldName": "metadata_storage_path" },
    { "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

인덱서를 만들면 첫 번째 실행이 시작됩니다. 쿼리하기 전에 인덱서 상태 가져오기 를 사용하여 실행이 성공적으로 완료되었는지 확인합니다. 오류 및 경고를 검사하고 두 파일이 모두 인덱싱되었는지 확인합니다.

자동 ACL 새로 고침을 사용할 계획이라면 권한 변경을 확인하려면 인덱서 일정을 구성합니다.

쿼리를 실행하여 결과 확인

이제 문서가 로드되었으므로 문서 - 검색 포스트(REST)를 사용하여 쿼리를 실행할 수 있습니다.

URI는 연산자를 사용하여 /docs/search 지정된 쿼리 입력을 포함하도록 확장됩니다. 쿼리 토큰은 요청 헤더에 전달됩니다. 자세한 내용은 쿼리 시간 ACL 및 RBAC 적용을 참조하세요.

POST  {{endpoint}}/indexes/my-adlsgen2-acl-index/docs/search?api-version=2026-10-01
Authorization: Bearer {{search-token}}
x-ms-query-source-authorization: {{query-user-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,content,metadata_storage_path,GroupIds"
}

Authorization 헤더는 애플리케이션에서 Search를 쿼리할 수 있는 권한을 부여합니다. query-user-token는 권한 평가를 위한 위임된 사용자의 토큰이며, 다른 ID를 나타낼 수 있습니다.

권한 변경 확인

  1. 파일 읽기 액세스 권한이 있는 명명된 사용자로 쿼리하고 상위 디렉터리를 통해 액세스를 실행/트래버스합니다. 필요한 문서가 표시되는지 확인합니다.
  2. 일치하는 사용자 또는 그룹 ACL이 없고 지원되는 컨테이너 RBAC 부여가 없는 사용자로 조회합니다. 동일한 문서가 없는지 확인합니다.
  3. 파일 콘텐츠를 변경하지 않고 첫 번째 사용자의 ACL 부여를 제거합니다. 다른 ACL 또는 지원되는 RBAC 부여가 해당 사용자에게 권한을 부여하지 않는지 확인합니다. 사용 권한을 다시 동기화하고 인덱서를 실행하거나 조건을 충족하는 자동 ACL 새로 고침을 기다립니다.
  4. 완료 후 두 쿼리를 모두 다시 실행합니다. 해지된 사용자는 더 이상 문서를 가져올 수 없어야 하지만 명시적으로 권한이 부여된 다른 사용자는 여전히 가져올 수 있습니다.
  5. 명명된 그룹 부여 또는 제거와 상위 디렉터리 통과 변경에 대해서도 같은 작업을 반복합니다. RBAC 권한 부여 또는 제거를 별도로 테스트하되, 스토리지 전파 및 쿼리 권한 부여 캐시를 감안합니다.

청크 분할 파이프라인의 경우 영향을 받는 각 부모의 대표 청크도 확인합니다. 부분 실패 후 오류 및 경고를 검사하고 모든 결과를 조정된 것으로 처리하기 전에 다시 시도합니다. 표준 프로젝션 매핑을 사용하세요; 보호된 부모만으로는 권한 메타데이터가 누락된 청크를 보호하지 않습니다.