푸시 REST API(미리 보기)를 사용하여 문서 ACL(액세스 제어 목록) 인덱싱

푸시 REST API(미리 보기)를 통한 문서 수준 권한 수집을 통해 관련 ACL(액세스 제어 목록) 및 컨테이너 RBAC(역할 기반 액세스 제어) 역할과 함께 문서를 인덱싱할 수 있습니다. 푸시 REST API를 통해 콘텐츠를 Azure AI 검색 인덱스에 푸시하는 경우 서비스는 인덱싱된 콘텐츠에 대한 권한을 유지하고 쿼리 시 적용합니다.

주요 기능은 다음과 같습니다.

• 데이터 수집 파이프라인을 유연하게 제어합니다.
• 권한 메타데이터에 대한 표준화된 스키마입니다.
• 폴더 수준 ACL과 같은 계층적 권한에 대한 지원

이 문서에서는 푸시 REST API를 사용하여 Azure AI 검색 문서 수준 권한 메타데이터를 인덱싱하는 방법을 설명합니다. 이 프로세스는 검색 결과에 대한 최종 사용자 권한을 쿼리하고 적용하기 위해 인덱스를 준비합니다.

필수 구성 요소

• Microsoft Entra ID 또는 다른 POSIX 스타일 ACL 시스템의 ACL 메타데이터가 포함된 콘텐츠입니다. userIds 및 groupIds ACL 필드에는 UPN 또는 전자 메일 주소가 아니라 Microsoft Entra 개체 ID(GUID)를 사용하세요. 안정적인 개체 ID는 디렉터리 특성이 변경되더라도 쿼리 시 안정적인 ID 일치를 보장합니다.

• latest preview REST API 또는 동등한 기능을 제공하는 미리 보기 Azure SDK 패키지입니다.

• permissionFilterOption가 사용하도록 설정된 인덱스 스키마와, 문서 권한을 저장하는 permissionFilter 필드 특성.

제한

• 사용 권한 필터 유형 userIds 이 있거나 groupIds 최대 1000개 값을 보유할 수 있는 ACL 필드입니다.

• 인덱스가 모든 문서의 형식 rbacScope 필드 중에서 최대 5개의 고유 값을 보유할 수 있습니다. 동일한 값을 rbacScope공유하는 문서 수에는 제한이 없습니다.

• 기본 제공 ACL 또는 RBAC 메타데이터 필터링에 대한 할당을 permissionFilter 포함하도록 기존 필드를 업데이트할 수 있습니다. 기존 인덱스 필터링을 사용하도록 설정하려면 새 필드를 추가하거나 값을 포함 permissionFilter 하도록 기존 필드를 업데이트합니다.

• 각 permissionFilter 형식의 필드 하나(각각 groupIds하나, userIds및 rbacScope)만 인덱스로 존재할 수 있습니다.

• 각 permissionFilter 필드에는 filterable 값을 true 으로 설정해야 합니다.

• 쿼리 시간 권한 적용은 인덱스에 마지막으로 기록된 ACL 값을 반영합니다. 원본 권한이 변경되면 영향을 받는 문서를 다시 수집하거나 업데이트할 때까지 해당 업데이트가 반영되지 않습니다. ACL을 최신 상태로 유지하기 위해 증분 재수집 또는 부분 업데이트를 예약합니다.

• 이 기능은 현재 Azure 포털에서 지원되지 않습니다.

권한 필터 필드가 있는 인덱스 만들기

REST API를 사용하여 문서 ACL 및 RBAC 메타데이터를 인덱싱하려면 권한 필터를 사용하도록 설정하고 사용 권한 필터 할당이 있는 필드를 포함하는 인덱스 스키마를 설정해야 합니다.

먼저 .를 추가합니다 permissionFilterOption. 유효한 값은 enabled 또는 disabled이며, enabled로 설정해야 합니다. 인덱스 수준에서 권한 필터 기능을 해제하려는 경우 disabled로 전환할 수 있습니다.

둘째, 사용 권한 메타데이터에 대한 문자열 필드를 만들고 다음을 포함합니다 permissionFilter. 각 권한 필터 유형 중 하나를 사용할 수 있습니다.

다음은 모든 permissionFilter 형식을 포함하는 기본 예제 스키마입니다.

