Foundry IQ(Azure AI 검색)에서 OneLake 권한 유지(미리 보기)

OneLake 인덱서 또는 인덱싱된 OneLake 지식 원본을 구성하여 Microsoft OneLake 권한을 유지합니다. Foundry IQ (Azure AI 검색)는 사용자 및 그룹 ACL이 아니라 원본 위치에 대한 메타데이터를 인덱싱하며, 쿼리 시 OneLake를 사용하여 요청한 사용자의 액세스를 평가합니다.

이 문서에서는 권한 수집과 관련된 구성에 대해 OneLake 파일 인덱싱 및 인덱싱된 OneLake 기술 자료 원본 만들기를 보완하여 설명합니다. Microsoft Fabric 원본 사용 권한을 관리합니다.

이 미리 보기는 Azure 퍼블릭 클라우드에서만 지원됩니다.

Important

OneLake 권한 수집은 공개 미리 보기로 제공되며 Microsoft Azure 미리 보기에 대한 추가 사용 약관의 적용을 받습니다.

이 기능과 관련된 미리 보기 관련 약관은 미리 보기 기능을 참조하세요.

외부 데이터 원본에 연결할 때 적용되는 용어는 외부 데이터 원본을 참조하세요.

Prerequisites

OneLake 인덱서 구성

직접 관리되는 인덱서 파이프라인의 경우 표준 OneLake 인덱싱 구성에 다음 설정을 추가합니다. 이러한 설정은 구성 추가이며, 완전한 생성 요청이 아닙니다.

  1. 수집할 원본 위치 메타데이터를 선택하려면 데이터 원본에서 indexerPermissionOptions을 설정합니다. 수집을 위해 oneLakeLakehouseId와 oneLakeParentFolders를 독립적으로 선택합니다. 다음 JSON 조각은 권한 인식 검색 가져오기를 위해 둘 다 선택합니다.

    {
      "indexerPermissionOptions": [
        "oneLakeParentFolders",
        "oneLakeLakehouseId"
      ]
    }
    
  2. 대상 인덱스에 해당 필드를 정의합니다.

    원본 메타데이터 예제 대상 필드 인덱스 필드 형식 필수 필드 구성
    metadata_onelake_parent_folders onelake_parent_folders Collection(Edm.String) filterable: true; permissionFilter: "oneLakeParentFolders". .
    metadata_onelake_lakehouse_id onelake_lakehouse_id Edm.String filterable: true; permissionFilter: "oneLakeLakehouseId". .
    metadata_onelake_is_shortcut metadata_onelake_is_shortcut Edm.Boolean filterable: true가 있고 permissionFilter 주석이 없는 최상위 필드입니다. 이 필드 이름을 유지합니다.

    레이크하우스 ID는 바로 가기의 대상 레이크하우스가 아닌 구성된 원본 레이크하우스를 식별합니다.

  3. 인덱스의 enabled를 permissionFilterOption로 설정하고, 원본 작업 영역 및 lakehouse ID로 oneLakeSecuritySource를 구성합니다.

    {
      "permissionFilterOption": "enabled",
      "oneLakeSecuritySource": {
        "fabricWorkspaceId": "<fabric-workspace-id>",
        "lakehouseId": "<lakehouse-id>"
      }
    }
    

userIds 또는 groupIds을 OneLake 권한 옵션으로 대체하지 마세요. 이러한 필드는 복사된 사용자 및 그룹 ACL 항목이 아닌 원본 위치를 나타냅니다.

소스에서 제공된 값을 유지합니다. 값을 기술 출력, 매핑 함수 또는 문서 콘텐츠에서 파생된 필드로 대체하지 마세요.

필드를 청크에 Project

