Используйте BLOB-индексатор или источник знаний для поиска метаданных областей RBAC

Служба хранилища Azure обеспечивает доступ на основе ролей к контейнерам в хранилище BLOB-объектов, где такие роли, как читатель данных BLOB-объектов хранилища или участник данных BLOB-объектов хранилища, определяют, имеет ли кто-то доступ к содержимому. Предварительные версии API в Службе поиска искусственного интеллекта Azure теперь поддерживают прием разрешений пользователей вместе с приемом документов, чтобы использовать эти разрешения для управления доступом к результатам поиска. Если у пользователя отсутствуют разрешения на определенный каталог или файл в службе хранилища Azure, этот пользователь не имеет доступа к соответствующим документам в результатах поиска ИИ Azure, даже если у вас лично есть назначение средства чтения данных индекса поискав индексе.

• 2025-05-01-preview и позже метаданные областей RBAC возможно извлекать с помощью индексатора BLOB.
• Предварительная версия 2025-11-01 обеспечивает эквивалентную поддержку источников данных Blob в хранилище Azure.

Область RBAC устанавливается на уровне контейнера и передается всем объектам BLOB (документам) за счет наследования разрешений. Область RBAC фиксируется во время индексирования в виде метаданных разрешений. Api push-уведомлений можно использовать для отправки и индексирования содержимого и метаданных разрешений вручную (см. раздел "Разрешения индексирования с помощью REST API push") или использовать индексатор или источник знаний для автоматизации приема данных. В этой статье рассматривается автоматизация индексирования.

Во время запроса идентификатор вызывающего объекта включается в заголовок запроса с помощью x-ms-query-source-authorization параметра. Удостоверение должно соответствовать метаданным разрешений в документах, чтобы пользователь мог видеть результаты поиска.

В этой статье рассматриваются подходы к автоматизации индексирования, основанные на этом фундаменте:

• Блоки Blob служба хранилища Azure, защищенные с помощью управления доступом на основе ролей (Azure RBAC). Нет поддержки управления доступом на основе атрибутов (Azure ABAC).

• Индексатор BLOB-объектов Azure или источник знаний BLOB-объектов , который извлекает и получает данные и метаданные, включая фильтры разрешений. Чтобы получить поддержку фильтра разрешений, используйте последнюю предварительную версию REST API или пакет предварительной версии пакета SDK Azure, поддерживающего эту функцию.

• Индекс в поиске ИИ Azure , содержащий обработанные документы и соответствующие разрешения. Метаданные разрешений хранятся в виде полей в индексе.

• Запрос, использующий фильтры разрешений. Чтобы настроить запросы, которые уважают фильтры разрешений, используйте последнюю предварительную версию REST API или пакет предварительной версии пакета Пакета SDK Azure, поддерживающего эту функцию.

Prerequisites

• Проверка подлинности и авторизация идентификатора Microsoft Entra. Службы и приложения должны находиться в одном арендаторе. Пользователи могут находиться в разных тенантах, если все тенанты используют Microsoft Entra ID. Назначения ролей используются для каждого аутентифицированного подключения.

• Поиск с использованием ИИ Azure, для любого региона, но для поддержки управляемых удостоверений необходимо иметь оплачиваемый уровень (базовый и выше). Служба поиска должна быть настроена для доступа на основе ролей и должна иметь управляемое удостоверение (система или пользователь).

• Служба хранилища Azure, стандартная производительность (универсальная версия 2) на горячих, промежуточных и холодных уровнях доступа с контейнерами или BLOB-объектами, защищенными с помощью РДД (RBAC).

• Вы должны понять, как работают индексаторы и источники знаний и как создать индекс. В этой статье описываются параметры конфигурации для источника данных и индексатора, но не приведены шаги по созданию индекса. Дополнительные сведения об индексах, предназначенных для фильтров разрешений, см. в разделе "Создание индекса с полями фильтра разрешений".

• Функциональность в настоящее время не поддерживается на портале Azure, включая фильтры разрешений, созданные с помощью мастера импорта данных. Используйте программный подход для создания или изменения существующих объектов для доступа на уровне документа.

Настройка хранилища BLOB-объектов

Убедитесь, что контейнер BLOB использует доступ на основе ролей.

1. Войдите на портал Azure и найдите учетную запись хранения.

2. Разверните контейнеры и выберите контейнер с объектами blob, которые нужно индексировать.

3. Выберите "Управление доступом" (IAM), чтобы проверить назначения ролей. Пользователи и группы с Чтением данных BLOB-объектов хранилища или Вкладом в данные BLOB-объектов хранилища имеют доступ к поиску документов в индексе после индексации контейнера.

Authorization

