참고
Foundry IQ (Azure AI 검색)는 관리형 검색을 위한 상위 수준의 지식 원본 및 지식 베이스 API와 함께 직접 인덱싱 및 쿼리 API를 제공합니다. Azure 포털, REST API 또는 Azure SDK 사용하여 이러한 기능을 구성하거나 Microsoft Foundry 포털의 기술 자료에 에이전트를 연결합니다.
푸시 REST API를 통한 문서 수준 권한 수집은 일반적으로 사용할 수 있습니다. 푸시 REST API를 사용하여 Microsoft Entra 사용자 및 그룹 ID 또는 스토리지 컨테이너 RBAC 범위로 콘텐츠를 인덱싱합니다. foundry IQ(Azure AI 검색)는 이 메타데이터를 사용하여 쿼리 시 문서를 필터링합니다.
주요 기능은 다음과 같습니다.
- 데이터 수집 파이프라인을 유연하게 제어합니다.
- 권한 메타데이터에 대한 표준화된 스키마입니다.
- 폴더 수준 ACL과 같은 계층적 권한에 대한 지원
이 문서에서는 Push REST API를 사용하여 Foundry IQ에서 문서 수준 권한 메타데이터를 인덱싱하는 방법을 설명합니다. 이 프로세스는 검색 결과에 대한 최종 사용자 권한을 쿼리하고 적용하기 위해 인덱스를 준비합니다.
필수 구성 요소
Microsoft Entra ID 또는 다른 POSIX 스타일 ACL 시스템의 ACL 메타데이터가 포함된 콘텐츠입니다.
userIds및groupIdsACL 필드에는 UPN 또는 전자 메일 주소가 아니라 Microsoft Entra 개체 ID(GUID)를 사용하세요. 안정적인 개체 ID는 디렉터리 특성이 변경되더라도 쿼리 시 안정적인 ID 일치를 보장합니다.REST API 버전
2026-10-01.permissionFilterOption가 사용하도록 설정된 인덱스 스키마와, 문서 권한을 저장하는permissionFilter필드 특성.인덱스 정의 생성, 문서 업로드 및 인덱스 쿼리에 필요한 기존 권한. 역할 기반 액세스에 대해서는 역할을 사용하여 연결을 참조하세요.
쿼리 예제의 경우 위임된 사용자 액세스 토큰 및 동일한 사용자의 Microsoft Entra 개체 ID 쿼리 시간 토큰 역할 및 권한 흐름을 참조하세요.
제한
사용 권한 필터 유형
userIds이 있거나groupIds최대 1000개 값을 보유할 수 있는 ACL 필드입니다.인덱스가 모든 문서에서 최대 5개의 고유
rbacScope값을 보유할 수 있습니다.네이티브
permissionFilter주석은 기존의 호환 필드에 추가하거나 기존의 호환 필드에서 제거할 수 있습니다. 기존 주석은 다른 사용 권한 필터 형식으로 직접 변경할 수 없습니다.각
permissionFilter형식의 필드 하나(각각groupIds하나,userIds및rbacScope)만 인덱스로 존재할 수 있습니다.각
permissionFilter필드는filterable이며 최상위 수준이어야 합니다. 키 또는 벡터 필드가 아니어야 합니다. 사용 권한 필드에는 분석기, 정규화기 또는 동의어 맵이 있을 수 없습니다.쿼리 시간 권한 적용은 인덱스에 마지막으로 기록된 ACL 값을 반영합니다. 원본 권한이 변경되면 영향을 받는 문서를 다시 수집하거나 업데이트할 때까지 해당 업데이트가 반영되지 않습니다. ACL을 최신 상태로 유지하기 위해 증분 재수집 또는 부분 업데이트를 예약합니다.
이 기능은 현재 Azure 포털에서 지원되지 않습니다.
권한 필터 필드가 있는 인덱스 만들기
REST API를 사용하여 문서 ACL 및 RBAC 메타데이터를 인덱싱하려면 권한 필터를 사용하도록 설정하고 사용 권한 필터 할당이 있는 필드를 포함하는 인덱스 스키마를 설정해야 합니다.
enabled을 명시적으로 permissionFilterOption(으)로 설정합니다. 유효한 값은 enabled 및 disabled입니다. 사용 권한 필드 주석이 있는 새 인덱스의 경우 옵션을 생략하면 기본값은 enabled로 설정됩니다. 업데이트 시 누락은 있는 경우 기존 옵션을 유지합니다.
groupIds 및 Edm.String에는 userIds을 사용하고, rbacScope에는 Collection(Edm.String)을 사용합니다. 인덱스는 각 주석 유형마다 하나의 필드를 가질 수 있습니다.
다음 2026-10-01 워크플로는 userIds 사용 권한 필드가 있는 별도의 예제 인덱스를 만듭니다. 검색 가능한 content 필드는 moreLikeThis 예제도 지원합니다.
<SEARCH_ACCESS_TOKEN>는 엔드포인트로, 는 필요한 <SEARCH_SERVICE_ENDPOINT>가 있는 호출자 토큰으로 바꾸십시오. 요청이 동일한 이름으로 기존 인덱스를 업데이트하므로 새 인덱스에 대해서만 예제 이름을 사용합니다.
PUT <SEARCH_SERVICE_ENDPOINT>/indexes('secured-content-index')?api-version=2026-10-01
Authorization: Bearer <SEARCH_ACCESS_TOKEN>
Content-Type: application/json
Accept: application/json
{
"name": "secured-content-index",
"fields": [
{
"name": "id",
"type": "Edm.String",
"key": true,
"searchable": false,
"filterable": true,
"sortable": true
},
{
"name": "content",
"type": "Edm.String",
"searchable": true,
"filterable": false,
"sortable": false,
"facetable": false
},
{
"name": "category",
"type": "Edm.String",
"searchable": false,
"filterable": true,
"sortable": false,
"facetable": false
},
{
"name": "userIds",
"type": "Collection(Edm.String)",
"filterable": true,
"retrievable": false,
"searchable": false,
"sortable": false,
"facetable": false,
"permissionFilter": "userIds"
}
],
"permissionFilterOption": "enabled"
}
참조: 인덱스 만들기 또는 업데이트
다음 2026-10-01 스키마 조각은 이 문서의 뒷부분에 있는 인덱싱 예제에 대한 세 가지 네이티브 권한 필드 형식을 모두 보여 줍니다.
{
"fields": [
{ "name": "UserIds", "type": "Collection(Edm.String)", "permissionFilter": "userIds", "filterable": true, "retrievable": false },
{ "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false },
{ "name": "RbacScope", "type": "Edm.String", "permissionFilter": "rbacScope", "filterable": true, "retrievable": false },
{ "name": "DocumentId", "type": "Edm.String", "key": true }
],
"permissionFilterOption": "enabled"
}
SharePoint Online과 같은 엔터프라이즈 리포지토리의 경우, 푸시 API를 호출하기 전에 수집 중에 문서 수준 또는 폴더 수준 권한을 Microsoft Entra 사용자 및 그룹 개체 ID로 확인해야 합니다. 그런 다음 해당 사용 권한 필드에 해당 ID를 저장해야 합니다.
신뢰할 수 있는 문서 식별 및 권한 부여 설정
문서 게시를 대상 콘텐츠 및 사용 권한을 관리할 수 있도록 승인된 ID로 제한합니다. 게시자는 일반 콘텐츠에서 권한과 유사한 속성을 복사하는 대신 동일한 문서 ID에 대한 권한 있는 액세스 정책에서 부여를 얻어야 합니다.
업로드 또는 병합을 제출하기 전에 문서 키와 사용 권한을 함께 검토합니다. 키를 다시 사용하는 것은 동일한 인덱싱된 레코드를 대상으로 합니다. 콘텐츠를 작성할 수 있는 권한은 그 자체로 다른 레코드의 콘텐츠 또는 권한을 변경하는 권한이 아닙니다. 신뢰할 수 있는 여러 원본이 의도적으로 레코드를 공유하는 경우 소유권 및 최종 권한 정책에 합의하세요. 병합은 해당 컬렉션의 항목들을 기존 값과 결합하지 않고 제공된 컬렉션을 대체합니다.
고객 관리형 파이프라인의 경우 어떤 소스 값이 DocumentId를 제공하고 어떤 정책이 해당 자격 증명에 대한 권한 부여를 제공하는지 제어합니다. 기여하는 원본에서 고유하지 않은 경우 비즈니스 식별자를 별도로 유지합니다. 신뢰가 낮은 콘텐츠가 다른 레코드의 키 또는 사용 권한 값을 선택하도록 허용하지 마세요. 이러한 책임은 새 소유권 적용 설정이 아닌 권한 있는 게시자의 책임입니다.
사용 권한 필드 주석을 사용하면 저장된 값을 쿼리로 평가할 수 있습니다. 콘텐츠 작성자가 해당 권한 부여를 제공할 권한이 있다는 점을 설정하지는 않습니다. 수집 구성 검사 목록을 사용하여 신뢰할 수 있는 게시 프로세스 내에서 ID 및 권한 선택을 유지합니다.
REST API 인덱싱 예제
다른 문서 필드와 같은 방식으로 사용 권한 필드를 채우세요. 이전에 만든 인덱스 2026-10-01에 다음 4개의 문서를 업로드하세요.
를 <USER_OBJECT_ID>에서 토큰을 제공하는 위임된 사용자의 Microsoft Entra 개체 ID로 바꾸십시오. 문서 21, 101 및 control는 해당 사용자에게 액세스 권한을 부여합니다. hidden에는 권한 부여가 없습니다.
POST <SEARCH_SERVICE_ENDPOINT>/indexes('secured-content-index')/docs/search.index?api-version=2026-10-01
Authorization: Bearer <SEARCH_ACCESS_TOKEN>
Content-Type: application/json
Accept: application/json
{
"value": [
{
"@search.action": "upload",
"id": "21",
"content": "Astronomers use telescopes to study stars and galaxies. Telescope observations reveal stellar light and distant planets. An observatory records repeated measurements of stars to compare their brightness.",
"category": "astronomy",
"userIds": [
"<USER_OBJECT_ID>"
]
},
{
"@search.action": "upload",
"id": "101",
"content": "Astronomers use telescopes to study stars and galaxies. Telescope observations reveal stellar light and distant planets. An observatory records repeated measurements of stars to compare their brightness.",
"category": "astronomy",
"userIds": [
"<USER_OBJECT_ID>"
]
},
{
"@search.action": "upload",
"id": "hidden",
"content": "Astronomers use telescopes to study stars and galaxies. Telescope observations reveal stellar light and distant planets. An observatory records repeated measurements of stars to compare their brightness.",
"category": "astronomy",
"userIds": [
"none"
]
},
{
"@search.action": "upload",
"id": "control",
"content": "Botanical gardens cultivate orchids and roses. Gardeners prune flowering plants and water their roots. A greenhouse protects young seedlings from cold weather.",
"category": "gardening",
"userIds": [
"<USER_OBJECT_ID>"
]
}
]
}
참조: 인덱스 문서.
쿼리 예제를 계속 진행하여 사용자의 문서가 반환되고 hidden는 제외되는지 확인합니다.
다음 2026-10-01 예제에서는 다른 옵션을 보여 줍니다.
POST https://exampleservice.search.windows.net/indexes('indexdocumentsexample')/docs/search.index?api-version=2026-10-01
{
"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": ["none"],
"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"
}
]
}
2026년 10월 정규화 변경 전에 푸시된 ACL 업데이트
Foundry IQ는 문서를 제출할 때 사용 권한 ID 값을 소문자로 정규화합니다. 이 동작은 permissionFilter: "groupIds" 또는 permissionFilter: "userIds"로 주석 지정된 필드에 적용되지만 필드 이름이나 관련 없는 문서 필드에는 적용되지 않습니다.
2026년 10월 서비스 업데이트에서는 2026-05-01-preview 및 2026-08-01-preview에 대한 이러한 정규화가 도입되었습니다. 이 변경 사항은 2026-10-01 GA REST API에서도 유지됩니다. 서비스는 이전에 저장된 값을 자동으로 다시 쓰지 않습니다. API 버전만 바꾼다고 해서 업데이트되지는 않습니다.
정규화 변경 전에 미리 보기 버전을 사용하여 ACL을 직접 푸시한 경우 기존 대문자 또는 혼합 대/소문자 권한 ID가 쿼리 시간 ID와 일치하지 못할 수 있습니다. 권한 있는 사용자는 예상보다 적은 결과를 받을 수 있습니다.
이 마이그레이션은 푸시 API를 통해 직접 제출된 ACL에만 적용됩니다. 기본 제공 인덱서 또는 인덱싱된 지식 원본에는 필요하지 않습니다.
영향을 받는 ACL 값을 다시 인덱싱하려면 다음을 수행합니다.
- 변경 전에 푸시된 사용 권한 ID가 있는 문서 및 청크를 식별합니다. 소문자로 이미 저장된 값은 이 대소문자 형식 업데이트가 필요하지 않습니다.
- 영향을 받는 모든 레코드에 대해 현재 ACL 값을 다시 제출합니다.
문서 키와 전체 사용 권한 컬렉션이 포함된
merge작업을 사용하여 콘텐츠를 대체하지 않고 ACL을 업데이트합니다. 병합은 제공된 컬렉션을 대체합니다. 대/소문자만 다른 항목뿐만 아니라 모든 현재 부여를 포함합니다. - 각 레코드의 인덱싱 응답을 확인하고 실패한 업데이트를 다시 시도합니다. 영향을 받는 모든 레코드를 업데이트할 때까지 계속합니다. 부분 마이그레이션은 일관되지 않은 매칭을 남길 수 있습니다.
- 액세스 권한이 있어야 하는 사용자 및 액세스 권한이 없어야 하는 사용자로 쿼리를 테스트합니다. 일반 사용자 결과에 ACL 값을 노출하지 않고 진단에만 관리자 권한 읽기 를 사용합니다.
ACL 액세스 해결 규칙
네이티브 권한 필터링은 userIds, groupIds, rbacScope를 OR로 결합된 대체 권한 부여로 평가합니다. 한 필드의 일치 항목은 문서 액세스 권한을 부여합니다. 다른 필드의 일치하지 않는 값은 해당 부여를 재정의하지 않습니다. 이 하나의 권한 부여만으로도 허용되는 동작에는 성공적인 권한 평가가 필요합니다.
사용자는 일치하는 사용자 또는 그룹 ID 또는 인덱싱된 컨테이너 범위의 스토리지 Blob 읽기 권한 부여를 통해 액세스 권한을 얻습니다. 스토리지 범위 검사는 작업 자격 증명이 아니라 x-ms-query-source-authorization에서 위임된 사용자를 사용합니다. 작업 권한 확인은 여전히 필요합니다. 자세한 내용 및 권한 평가 실패 동작은 쿼리 시간 ACL 및 RBAC 적용을 참조하세요.
특수 ACL 값 "none"
ACL 필드(예: userIds 및 groupIds)에는 일반적으로 문서에 액세스할 수 있는 사용자 및 그룹을 식별하는 Microsoft Entra 개체 ID(GUID)가 포함됩니다. 특수 문자열 값 none 또는 빈 배열을 사용하여 ACL 필드가 액세스 권한을 부여하지 않음을 나타냅니다.
| ACL 값 | 의미 |
|---|---|
["none"] |
이 ACL 형식을 일치시켜 문서에 액세스할 수 있는 사용자는 없습니다. |
| [] (빈 배열) | 이 ACL 형식을 일치시켜 문서에 액세스할 수 있는 사용자는 없습니다. |
["none"]를 userIds 또는 빈 배열로 설정하면 어떤 사용자에게도 사용자 ID에 따라 문서에 대한 액세스 권한이 부여되지 않습니다. 그룹 ID 또는 RBAC 메타데이터를 일치시켜 여전히 액세스 권한을 부여받을 수 있습니다.
액세스 제어 예제
이 예제에서는 userIds, groupIds, 및 rbacScope의 권한 필드 값을 기준으로 문서 액세스 규칙이 어떻게 결정되는지 보여 줍니다. 가독성을 위해 이 시나리오에서는 GUID 대신 "user1" 및 "group1"과 같은 별칭을 사용합니다. 프로덕션 환경에서는 GUID(Microsoft Entra 개체 ID)를 사용합니다.
| 문서 # | 사용자 ID | 그룹 ID | RBAC 범위 | 허용된 사용자 목록 | 참고 |
|---|---|---|---|---|---|
| 1 | ["none"] |
[] |
빈 | 사용자에게 액세스 권한이 없음 | 값 ["none"] 과 [] 동작이 정확히 동일합니다. |
| 2 | ["none"] |
[] |
scope/to/container1 | container1에 대한 RBAC 권한이 있는 사용자 | "none" 값은 다른 권한 필드(groupIds 또는 rbacScope)가 액세스 권한을 부여할 때 액세스를 차단하지 않습니다. |
| 3 | ["none"] |
["group1", "group2"] |
빈 | group1 또는 group2의 멤버 | |
| 4 | ["user1", "user2"] |
["group1"] |
빈 | User1, user2 또는 group1의 모든 멤버 | |
| 5 | ["user1", "user2"] |
[] |
빈 | 사용자1 또는 사용자2 |