{  
  "fields": [  
    { "name": "UserIds", "type": "Collection(Edm.String)", "permissionFilter": "userIds", "filterable": true },  
    { "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true },  
    { "name": "RbacScope", "type": "Edm.String", "permissionFilter": "rbacScope", "filterable": true },  
    { "name": "DocumentId", "type": "Edm.String", "key": true }  
  ],
  "permissionFilterOption": "enabled"
}

SharePoint Online과 같은 엔터프라이즈 리포지토리의 경우, 푸시 API를 호출하기 전에 수집 중에 문서 수준 또는 폴더 수준 권한을 Microsoft Entra 사용자 및 그룹 개체 ID로 확인해야 합니다. 그런 다음 해당 사용 권한 필드에 해당 ID를 저장해야 합니다.

REST API 인덱싱 예제

권한 필터 필드가 있는 인덱스가 있으면 다른 문서 필드와 마찬가지로 푸시 인덱싱 API를 사용하여 해당 값을 채울 수 있습니다. 다음은 각 문서에서 인덱싱 작업, 키 필드(DocumentId) 및 사용 권한 필드를 지정하는 지정된 인덱스 스키마를 사용하는 예제입니다. 문서에는 콘텐츠도 포함되어야 하지만 간결하게 하기 위해 이 예제에서는 해당 필드가 생략됩니다.

POST https://exampleservice.search.windows.net/indexes('indexdocumentsexample')/docs/search.index?api-version=2026-08-01-preview
{
  "value": [
    {
      "@search.action": "upload",
      "DocumentId": "1",
      "UserIds": ["00aa00aa-bb11-cc22-dd33-44ee44ee44ee", "11bb11bb-cc22-dd33-ee44-55ff55ff55ff", "22cc22cc-dd33-ee44-ff55-66aa66aa66aa"],
      "GroupIds": ["none"],
      "RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-01"
    },
    {
      "@search.action": "merge",
      "DocumentId": "2",
      "UserIds": ["all"],
      "GroupIds": ["33dd33dd-ee44-ff55-aa66-77bb77bb77bb", "44ee44ee-ff55-aa66-bb77-88cc88cc88cc"]
    },
    {
      "@search.action": "mergeOrUpload",
      "DocumentId": "3",
      "UserIds": ["1cdd8521-38cf-49ab-b483-17ddaa48f68f"],
      "RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-03"
    }
  ]
}

ACL 액세스 해결 규칙

이 섹션에서는 시스템에서 각 문서의 사용 권한 필드를 기반으로 사용자의 문서 액세스를 결정하는 방법을 설명합니다. 이러한 필드는 ACL(userIds 및 groupIds, 여기서 groupIds에는 보안 그룹 및 Microsoft 365 그룹이 포함됨)이거나 RBAC 범위(rbacScope)입니다. Azure ADLS Gen2 권한 모델과 일치하는 정의된 순서로 RBAC 범위 및 ACL을 평가합니다.

사용자는 다음 필드 중 하나를 충족하면 액세스 권한을 얻습니다: 일치하는 userIds 또는 groupIds 항목, 또는 rbacScope에 대한 적합한 Azure 역할 할당. 쿼리 시간에 호출자 ID를 제공하는 방법에 대한 자세한 내용은 쿼리 시간 ACL 및 RBAC 적용을 참조하세요.

특수 ACL 값 "all"과 "none"

ACL 필드(예: userIdsgroupIds및)에는 일반적으로 문서에 액세스할 수 있는 사용자 및 그룹을 식별하는 GUID(Globally Unique Identifiers) 목록이 포함됩니다. 이러한 ACL 필드 형식에는 "all" 및 "none"이라는 두 개의 특수 문자열 값이 지원됩니다. 이러한 값은 다음 표와 같이 전역 수준에서 액세스를 제어하는 광범위한 필터 역할을 합니다.

사용자가 하나의 필드 형식만 일치해야 하므로 특수 값 "all"은 다른 ACL 필드 값에 관계없이 공용 액세스 권한을 부여합니다. 반면에 "none" 또는 빈 배열로 설정 userIds 하면 사용자 ID에 따라 문서에 대한 액세스 권한이 부여되지 않습니다. 그룹 ID 또는 RBAC 메타데이터를 일치시켜 여전히 액세스 권한을 부여받을 수 있습니다.

액세스 제어 예제

이 예제에서는 userIds, groupIds, 및 rbacScope의 권한 필드 값을 기준으로 문서 액세스 규칙이 어떻게 결정되는지 보여 줍니다. 가독성을 위해 이 시나리오에서는 GUID 대신 "user1" 및 "group1"과 같은 별칭을 사용합니다. 프로덕션 환경에서는 GUID(Microsoft Entra 개체 ID)를 사용합니다.

관련 콘텐츠

• 역할을 사용하여 Azure AI 검색 연결
• 쿼리 시 ACL 및 RBAC 적용
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API