기술 세트가 청크를 만들 때 인덱스 프로젝션을 통해 세 개의 메타데이터 필드를 모두 각 청크에 매핑합니다. 이러한 프로젝션 매핑은 청크 필드를 직접 채웁니다. 이들에는 fieldMappings 인덱서가 필요하지 않습니다.

  1. 앞의 표에 있는 세 개의 필드를 청크 인덱스에 추가합니다. 해당 인덱스의 permissionFilterOption 및 oneLakeSecuritySource을 앞에서 설명한 대로 구성합니다.

  2. 기술 세트에 다음 조각을 추가합니다. parent_id 필드와 /document/pages/*를 생성하는 텍스트 분할 기술을 사용하는 표준 청크 인덱스 스키마를 사용합니다. 예제를 조정할 때 다른 콘텐츠 매핑을 유지합니다.

    {
      "indexProjections": {
        "selectors": [
          {
            "targetIndexName": "<chunk-index-name>",
            "parentKeyFieldName": "parent_id",
            "sourceContext": "/document/pages/*",
            "mappings": [
              {"name": "chunk", "source": "/document/pages/*"},
              {
                "name": "onelake_parent_folders",
                "source": "/document/metadata_onelake_parent_folders"
              },
              {
                "name": "onelake_lakehouse_id",
                "source": "/document/metadata_onelake_lakehouse_id"
              },
              {
                "name": "metadata_onelake_is_shortcut",
                "source": "/document/metadata_onelake_is_shortcut"
              }
            ]
          }
        ],
        "parameters": {"projectionMode": "skipIndexingParentDocuments"}
      }
    }
    

skipIndexingParentDocuments를 사용하여 청크만 작성합니다. 작성된 각 콘텐츠 인덱스에는 세 개의 메타데이터 필드가 모두 필요합니다. 모든 콘텐츠 프로젝션의 앞서 표시된 해당 /document/metadata_onelake_* 원본에서 직접 매핑합니다.

문서 인덱싱을 위한 필드 매핑

nonchunked 수집 또는 별도의 부모 인덱스의 경우, 호환되는 형식의 일치하는 원본 및 대상 이름은 자동으로 매핑됩니다. 인덱서 필드 매핑을 예제 스키마에서와 같이 metadata_onelake_parent_folders을 onelake_parent_folders로, metadata_onelake_lakehouse_id을 onelake_lakehouse_id로 바꾸는 등 이러한 메타데이터 필드의 이름을 바꾸는 데에만 사용합니다. 변경되지 않은 metadata_onelake_is_shortcut 이름에는 명시적 필드 매핑이 필요하지 않습니다.

기존 인덱스에 사용 권한 필드를 추가해도 이미 인덱싱된 문서에는 해당 필드가 채워지지 않습니다. 권한 수집을 구성한 후 해당 문서를 다시 처리 하여 필요한 메타데이터를 채웁니다.

인덱싱된 OneLake 지식 원본 구성

인덱싱된 OneLake 지식 원본을 만들 때 indexedOneLakeParameters.ingestionParameters.ingestionPermissionOptions에서 두 값을 설정합니다:

{
  "ingestionPermissionOptions": [
    "oneLakeParentFolders",
    "oneLakeLakehouseId"
  ]
}

이 JSON 조각은 권한 설정만 표시합니다. 직접 데이터 원본 옵션과 달리 보안 인덱싱된 OneLake 수집에는 두 값이 함께 필요합니다. 2026-11-01-preview 및 두 권한 옵션을 모두 사용하는 전체 REST 생성 예제는 OneLake 권한 유지를 사용하여 지식 원본 만들기를 참조하세요.

지식 원본은 인덱스 필드, 인덱스 수준 권한 구성, 필드 매핑 및 청크 프로젝션을 생성합니다. 생성된 매핑을 별도로 구성할 필요가 없습니다.

OneLake 권한 수집을 사용하도록 설정하면 자산 저장소, 보강 캐시 및 그래프 추출 설정을 생략합니다.

요청 중인 사용자의 신원을 사용하여 쿼리

요청하는 사용자의 토큰에 을 포함하여 기존 x-ms-query-source-authorization을 사용합니다. 이러한 공유 예제에서 API 버전 대신 OneLake 권한 인식 요청에 2026-11-01-preview를 사용합니다. 기술 자료 문서의 경우 공유 쿼리 시간 권한 부여 지침을 따릅니다. OneLake에는 별도의 쿼리 프로토콜이 필요하지 않습니다.

검색은 구성된 Lakehouse 내에서 인덱싱된 부모 폴더 값에 대해 요청 중인 사용자의 읽기 가능한 OneLake 폴더를 평가합니다. 문서의 바로 상위 폴더 또는 상위 폴더와 일치하면 해당 문서가 검색 대상으로 검색될 수 있습니다. 원본 권한은 Fabric에서 관리됩니다.

Files/teamA/reports/document.txt의 경우 인덱싱된 폴더 값은 ["Files", "Files/teamA", "Files/teamA/reports"]입니다. 파일 이름은 포함되지 않습니다. 계층 구조에는 구성된 수집 하위 폴더 위의 상위 항목이 포함됩니다.

경로는 레이크하우스를 기준으로 한 상대 경로이며, 구분자로 /를 사용하고, 앞이나 뒤에 슬래시가 없습니다. 일치는 대/소문자를 구분합니다. 제공된 대로 공백, 유니코드 문자 및 리터럴 백분율 문자를 유지하세요. 이러한 메타데이터 값을 URI 디코딩하거나 다른 방식으로 다시 작성하지 마세요.

권한 및 경로의 최신 상태를 고려

인덱싱된 원본 위치 및 쿼리 시간 액세스 정보는 서로 다른 시간에 변경될 수 있습니다. 권한 취소를 포함한 권한 변경은 검색 결과에 반영되는 데 시간이 걸릴 수 있습니다. 종단 간 최신 상태 반영 시간은 고정되어 있지 않습니다.

쿼리는 인덱싱된 콘텐츠 및 쿼리 시간 권한 부여를 사용합니다. 인덱서 실행을 트리거하지 않습니다. 인덱서는 일반적으로 사용하지 않도록 설정되지 않은 경우 생성 시 실행되며, 이후에 수동으로 또는 일정에 따라 실행됩니다. 예약된 시간 또는 실행 요청은 완료 마감일이 아닙니다. 시작이 지연되거나 건너뛰어지는 경우 일정 동작을 참조하세요.

단계 변경을 지연할 수 있는 사항
Fabric 및 OneLake 작업 영역 역할, 항목 액세스 및 폴더 권한 전파
인덱서 시작 예약 및 실행 용량; 예약되거나 요청된 실행이 즉시 시작되지 않을 수 있습니다.
인덱서 실행 처리 기간, 스로틀링, 재시도 또는 실패한 항목
인덱스 가용성 청크 프로젝션, 문서 쓰기 및 인덱스 새로 고침은 업데이트된 콘텐츠 및 경로 메타데이터가 언제 검색 가능해지는지에 영향을 줍니다.
요청 사용자 ID 토큰의 최신 상태 및 사용자의 역할 또는 그룹 멤버 자격 변경
쿼리 시 액세스 캐시된 OneLake 액세스 정보는 새로 고칠 때까지 이전 사용 권한을 계속 반영할 수 있습니다. 새 사용자 토큰만으로는 캐시된 정보가 지워지지 않습니다.

인덱서 상태 및 실행 기록을 사용하여 실행 수준 시작 및 종료 시간, 오류, 경고 및 실패한 항목을 확인합니다. 최상위 running 상태는 실행이 진행 중이라는 의미가 아니라 인덱서를 실행할 수 있음을 의미합니다. 대표 문서와 청크에 필요한 메타데이터가 있는지 확인합니다. 성공적인 수집 실행이 Fabric 전파, 사용자 토큰 및 캐시된 액세스 정보도 새로 고쳐졌다는 것을 보장하지는 않습니다.

이동, 이름 바꾸기, 삭제 또는 경로 재사용 후 이전 위치의 부실 레코드와 새 위치의 레코드를 확인합니다. 이전 인덱싱된 콘텐츠는 현재 액세스가 변경된 경로와 계속 연결될 수 있습니다.

원본 파일을 물리적으로 제거하기 전에 OneLake 소프트 삭제 워크플로를 사용합니다. 원본 파일이 이미 제거된 경우 분리된 검색 문서 및 청크를 수동으로 삭제합니다.

실행 및 재설정 지침에 따라 여전히 존재하는 파일을 다시 처리합니다. 인덱서를 다시 설정해도 인덱싱된 문서를 삭제하지 않고 쿼리 시간 액세스 정보를 새로 고치지 않습니다.

권한 변경의 유효성을 검사할 때 새 사용자 토큰 및 공유 ACL 테스트 흐름을 사용합니다. 허용되는 사용자와 거부된 사용자를 비교하고 해당되는 경우 부모 문서와 청크를 모두 확인합니다. 인제션 완료를 해지 완료의 측정값으로 사용하지 마세요.

바로 가기 권한 경계 이해

OneLake 권한 인식 검색은 이 미리 보기의 바로 가기를 지원하지 않습니다. OneLake-to-OneLake 및 외부 바로 가기를 통해 도달한 콘텐츠를 포함하여 바로 가기 파생 콘텐츠는 결과에서 제외됩니다. 포함된 폴더 또는 바로 가기 대상에 액세스해도 바로 가기 콘텐츠를 검색할 수 없습니다.

일반적인 바로 가기 수집 지원 은 권한 인식 검색과는 별개입니다.

필수 metadata_onelake_is_shortcut 필드는 바로 가기 파생 콘텐츠를 직접 파일과 구분합니다. Edm.Boolean이 있고 filterable: true 주석이 없는 최상위 permissionFilter 필드로 정의합니다. 이 필드 이름과 원본 제공 값을 유지합니다. 누락되거나 null 값은 문서를 사용 권한 필터링 결과 대상에 포함시키지 않습니다. 이 필드를 상수 값으로 바꾸거나 부모 폴더 액세스에서 유추하지 마세요.

권한 필터링된 콘텐츠에 따른 개수, 패싯, 인용 및 그라운딩은 인덱싱된 모든 콘텐츠의 목록이 아닙니다.

권한 인식 검색 문제 해결

결과가 누락된 경우, 공유 쿼리 문제 해결 지침을 사용하기 전에 다음 원본별 조건을 확인하세요.

  • 세 개의 필수 필드가 있는지 확인하고 이전에 표시된 유형과 특성이 있는지 확인합니다. 청크의 경우 각 프로젝션의 매핑 및 원본 경로를 확인합니다.
  • Foundry IQ 서비스의 시스템 할당 관리 ID 및 Fabric 작업 영역의 Admin 역할을 확인합니다.
  • 콘텐츠가 바로 가기를 통해 제공되었는지 확인합니다. 바로 가기 제외는 누락된 부모 폴더 부여가 아니라 미리 보기 제한 사항입니다.
  • 콘텐츠를 이동하거나 사용 권한을 변경한 후 경로 최신 상태, 대/소문자 및 구성된 레이크하우스를 확인합니다.
  • 인증, 페이지 매김, 잘못된 응답 또는 경로 해결로 인해 OneLake 액세스 확인이 실패하는 경우 쿼리는 불완전한 액세스 정보로 계속 진행하지 않고 오류를 반환합니다. 다시 시도하기 전에 원본 액세스 또는 구성을 수정합니다.

Limitations

기본 제공 텍스트 및 임베딩 기술은 OneLake 권한 인제스트를 통해 지원됩니다. 다음 미리 보기 제약 조건이 적용됩니다.

  • 바로 가기 파생 콘텐츠는 권한 인식 검색에서 제외됩니다. 바로 가기 권한 경계를 참조하세요.
  • OneLake 권한 옵션을 사용하도록 설정하면 보강 캐싱, 지식 저장소 및 사용자 지정 Web API 기술이 지원되지 않습니다.
  • Chat Completion skills에는 OneLake 권한 수집에 지원되는 Microsoft 엔드포인트가 필요합니다. 사용자 지정 도메인 및 Azure API Management 엔드포인트는 지원되지 않습니다. 민감도 레이블 수집도 사용하도록 설정하는 경우 채팅 완료 기술은 어떤 엔드포인트에서도 지원되지 않습니다.