다음을 통해 공유

자습서: ADLS Gen2의 권한 메타데이터 인덱싱 및 권한 필터링 결과를 사용하여 쿼리

이 자습서에서는 인덱서를 사용하여 ADLS(Azure Data Lake Storage) Gen2 ACL(액세스 제어 목록) 및 RBAC(역할 기반 액세스 제어) 범위를 검색 인덱스로 인덱싱하는 방법을 보여 줍니다.

또한 사용자 액세스 권한을 존중하는 쿼리를 구성하는 방법도 보여 줍니다. 쿼리 결과가 성공하면 인덱스 중에 발생한 권한 전송이 확인됩니다.

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

이 튜토리얼에서는 다음을 배우게 됩니다:

  • 데이터 원본에서 adlsgen2 RBAC 범위 및 ACL을 설정 및 구성
  • 사용 권한 정보 필드를 포함하는 Azure AI Search 인덱스 만들기
  • 인덱서를 만들고 실행하여 데이터 원본에서 인덱스로 권한 정보를 수집합니다.
  • 방금 만든 인덱스 검색

REST 클라이언트를 사용하여 이 자습서와 최신 미리 보기 REST API를 완료합니다. 현재 Azure Portal에서는 ACL 인덱싱이 지원되지 않습니다.

필수 조건

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

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

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

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

  • Azure AI Search, 모든 지역 관리 ID 지원에는 기본 계층 이상이 필요합니다.

  • REST 클라이언트 또는 Python 클라이언트 및 Jupyter 패키지가 있는 Visual Studio Code입니다.

샘플 데이터 준비

ADLS Gen2의 컨테이너에 주립 공원 샘플 데이터를 업로드합니다. 컨테이너 이름은 "parks"여야 하며 "Oregon" 및 "Washington"이라는 두 개의 폴더가 있어야 합니다.

검색 서비스 구성 확인

Microsoft Entra ID 인증 및 권한 부여를 위해 검색 서비스를 구성해야 합니다. 이 검사 목록을 검토하여 준비가 되었는지 확인합니다.

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

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

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

ADLS Gen2에서 권한 설정

모범 사례로서, Group 집합을 직접 할당하는 대신 집합을 사용하는 것이 가장 좋습니다.

  1. 검색 서비스 ID에 컨테이너에 대한 읽기 권한을 부여합니다. 인덱서는 검색 서비스 ID에서 Azure Storage에 연결합니다. 검색 서비스에는 데이터를 검색하기 위한 스토리지 Blob 데이터 판독자 권한이 있어야 합니다.

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

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

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

  5. 소유 그룹, 소유 사용자 및 기타에 대한 기존 주체를 제거합니다. 이러한 주체는 공개 미리 보기 동안 ACL 인덱싱에서 지원되지 않습니다.

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

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

최신 미리 보기 REST API 또는 동등한 기능을 제공하는 미리 보기 Azure SDK 패키지를 사용해야 합니다. 권한 필터 속성은 미리 보기 API에서만 사용할 수 있습니다.

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

{
  "name" : "my-adlsgen2-acl-index",
  "fields": [
    {
      "name": "name", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "description", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true    
    },
    {
      "name": "location", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "state", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "AzureSearch_DocumentKey", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
      "stored": true,
      "key": true
    },
    { 
      "name": "UserIds", "type": "Collection(Edm.String)", 
      "permissionFilter": "userIds", 
      "searchable": true, "filterable": false, "retrievable": true
    },
    { 
      "name": "GroupIds", "type": "Collection(Edm.String)", 
      "permissionFilter": "groupIds", 
      "searchable": true, "filterable": false, "retrievable": true
    },
    { 
      "name": "RbacScope", "type": "Edm.String", 
      "permissionFilter": "rbacScope", 
      "searchable": true, "filterable": false, "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에서 정의하는 것입니다.

{
  "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": "delimitedText",
      "firstLineContainsHeaders": true,
      "delimitedTextDelimiter": ",",
      "delimitedTextHeaders": ""
      },
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
    ]
  }
}

인덱서를 만들고 즉시 실행하면 권한 메타데이터 정보와 함께 파일 콘텐츠가 인덱스로 인덱싱됩니다.

쿼리를 실행하여 결과 확인

이제 문서가 로드되었으므로 문서 - 게시물 검색(REST)을 사용하여 문서에 대한 쿼리를 실행할 수 있습니다.

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

POST  {{endpoint}}/indexes/stateparks/docs/search?api-version=2025-11-01-preview
Authorization: Bearer {{search-token}}
x-ms-query-source-authorization: {{search-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,description,location,GroupIds",
    "orderby": "name asc"
}

관련 콘텐츠

  • Last updated on