참고
Foundry IQ (Azure AI 검색)는 관리형 검색을 위한 상위 수준의 지식 원본 및 지식 베이스 API와 함께 직접 인덱싱 및 쿼리 API를 제공합니다. Azure 포털, REST API 또는 Azure SDK 사용하여 이러한 기능을 구성하거나 Microsoft Foundry 포털의 기술 자료에 에이전트를 연결합니다.
foundry IQ(Azure AI 검색)는 Azure Blob Storage 컨테이너 리소스 범위를 수집하고 위임된 사용자의 지원되는 Blob 읽기 권한 부여를 통해 쿼리 결과를 필터링합니다. 컨테이너 RBAC 범위 수집 및 쿼리 시간 필터링은 일반적으로 REST API 2026-10-01에서 사용할 수 있습니다.
Blob 인덱서 또는 Blob 지식 원본을 사용합니다. 표준 Blob 수집은 ADLS 파일 또는 디렉터리 ACL을 평가하지 않습니다. 해당 권한의 경우 ADLS Gen2 구성을 사용합니다.
RBAC 범위는 컨테이너 수준에서 설정되며 권한 상속을 통해 모든 Blob(문서)으로 흐릅니다. RBAC 범위는 권한 메타데이터로 인덱싱하는 동안 캡처됩니다. 푸시 API를 사용하여 콘텐츠 및 권한 메타데이터를 수동으로 업로드 및 인 덱싱하거나(푸시 REST API를 사용하여 인덱싱 권한 참조) 인덱서 또는 기술 자료 원본을 사용하여 데이터 수집을 자동화할 수 있습니다. 이 문서에서는 인덱싱 자동화에 중점을 둡니다.
저장된 범위는 컨테이너를 식별합니다. 이는 역할 할당이나 보안 주체 목록의 복사본이 아닙니다. 쿼리 시점에 x-ms-query-source-authorization는 위임된 사용자의 토큰을 전달합니다. Foundry IQ는 애플리케이션의 검색 데이터 평면 권한 부여와 별도로 저장된 범위에 대해 해당 사용자의 권한 부여를 평가합니다.
이 문서에서는 이 기초를 기반으로 하는 인덱싱 자동화 접근 방식에 중점을 둡니다.
Azure RBAC(역할 기반 액세스 제어)로 보호되는 Azure Storage blob. 특성 기반 액세스 제어(Azure ABAC)는 지원되지 않습니다.
Azure Blob 인덱서 또는 권한 필터를 포함하여 데이터 및 메타데이터를 검색하고 수집하는 Blob 지식 원본입니다. REST API
2026-10-01를 사용하거나 패키지 변경 로그에서 동등한 SDK 지원을 확인합니다.수집된 문서와 해당 권한을 포함하는 Foundry IQ의 인덱스입니다. 권한 메타데이터는 인덱스 필드로 저장됩니다.
필수 구성 요소
Microsoft Entra ID 인증 및 권한 부여. 서비스 및 앱은 동일한 테넌트에 있어야 합니다. 모든 테넌트가 Microsoft Entra ID인 경우, 사용자는 서로 다른 테넌트에 속할 수 있습니다. 역할 할당은 인증된 각 연결에 사용됩니다.
Foundry IQ, 모든 지역이지만 관리 ID 지원을 위한 청구 가능 계층(기본 이상)이 있어야 합니다. Foundry IQ 서비스는 역할 기반 액세스를 위해 구성 되어야 하며 관리 ID(시스템 또는 사용자)가 있어야 합니다.
컨테이너 RBAC 액세스가 있는 핫, 쿨 및 콜드 액세스 계층의 Azure Storage 표준 성능(범용 v2).
인덱서 및 기술 자료 원본의 작동 방식과 인덱스를 만드는 방법을 이해해야 합니다. 이 문서에서는 데이터 원본 및 인덱서에 대한 구성 설정을 설명하지만 인덱스를 만들기 위한 단계는 제공하지 않습니다. 권한 필터용으로 설계된 인덱스에 대한 자세한 내용은 권한 필터 필드가 있는 인덱스 만들기를 참조하세요.
Limitations
표준 또는 기본 문서 구문 분석(
parameters.configuration.parsingMode: "default") 또는 지원되는 경우 Content Understanding 기반 추출을 사용합니다. 생성된 모든 청크는 필요한 권한 메타데이터 및 원본 컨텍스트를 유지해야 합니다. 고객이 선택한 특수 구문 분석 모드는 지원되지 않습니다. 제외된 모드 및 기술 자료 설정 에 대한 권한 수집은 지원되는 구문 분석 및 콘텐츠 추출 을 참조하세요.Azure Portal은 이 기능을 지원하지 않습니다.
다음 인덱서 기능은 Blob Storage 권한 수집과 호환되지 않습니다.
Blob Storage 구성
Blob 컨테이너가 역할 기반 액세스를 사용하는지 확인합니다.
Azure 포털에 로그인하고 스토리지 계정을 찾습니다.
컨테이너를 확장하고 인덱싱할 Blob이 있는 컨테이너를 선택합니다.
Access Control(IAM)을 선택하여 역할 할당을 확인합니다. Storage Blob 데이터 판독기 또는 Storage Blob 데이터 기여자가 있는 사용자 및 그룹은 컨테이너가 인덱싱된 후 인덱스 내의 문서를 검색할 수 있습니다.
권한 부여
인덱서 실행의 경우 Foundry IQ 서비스 ID에 스토리지 Blob 데이터 판독 기 권한이 있어야 합니다. 자세한 내용은 관리 ID를 사용하여 Azure Storage 연결 참조하세요.
Foundry IQ 구성
Foundry IQ 서비스에는 다음이 있어야 합니다.
권한 부여
인덱서 실행을 위해 API 호출을 실행하는 클라이언트에는 개체를 만들 수 있는 Search Service 기여자 권한, 데이터 가져오기를 수행하기 위한 인덱스 데이터 기여자 검색 권한 및 인덱스 쿼리를 위한 인덱스 데이터 판독기 검색 권한이 있어야 합니다. 역할을 사용하여 Foundry IQ에 연결을 참조하세요.
지식 소스 구성
기술 원본을 사용하는 경우 기술 원본의 정의는 전체 인덱싱 파이프라인(인덱서, 데이터 원본 및 인덱스)을 생성하는 데 사용됩니다. RBAC 범위가 검색되고 생성된 인덱스로 자동으로 포함됩니다. 인덱싱된 콘텐츠에서 사용 권한 상속을 원하는 경우 생성된 개체를 수정할 필요가 없습니다.
이 시나리오에서 작동하게 하는 구성에 대한 핵심 사항은 다음과 같습니다.
-
isADLSGen2가 false로 설정되어 있으며, 즉 데이터 원본은 Azure Blob Storage입니다. -
ingestionPermissionOptions은rbacScope을 지정합니다.
# Create / Update Azure Blob Knowledge Source
###
PUT {{url}}/knowledgesources/azure-blob-ks?api-version=2026-10-01
api-key: {{key}}
Content-Type: application/json
{
"name": "azure-blob-ks",
"kind": "azureBlob",
"description": "A sample azure blob knowledge source",
"azureBlobParameters": {
"connectionString": "{{blob-connection-string}}",
"containerName": "blobcontainer",
"folderPath": null,
"isADLSGen2": false,
"ingestionParameters": {
"identity": null,
"embeddingModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"deploymentId": "{{embedding-deployment}}",
"modelName": "{{embedding-model}}",
"resourceUri": "{{aoai-endpoint}}",
"apiKey": "{{aoai-key}}"
}
},
"chatCompletionModel": null,
"disableImageVerbalization": true,
"ingestionSchedule": null,
"ingestionPermissionOptions": ["rbacScope"],
"contentExtractionMode": "minimal",
"aiServices": {
"uri": "{{ai-endpoint}}",
"apiKey": "{{ai-key}}"
}
}
}
}
참조:지식 원본 만들기 또는 업데이트 (REST API)
인덱서 기반 인덱싱 구성
인덱서를 사용하는 경우 Blob에서 권한 메타데이터를 끌어오도록 인덱서, 데이터 원본 및 인덱스를 구성합니다.
데이터 원본 만들기
데이터 원본 형식은 .이어야
azureblob합니다.인덱서 구성에서 기본 구문 분석 모드를 사용합니다.
데이터 원본에는
indexerPermissionOptions와rbacScope이(가) 있어야 합니다.rbacScope경우 관리 ID 형식으로 연결 문자열 구성합니다.사용자 할당 관리 ID를 사용하는 연결 문자열의 경우 속성도 지정
identity해야 합니다.
시스템 관리 ID 및 indexerPermissionOptions를 사용한 JSON 예제:
{
"name" : "my-blob-datasource",
"type": "azureblob",
"indexerPermissionOptions": ["rbacScope"],
"credentials": {
"connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
},
"container": {
"name": "<your-container-name>",
"query": "<optional-query-used-for-selecting-specific-blobs>"
}
}
연결 문자열에서 사용자 관리 식별자를 사용하는 JSON 스키마 예제:
{
"name" : "my-blob-datasource",
"type": "azureblob",
"indexerPermissionOptions": ["rbacScope"],
"credentials": {
"connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
},
"container": {
"name": "<your-container-name>",
"query": "<optional-query-used-for-selecting-specific-blobs>"
},
"identity": {
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
"userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
}
}
인덱스에서 권한 필드 만들기
Foundry IQ에서 인덱스에 사용 권한 메타데이터에 대한 필드 정의가 포함되어 있는지 확인합니다. 사용 권한 메타데이터는 데이터 원본 정의에 지정된 경우 indexerPermissionOptions 인덱싱할 수 있습니다.
직접 표준 Blob RBAC 인덱서의 경우 컨테이너 범위를 계산하는 데 metadata_storage_path가 필요하지 않습니다. 이 요구 사항은 RBAC 전용 수집에도 해당 필드가 필요한 ADLS Gen2 권한 수집과 다릅니다. 생성된 Blob 지식 원본 파이프라인에는 해당 스키마 및 원본 컨텍스트에 대한 원본 경로가 여전히 포함됩니다.
원본 메타데이터 매트릭스를 참조하세요.
RBAC 범위에 다음 특성을 사용합니다.
-
rbacScope퍼미션 필터 값이 포함된 RBAC 범위 필드입니다. - 쿼리 시 필터링을 사용하도록 설정하는 속성
permissionFilterOption입니다. - 사용 권한 메타데이터에 문자열 필드 사용
- 모든 필드에서 true로 설정합니다
filterable.
retrievable이 false임을 주목하세요. 개발 중에 true로 설정하여 사용 권한이 있는지 확인할 수 있지만, 보안 주체 ID가 결과에 표시되지 않도록 프로덕션 환경에 배포하기 전에 다시 false로 설정해야 합니다.
JSON 스키마 예제:
{
"name": "my-blob-rbac-index",
"fields": [
{ "name": "id", "type": "Edm.String", "key": true },
{
"name": "RbacScope",
"type": "Edm.String",
"permissionFilter": "rbacScope",
"filterable": true,
"retrievable": false
}
],
"permissionFilterOption": "enabled"
}
인덱서 구성
인덱서 내의 필드 매핑은 데이터 경로를 인덱스의 필드로 설정합니다. 이름 또는 데이터 형식에 따라 달라지는 대상 및 대상 필드에는 명시적 필드 매핑이 필요합니다. 필드 이름을 변경하면 Azure Blob Storage 다음 메타데이터 필드에 필드 매핑이 필요할 수 있습니다.
-
metadata_rbac_scope (
Edm.String) - 컨테이너 RBAC 범위입니다.
인덱싱하는 동안 사용 권한 메타데이터를 대상 필드로 라우팅하도록 인덱서에서 지정 fieldMappings 합니다.
지원되는 이 수집 흐름에 커넥터 파생 metadata_rbac_scope을 사용하고 컨테이너 범위가 문서의 최종 키 및 콘텐츠와 연관된 상태를 유지하는지 검토합니다. 일반 콘텐츠 또는 사용자 지정 메타데이터에서 비슷한 이름의 값을 액세스 권한 부여의 근거로 취급하지 마세요.
permissionFilter 주석은 저장된 값이 평가되는 방식을 식별하며 문서 소유권 검사가 아닙니다.
원본 콘텐츠를 작성할 수 있는 사용자와 키, 매핑 및 권한 값을 변경할 수 있는 사용자를 검토합니다. 암시적 키 매핑 및 프로젝션된 자식을 포함하여 Blob ID 및 권한 검사 목록을 따릅니다. 이 흐름에서 요구되는 기본 파싱 모드를 유지하세요. JSON 파싱 예제는 Blob 권한의 네이티브 수집을 지원함을 의미하지 않습니다.
JSON 스키마 예제:
{
"fieldMappings": [
{ "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
]
}
인덱서 실행
인덱서, 데이터 원본 및 인덱스가 구성된 후 인덱서를 실행하여 프로세스를 동작으로 설정합니다. 구성 또는 사용 권한에 문제가 있는 경우 이러한 문제가 이 단계에서 나타납니다.
기본적으로 인덱서는 Foundry IQ 서비스에 게시하는 즉시 실행되지만 인덱서 구성 disabled 에 true로 설정된 경우 인덱서를 수동으로 실행할 수 있도록 인덱서가 비활성화된 상태로 게시됩니다.
상태 및 메시지를 모니터링할 수 있도록 Azure 포털에서 인덱서를 실행합니다.
오류가 없다고 가정하면 이제 인덱스가 채워지고 쿼리 및 테스트를 진행할 수 있습니다.
범위 및 권한 부여를 최신 상태로 유지
스토리지 역할 할당 변경 내용은 인덱싱된 컨테이너 리소스 ID가 아니라 쿼리 시간 권한 부여에 영향을 줍니다. 권한 부여 또는 제거 후 스토리지 권한 부여 전파 및 해당 캐시를 허용합니다. 다시 인덱싱 또는 ACL 다시 동기화는 권한 부여 캐시를 강제로 새로 고치지 않습니다.
refreshAllAcls는 표준 Blob RBAC 수집이 아니라 ADLS ACL 수집에 적용됩니다.
인덱스 프로젝션을 사용하는 경우 보호된 모든 청크에서 청크의 /document/metadata_rbac_scope 주석이 추가된 필드에 rbacScope 직접 매핑합니다. 지식 원본을 사용할 때 생성된 소스 경로 매핑을 유지합니다. 스키마 또는 매핑을 수정해도 기존 레코드가 채워지지 않습니다. 파이프라인을 수정한 후 영향을 받는 콘텐츠를 다시 처리합니다.
지원되는 컨테이너 권한 부여 없이 허용된 사용자와 사용자를 테스트한 다음 인덱싱 변경 내용과 별도로 권한 부여 제거를 테스트합니다. 예기치 않은 결과를 해석하기 전에 지원되는 다른 권한을 확인합니다. 공유 새로 고침 및 정리 고려 사항은 사용 권한 동기화를 참조하세요.
삭제 추적
Blob 삭제를 효과적으로 관리하려면 인덱서가 처음으로 실행되기 전에 삭제 추적 을 사용하도록 설정했는지 확인합니다. 이 기능을 사용하면 시스템에서 원본에서 삭제된 Blob을 검색하고 인덱스에서 해당 콘텐츠를 삭제할 수 있습니다.