Для выполнения индексатора удостоверение личности службы поиска должно иметь разрешение на чтение данных BLOB-объектов в хранилище. Для получения дополнительной информации см. статью «Подключение к хранилищу Azure с помощью управляемого удостоверения».

Настройка поиска по искусственному интеллекту Azure

Помните, что служба поиска должна иметь следующее:

• Включен доступ на основе ролей
• Управляемое удостоверение настроено

Authorization

Для выполнения индексатора клиент, выдавающий вызов API, должен иметь разрешение участника службы поиска для создания объектов, разрешения участника индекса поиска для выполнения импорта данных и средства чтения данных индекса поиска , чтобы запросить индекс, см. статью Connect to Поиск с использованием ИИ Azure с помощью ролей.

Настройка источника знаний

Если вы используете источник знаний, определения в источнике знаний используются для создания полного конвейера индексирования (индексатора, источника данных и индекса). Область RBAC обнаруживается и автоматически включается в созданный индекс. Если требуется наследование разрешений в индексируемом содержимом, не нужно изменять какие-либо созданные объекты.

Особенности конфигурации, обеспечивающие её работу в этом сценарии:

• isADLSGen2 имеет значение false, что означает, что источник данных — хранилище BLOB-объектов Azure.
• ingestionPermissionOptions указывает rbacScope.

# Create / Update Azure Blob Knowledge Source
###
PUT {{url}}/knowledgesources/azure-blob-ks?api-version=2025-11-01-preview
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": "text-embedding-3-large",
                    "modelName": "text-embedding-3-large",
                    "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этого настройте строку подключения с форматом управляемого удостоверения.

  • Для строк подключения с помощью пользовательского управляемого удостоверения личности, вы должны также указать identity свойство.

Пример JSON с управляемым удостоверением системы и indexerPermissionOptions:

{
    "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}"
    }
}

Создание полей разрешений в индексе

В службе "Поиск ИИ Azure" убедитесь, что индекс содержит определения полей для метаданных разрешений. Метаданные разрешений могут быть индексированы, если indexerPermissionOptions указано в определении источника данных.

Рекомендуемые атрибуты схемы области RBAC:

• Поле области действия RBAC со значением rbacScope permissionFilter.
• Свойство permissionFilterOption для включения фильтрации во время запроса.
• Использование строковых полей для метаданных разрешений
• Задайте filterable значение true для всех полей.

Обратите внимание, что retrievable является ложным. Вы можете задать значение true во время разработки, чтобы проверить наличие разрешений, но не забудьте вернуть значение false перед развертыванием в рабочей среде, чтобы удостоверения субъектов безопасности не отображались в результатах.

Пример схемы JSON:

{
  ...
  "fields": [
    ...
    { 
        "name": "RbacScope", 
        "type": "Edm.String", 
        "permissionFilter": "rbacScope", 
        "filterable": true, 
        "retrievable": false 
    }
  ],
  "permissionFilterOption": "enabled"
}

Настройка индексатора

Сопоставления полей в индексаторе задают путь к данным полям в индексе. Для целевых и полей назначения, которые зависят от имени или типа данных, требуется явное сопоставление полей. Следующие поля метаданных в хранилище BLOB-объектов Azure могут потребовать сопоставления полей, если вы изменили имя поля.

• metadata_rbac_scope (Edm.String) — область контейнера RBAC.

Укажите fieldMappings в индексаторе, чтобы направить метаданные разрешений в целевые поля во время индексирования.

Пример схемы JSON:

{
  ...
  "fieldMappings": [
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

Запуск индексатора

После настройки индексатора, источника данных и индекса запустите индексатор, чтобы начать процесс. Если возникла проблема с конфигурацией или разрешениями, эти проблемы возникают на этом шаге.

По умолчанию индексатор запускается сразу после публикации его в службу поиска, но если конфигурация индексатора включает disabled значение true, индексатор размещается в отключенном состоянии, чтобы запустить индексатор вручную.

Мы рекомендуем запустить индексатор на портале Azure , чтобы отслеживать состояние и сообщения.

Если ошибок нет, индекс теперь заполнен, и вы можете перейти к запросам и тестированию.

Отслеживание удаления

Чтобы эффективно управлять удалением BLOB-объектов, убедитесь, что вы включили отслеживание удаления перед первым запуском индексатора. Эта функция позволяет системе обнаруживать удаленные BLOB-объекты из источника и удалять соответствующее содержимое из индекса.

См. также

• Подключение к поиску ИИ Azure с помощью ролей

• Принудительное применение ACL и RBAC на этапе выполнения запроса
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API

• Поиск по содержимому объектов BLOB в Azure
• Настройка индексатора BLOB-объектов