Подключение к Поиск с использованием ИИ Azure с помощью ролей

Замечание

Поиск с использованием ИИ Azure доступна через портал Azure, REST API и Azure SDKs. Он также лежит в основе Foundry IQ — управляемого слоя знаний, который преобразует корпоративный контент в многократно используемые базы знаний с учетом разрешений доступа для агентов на портале Microsoft Foundry.

Поиск с использованием ИИ Azure поддерживает управление доступом на основе ролей через Microsoft Entra ID. Доступ на основе ролей является необязательным, но рекомендуется. Альтернативой является проверка подлинности на основе ключей, которая является стандартной.

При назначении нескольких ролей субъекту безопасности объединяются разрешения. Назначения ролей применяются ко всем средствам и клиентским библиотекам.

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

Подсказка

Хотите получить краткий обзор встроенных ролей? См . сводку разрешений.
Чтобы управлять доступом к результатам поиска на уровне документа, также известному как безопасность на уровне строк, см. раздел Управление доступом на уровне документа в Поиск с использованием ИИ Azure.

Предпосылки

Служба Поиск с использованием ИИ Azure (любой регион и любой уровень) с включенным доступом на основе ролей.
Разрешение на назначение ролей Azure. Любая из перечисленных ниже ролей подходит.
- Owner
- Администратор доступа пользователей
- Администратор ролевого управления доступом
- Пользовательская роль с Microsoft.Authorization/roleAssignments/write разрешениями
Просмотрите инструкции по назначению ролей для предпочтительного клиента:
Определите значение назначаемого пользователя, необходимое для предпочтительного клиента. В зависимости от типа клиента и назначателя это значение может быть именем субъекта-пользователя, идентификатором объекта группы, именем субъекта-службы, идентификатором приложения субъекта-службы или идентификатором объекта Microsoft Entra.

Встроенные роли

Роли — это коллекция разрешений, влияющих на плоскость управления или плоскость данных:

Плоскость управления: Операции по предоставлению, настройке и администрированию сервиса. Операции уровня управления включают создание или удаление служб поиска, перечисление ключей API и управление параметрами сети и проверки подлинности. Доступен через интерфейсы REST API Azure Resource Manager, Search Management REST API и эквивалентные клиентские библиотеки Azure SDK.
Плоскость данных: Операции с конечной точкой службы поиска. Операции плоскости данных делятся на две категории: управление объектами и доступ к содержимому. Доступно через REST API-интерфейсы службы Search Service и эквивалентные клиентские библиотеки Azure SDK.

Описания ролей

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

Должность	Самолет	Описание
владелец	Управление	Полный доступ к плоскости управления, включая возможность назначать роли и изменять параметры проверки подлинности. Администраторы подписок по умолчанию имеют эту роль. Может управлять ключами API. Не удается создать объекты поиска, загрузить документы, индексы запросов или получить из баз знаний.
Сотрудник	Управление	Тот же уровень доступа к плоскости управления, как у владельца, за исключением возможности назначать роли.
Читалка	Управление	Доступ к контрольной плоскости только для чтения. Может просматривать метрики служб и определения объектов. Не удается просмотреть ключи API или управлять ими, загружать документы, индексы запросов или извлекать из баз знаний.
Участник службы поиска	Управление и данные	Полный доступ к плоскости управления. Доступ к плоскости данных ограничен управлением объектами. Может создавать индексы, индексаторы, наборы навыков, базы знаний и другие объекты поиска. Может получать ключи API администратора и запрашивать их с помощью операций плоскости управления. Не удается загрузить документы, индексы запросов или получить из баз знаний непосредственно с помощью доступа на основе ролей. Полный список разрешений см. в разделе `Microsoft.Search/searchServices/*`.
Участник данных индекса поиска	Данные	Доступ к содержимому для чтения и записи. Может загружать документы, индексы запросов и извлекать их из баз знаний. Не удается изменить определения объектов или получить ключи администратора.
Средство чтения индексов поиска	Данные	Доступ к содержимому только для чтения. Может запрашивать индексы и извлекать из баз знаний. Не удается загрузить документы, изменить определения объектов или получить ключи администратора.

Это важно

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

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

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

Разрешения	Владелец или участник	Читатель	Участник службы поиска	Участник данных поискового индекса	Средство чтения данных индекса поиска
Создание и настройка служб Поиск с использованием ИИ Azure	✅	❌	✅	❌	❌
Доступ к службе на портале Azure	✅	✅	✅	❌	❌
Просмотр свойств службы, метрик и конечной точки	✅	✅	✅	❌	❌
Список всех объектов на службе	✅	✅	✅	❌	❌
Доступ к квотам и статистике услуг	✅	❌	✅	❌	❌
Просмотр, копирование и повторное создание ключей	✅	❌	✅	❌	❌
Настройка параметров проверки подлинности	✅	❌	✅	❌	❌
Просмотр ролей, политик и определений	✅	✅	✅	❌	❌
Настройка безопасности сети и частных подключений	✅	❌	✅	❌	❌
Создание, запуск и управление объектами поиска ¹	❌	❌	✅	❌	❌
Отправка данных для индексирования ²	❌	❌	❌	✅	❌
Запрос к индексу	❌	❌	❌	✅	✅
Получение из базы знаний	❌	❌	❌	✅	✅
Обход фильтров разрешений с повышенными привилегиями (предварительная версия)	❌	❌	❌	✅	❌

¹ Включает индексы, индексаторы, источники данных, наборы навыков, псевдонимы, карты синонимов, сеансы отладки, базы знаний и источники знаний. Индексаторы также поддерживают операции запуска и сброса.

² Владелец или участник могут запустить мастер импорта данных для создания и загрузки индексов, даже если они не могут отправлять документы в другие клиенты. Аналогичным образом индексаторы могут записывать в любой индекс в службе поиска независимо от назначений ролей на индекс. В обоих случаях служба поиска (а не пользователь) выполняет операции в плоскости данных с помощью своих разрешений Microsoft.Search/searchServices/indexes/documents/*.

Назначьте встроенные роли

В этом разделе вы назначите роли для:

Администрирование службы
Развитие
Доступ только для чтения

Назначьте роли для администрирования сервиса

Следующие роли позволяют создавать, настраивать и управлять службой поиска. Эти роли являются иерархическими, поэтому выберите одну на основе необходимого уровня доступа.

Должность	Идентификатор
владелец	8e3af657-a8ff-443c-a75c-2fe8c4bcb635
Сотрудник	b24988ac-6180-42a0-ab88-20f7382d2d2c
Читалка	acdd72a7-3385-48ef-bd42-f606fba81ae7

Перейдите в службу поиска на портале Azure.
В левой области выберите Access control (IAM).
Выберите + Добавить>Добавить назначение роли.
Выберите роль: владелец, участник или читатель.
На вкладке Members выберите идентификатор пользователя или группы Microsoft Entra. Если вы настраиваете разрешения для другой службы Azure, выберите управляемое удостоверение, назначаемое системой или назначаемое пользователем.
На вкладке Проверка и назначение выберите пункт Проверка и назначение, чтобы назначить роль.

Войдите в подписку Azure.
```
az login
```

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

az role assignment create \
    --assignee <assignee> \
    --role "Reader" \
    --scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

Справка:az role assignment create

Импортируйте необходимый модуль и подключитесь к учетной записи Azure.
```
Import-Module Az.Resources
Connect-AzAccount
```
Создайте назначение роли, заданное в службе поиска. В этом примере используется имя входа пользователя.
```
New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Reader" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"
```
Справочник:New-AzRoleAssignment

Откройте командную оболочку и войдите в подписку Azure.
```
az login
```

Получите токен доступа для Azure Resource Manager.

az account get-access-token --scope https://management.azure.com/.default --query accessToken --output tsv

Отправьте запрос PUT, чтобы создать назначение ролей в службе поиска. Установите для principalType значение User, Group или ServicePrincipal, чтобы оно соответствовало исполнителю.

PUT https://management.azure.com/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/providers/Microsoft.Authorization/roleAssignments/<role-assignment-guid>?api-version=2022-04-01 HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json

{
    "properties": {
        "roleDefinitionId": "/subscriptions/<subscription>/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7",
        "principalId": "<principal-object-id>",
        "principalType": "<principal-type>"
    }
}

Справочник:Назначения ролей — создание

Назначение ролей для разработки

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

Должность	Идентификатор
Участник службы поиска	7ca78c08-252a-4471-8644-bb5ff32d4ba0
Участник данных индекса поиска	8ebe5a00-799e-43f5-93ac-243d3dce84a7
Средство чтения индексов поиска	1407120a-92aa-4202-b7e9-c0e197c71c8f

Перейдите в службу поиска на портале Azure.
В левой области выберите Access control (IAM).
Выберите + Добавить>Добавить назначение роли.
Выберите соавтора службы поиска.
На вкладке Members выберите идентификатор пользователя или группы Microsoft Entra. Если вы настраиваете разрешения для другой службы Azure, выберите управляемое удостоверение, назначаемое системой или назначаемое пользователем.
На вкладке Проверка и назначение выберите пункт Проверка и назначение, чтобы назначить роль.
Повторите эти действия, чтобы назначить участника индексов поиска и средства чтения данных индексов поиска.

Войдите в подписку Azure.
```
az login
```

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

az role assignment create \
    --assignee <assignee> \
    --role "Search Index Data Contributor" \
    --scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

Справка:az role assignment create

(Необязательно) Создайте назначение ролей, ограниченное индексом. Укажите назначаемого и область.

az role assignment create \
    --assignee <assignee> \
    --role "Search Index Data Contributor" \
    --scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

Справка:az role assignment create

Импортируйте необходимый модуль и подключитесь к учетной записи Azure.
```
Import-Module Az.Resources
Connect-AzAccount
```

Создайте назначение роли, заданное в службе поиска. В этом примере используется имя входа пользователя.

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

Справочник:New-AzRoleAssignment

(Необязательно) Создайте назначение ролей, ограниченное индексом. В этом примере используется имя входа пользователя.

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

Справочник:New-AzRoleAssignment

Откройте командную оболочку и войдите в подписку Azure.
```
az login
```

Получите токен доступа для Azure Resource Manager.

az account get-access-token --scope https://management.azure.com/.default --query accessToken --output tsv

PUT https://management.azure.com/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/providers/Microsoft.Authorization/roleAssignments/<role-assignment-guid>?api-version=2022-04-01 HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json

{
    "properties": {
        "roleDefinitionId": "/subscriptions/<subscription>/providers/Microsoft.Authorization/roleDefinitions/8ebe5a00-799e-43f5-93ac-243d3dce84a7",
        "principalId": "<principal-object-id>",
        "principalType": "<principal-type>"
    }
}

Справочник:Назначения ролей — создание

(Необязательно) Отправьте запрос PUT, чтобы создать назначение ролей в пределах индекса.

PUT https://management.azure.com/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>/providers/Microsoft.Authorization/roleAssignments/<role-assignment-guid>?api-version=2022-04-01 HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json

{
    "properties": {
        "roleDefinitionId": "/subscriptions/<subscription>/providers/Microsoft.Authorization/roleDefinitions/8ebe5a00-799e-43f5-93ac-243d3dce84a7",
        "principalId": "<principal-object-id>",
        "principalType": "<principal-type>"
    }
}

Справочник:Назначения ролей — создание

Назначьте роли для доступа только для чтения

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

Должность	Идентификатор
Средство чтения индексов поиска	1407120a-92aa-4202-b7e9-c0e197c71c8f

Перейдите в службу поиска на портале Azure.
В левой области выберите Access control (IAM).
Выберите + Добавить>Добавить назначение роли.
Выберите роль читателя индексов поиска .
На вкладке Members выберите идентификатор пользователя или группы Microsoft Entra. Если вы настраиваете разрешения для другой службы Azure, выберите управляемое удостоверение, назначаемое системой или назначаемое пользователем.
На вкладке Проверка и назначение выберите пункт Проверка и назначение, чтобы назначить роль.

Войдите в подписку Azure.
```
az login
```

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

az role assignment create \
    --assignee <assignee> \
    --role "Search Index Data Reader" \
    --scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

Справка:az role assignment create

(Необязательно) Создайте назначение ролей, ограниченное индексом. Укажите назначаемого и область.

az role assignment create \
    --assignee <assignee> \
    --role "Search Index Data Reader" \
    --scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

Справка:az role assignment create

Импортируйте необходимый модуль и подключитесь к учетной записи Azure.
```
Import-Module Az.Resources
Connect-AzAccount
```

Создайте назначение роли, заданное в службе поиска. В этом примере используется имя входа пользователя.

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Reader" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

Справочник:New-AzRoleAssignment

(Необязательно) Создайте назначение ролей, ограниченное индексом. В этом примере используется имя входа пользователя.
```
New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Reader" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"
```
Справочник:New-AzRoleAssignment

Откройте командную оболочку и войдите в подписку Azure.
```
az login
```

Получите токен доступа для Azure Resource Manager.

az account get-access-token --scope https://management.azure.com/.default --query accessToken --output tsv

PUT https://management.azure.com/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/providers/Microsoft.Authorization/roleAssignments/<role-assignment-guid>?api-version=2022-04-01 HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json

{
    "properties": {
        "roleDefinitionId": "/subscriptions/<subscription>/providers/Microsoft.Authorization/roleDefinitions/1407120a-92aa-4202-b7e9-c0e197c71c8f",
        "principalId": "<principal-object-id>",
        "principalType": "<principal-type>"
    }
}

Справочник:Назначения ролей — создание

(Необязательно) Отправьте запрос PUT, чтобы создать назначение ролей в пределах индекса.

PUT https://management.azure.com/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>/providers/Microsoft.Authorization/roleAssignments/<role-assignment-guid>?api-version=2022-04-01 HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json

{
    "properties": {
        "roleDefinitionId": "/subscriptions/<subscription>/providers/Microsoft.Authorization/roleDefinitions/1407120a-92aa-4202-b7e9-c0e197c71c8f",
        "principalId": "<principal-object-id>",
        "principalType": "<principal-type>"
    }
}

Справочник:Назначения ролей — создание

Тестирование назначений ролей

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

Прежде чем продолжить, настройте приложение для бессерверных подключений и укажите назначения ролей.

Перейдите в службу поиска на портале Azure.
На левой панели выберите Управление поиском>Индексы, чтобы протестировать разрешения, связанные с индексами.
- Участники службы поиска могут создавать, изменять и удалять объекты поиска, но не могут загружать документы или выполнять запросы. Чтобы проверить разрешения, создайте индекс поиска.
- Участники индекса поиска могут загружать документы. Нет возможности загрузить документы на портале Azure за пределами мастера Import data, но вы можете сбросить и запустить индексатор для подтверждения разрешений на загрузку документов.
- Читатели данных поискового индекса могут выполнять запросы к индексам. Чтобы проверить разрешения, используйте обозреватель поиска. Вы должны иметь возможность отправлять запросы и просматривать результаты, но вы не сможете просматривать определения индексов или создавать индексы.

Этот подход предполагает Visual Studio Code с расширением клиента REST.

Откройте командную оболочку для Azure CLI и войдите в подписку Azure.
```
az login
```
Получите токен доступа для плоскости управления данными Поиск с использованием ИИ Azure.
```
az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
```

Вставьте эти переменные в новый текстовый файл в Visual Studio Code.

@baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
@index-name = PASTE-YOUR-INDEX-NAME-HERE
@token = PASTE-YOUR-TOKEN-HERE

Отправьте запрос, использующий указанные переменные. Для роли читателя индексов поиска можно отправить запрос с помощью любой поддерживаемой версии API.
```
POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2026-04-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}

{
    "queryType": "simple",
    "search": "motel",
    "filter": "",
    "select": "HotelName,Description,Category,Tags",
    "count": true
}
```
Справочник:Поиск документов

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

Подсказка

Дополнительные сведения о том, как получить токен для конкретной среды, см. в статьях Управление службой Поиск с использованием ИИ Azure с интерфейсами REST API и библиотеки аутентификации платформы Microsoft Identity.

Установите необходимые пакеты.

dotnet add package Azure.Search.Documents
dotnet add package Azure.Identity

Используйте Azure.Identity для .NET для проверки подлинности маркера. Microsoft рекомендует DefaultAzureCredential() для большинства сценариев.

Ниже приведен пример подключения клиента с помощью DefaultAzureCredential().

// Create a SearchIndexClient to send create/delete index commands
// Requires Search Service Contributor role
SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());

// Create a SearchClient to load and query documents
// Requires Search Index Data Contributor (load) or Search Index Data Reader (query)
SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new DefaultAzureCredential());

Reference:SearchClient, SearchIndexClient, DefaultAzureCredential

Ниже приведен еще один пример использования учетных данных секрета клиента.

var tokenCredential =  new ClientSecretCredential(aadTenantId, aadClientId, aadSecret);
SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, tokenCredential);

Ниже приведен пример выполнения запроса.
```
SearchResults<SearchDocument> response = srchclient.Search<SearchDocument>("motel");
foreach (SearchResult<SearchDocument> result in response.GetResults())
{
    Console.WriteLine(result.Document["HotelName"]);
}
```
Успешный запрос возвращает результаты поиска. Если документы не соответствуют, коллекция результатов пуста.

Установите необходимые пакеты.
```
pip install azure-search-documents azure-identity
```
Используйте Azure.Identity для Python для аутентификации токенов.
Используйте DefaultAzureCredential, если клиент Python является приложением, выполняющим серверную сторону. Включите интерактивную проверку подлинности , если приложение работает в браузере.

Приведем пример.

from azure.search.documents import SearchClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
endpoint = "https://<mysearch>.search.windows.net"
index_name = "myindex"
client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)

Reference:SearchClient, DefaultAzureCredential

Установите необходимые пакеты.
```
npm install @azure/search-documents @azure/identity
```
Используйте Azure.Identity для JavaScript для токен аутентификации.
Если вы используете React, используйте InteractiveBrowserCredential для проверки подлинности Microsoft Entra для Поиск с использованием ИИ Azure. Дополнительные сведения см. в разделе "Когда следует использовать @azure/identity".

Reference:SearchClient, DefaultAzureCredential

Добавьте необходимые зависимости в свой pom.xml.

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-search-documents</artifactId>
  <version>11.7.4</version>
</dependency>
<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-identity</artifactId>
  <version>1.15.0</version>
</dependency>

Используйте Azure.Identity для Java для аутентификации токена.
Используйте DefaultAzureCredential для приложений, работающих на Azure.

Предоставление доступа к одному индексу

В некоторых сценариях может потребоваться ограничить доступ приложения к одному ресурсу, например индексу.

В настоящее время портал Azure не поддерживает назначения ролей на уровне индекса. Используйте Azure CLI, PowerShell или REST API для назначения ролей, ограниченных одному индексу.

Войдите в подписку Azure.
```
az login
```

Создайте назначение роли, ограниченное одним индексом. Укажите исполнителя и область действия на уровне индекса.

az role assignment create \
    --assignee <assignee> \
    --role "Search Index Data Contributor" \
    --scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

Справка:az role assignment create

Импортируйте необходимый модуль и подключитесь к учетной записи Azure.
```
Import-Module Az.Resources
Connect-AzAccount
```

Создайте назначение роли, ограниченное одним индексом. В этом примере используется имя входа пользователя.

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

Справочник:New-AzRoleAssignment

Откройте командную оболочку и войдите в подписку Azure.
```
az login
```

Получите токен доступа для Azure Resource Manager.

az account get-access-token --scope https://management.azure.com/.default --query accessToken --output tsv

Отправьте запрос PUT, чтобы создать назначение ролей в пределах одного индекса. Установите для principalType значение User, Group или ServicePrincipal, чтобы оно соответствовало исполнителю.

PUT https://management.azure.com/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>/providers/Microsoft.Authorization/roleAssignments/<role-assignment-guid>?api-version=2022-04-01 HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json

{
    "properties": {
        "roleDefinitionId": "/subscriptions/<subscription>/providers/Microsoft.Authorization/roleDefinitions/8ebe5a00-799e-43f5-93ac-243d3dce84a7",
        "principalId": "<principal-object-id>",
        "principalType": "<principal-type>"
    }
}

Справочник:Назначения ролей — создание

Операции с областью и индексатором для каждого индекса

Назначения ролей по индексу применяются только к операциям API, выполняемым непосредственно, таким как запросы или отправка документов пользователями или приложениями. Индексаторы не ограничиваются разрешениями на индекс, потому что они работают с учетными данными уровня сервиса.

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

Для строгой изоляции данных между индексами рассмотрим следующие подходы:

Используйте отдельные службы поиска для команд или пользователей, которым требуется изоляция на уровне индекса.
Назначайте Search Service Contributor только администраторам, которые управляют индексаторами.
Используйте управление доступом на уровне документа с фильтрами безопасности, чтобы ограничить результаты запроса в общем индексе.

Создание настраиваемой роли

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

В следующих примерах клонируйте средство чтения данных индекса поиска и добавьте возможность перечислять индексы по имени. Как правило, перечисление индексов в службе поиска считается административным правом.

Войдите на портал Azure и перейдите в службу поиска.
В левой области выберите Access control (IAM).
На вкладке «Роли» найдите роль «Search Index Data Reader» или другую роль, выберите многоточие (...), затем выберите «Клонировать».
На вкладке Basics введите имя настраиваемой роли, например "Индекс поиска Исследователь данных", а затем выберите Далее.
На вкладке "Разрешения" выберите "Добавить разрешения".
В области разрешений Add выберите плитку Поиск (Майкрософт).
При выборе действий в верхней части задайте следующие разрешения:
- В разделе Microsoft.Search/operations выберите Read: перечисление всех доступных операций.
- В разделе Microsoft.Search/searchServices/indexes выберите Read : Read Index.

Перейдите на Data Actions вверху и в разделе Microsoft.Search/searchServices/indexes/documents выберите Read: Read Documents.

Определение JSON выглядит следующим образом:

{
    "properties": {
        "roleName": "Search Index Data Explorer",
        "description": "List all indexes on the service and query them.",
        "assignableScopes": [
            "/subscriptions/<subscription>/resourceGroups/<resource-group>"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.Search/operations/read",
                    "Microsoft.Search/searchServices/indexes/read"
                ],
                "notActions": [],
                "dataActions": [
                    "Microsoft.Search/searchServices/indexes/documents/read"
                ],
                "notDataActions": []
            }
        ]
    }
}

Нажмите кнопку "Добавить ", чтобы закрыть область.
Выберите "Проверить и создать" , чтобы создать роль.

Теперь вы можете назначить пользователей и группы к роли. Дополнительные сведения об этих шагах см. в статье Создание и обновление пользовательских ролей в Azure с помощью портала.

В примере Azure CLI показан синтаксис JSON для создания настраиваемой роли, которая является клоном средства чтения данных индекса поиска, но с возможностью перечисления всех индексов по имени. Пошаговые инструкции по созданию пользовательских ролей см. в статье "Создание или обновление Azure пользовательских ролей с помощью Azure CLI".

Просмотрите список атомарных разрешений , чтобы определить нужные. В этом примере вам потребуются следующие разрешения:
```
"Microsoft.Search/operations/read",
"Microsoft.Search/searchServices/indexes/read",
"Microsoft.Search/searchServices/indexes/documents/read"
```

Сохраните следующее определение роли в JSON-файле с именем search-index-data-explorer.json. Для Id укажите новый GUID, который вы сгенерируете.

{
    "Name": "Search Index Data Explorer",
    "Id": "<role-definition-guid>",
    "IsCustom": true,
    "Description": "List all indexes on the service and query them.",
    "Actions": [
        "Microsoft.Search/operations/read",
        "Microsoft.Search/searchServices/indexes/read"
    ],
    "NotActions": [],
    "DataActions": [
        "Microsoft.Search/searchServices/indexes/documents/read"
    ],
    "NotDataActions": [],
    "AssignableScopes": [
        "/subscriptions/<subscription>/resourceGroups/<resource-group>"
    ]
}

Создайте пользовательскую роль, передав JSON-файл в az role definition create.
```
az role definition create --role-definition @search-index-data-explorer.json
```
Справка:az role definition create

В примере PowerShell показан синтаксис JSON для создания пользовательской роли, которая является клоном средства чтения данных индекса поиска, но с возможностью перечисления всех индексов по имени. Пошаговые инструкции по созданию настраиваемых ролей см. в статье "Создание или обновление Azure настраиваемых ролей с помощью Azure PowerShell".

Просмотрите список атомарных разрешений , чтобы определить нужные. В этом примере вам потребуются следующие разрешения:
```
"Microsoft.Search/operations/read",
"Microsoft.Search/searchServices/indexes/read",
"Microsoft.Search/searchServices/indexes/documents/read"
```

{
    "Name": "Search Index Data Explorer",
    "Id": "<role-definition-guid>",
    "IsCustom": true,
    "Description": "List all indexes on the service and query them.",
    "Actions": [
        "Microsoft.Search/operations/read",
        "Microsoft.Search/searchServices/indexes/read"
    ],
    "NotActions": [],
    "DataActions": [
        "Microsoft.Search/searchServices/indexes/documents/read"
    ],
    "NotDataActions": [],
    "AssignableScopes": [
        "/subscriptions/<subscription>/resourceGroups/<resource-group>"
    ]
}

Создайте пользовательскую роль, передав JSON-файл в New-AzRoleDefinition.
```
New-AzRoleDefinition -InputFile "search-index-data-explorer.json"
```
Справочник:New-AzRoleDefinition

В примере REST API показан синтаксис JSON для создания настраиваемой роли, которая является клоном средства чтения данных индекса поиска, но с возможностью перечисления всех индексов по имени. Пошаговые инструкции по созданию пользовательских ролей см. в статье "Создание или обновление" Azure пользовательских ролей с помощью REST API.

Просмотрите список атомарных разрешений , чтобы определить нужные. В этом примере вам потребуются следующие разрешения:
```
"Microsoft.Search/operations/read",
"Microsoft.Search/searchServices/indexes/read",
"Microsoft.Search/searchServices/indexes/documents/read"
```

Создайте пользовательскую роль, отправив следующий запрос в конечную точку определения роли.

PUT https://management.azure.com/subscriptions/<subscription>/providers/Microsoft.Authorization/roleDefinitions/<role-definition-guid>?api-version=2022-04-01 HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json

{
    "properties": {
        "roleName": "Search Index Data Explorer",
        "description": "List all indexes on the service and query them.",
        "type": "CustomRole",
        "permissions": [
            {
                "actions": [
                    "Microsoft.Search/operations/read",
                    "Microsoft.Search/searchServices/indexes/read"
                ],
                "notActions": [],
                "dataActions": [
                    "Microsoft.Search/searchServices/indexes/documents/read"
                ],
                "notDataActions": []
            }
        ],
        "assignableScopes": [
            "/subscriptions/<subscription>/resourceGroups/<resource-group>"
        ]
    }
}

Справочник:Определения ролей— создание или обновление

Создание политики условного доступа

Если необходимо применить политики организации, такие как многофакторная проверка подлинности, используйте Условный доступ Microsoft Entra.

Чтобы создать политику условного доступа для Поиск с использованием ИИ Azure, выполните следующие действия.

Войдите на портал Azure.
Найдите Условный доступ Microsoft Entra.
На странице "Обзор" выберите "Создать политику".
В разделе Cloud apps or actions добавьте Поиск с использованием ИИ Azure в качестве облачного приложения в зависимости от способа настройки политики.
Обновите оставшиеся параметры политики. Например, укажите, к каким пользователям и группам применяется политика.
Сохраните политику.

Это важно

Если вашей службе поиска назначено управляемое удостоверение, эта конкретная служба поиска отображается как облачное приложение. Однако выбор конкретной службы поиска не применяет политику. Вместо этого выберите общее Поиск с использованием ИИ Azure облачное приложение, чтобы применить политики условного доступа к службе поиска.

Troubleshooting

При разработке приложений, использующих управление доступом на основе ролей для проверки подлинности, могут возникнуть некоторые распространенные проблемы:

Конфигурация по умолчанию для службы поиска — это проверка подлинности на основе ключей. Если вы не измените этот параметр на Оба или Управление доступом на основе ролей, все запросы, использующие аутентификацию на основе ролей, автоматически отклоняются, независимо от базовых разрешений.
Если запрос включает ключ API вместе с учетными данными на основе ролей, служба проходит проверку подлинности с помощью ключа. Удалите ключ API из заголовков запроса для использования проверки подлинности на основе ролей.
Если маркер авторизации поступает из управляемого удостоверения и вы недавно назначили соответствующие разрешения, может потребоваться несколько часов, чтобы назначения разрешений вступили в силу.
Если запросы с разрешениями на уровне документа не возвращают ожидаемых результатов, используйте роль Search Index Data Contributor или создайте настраиваемую роль с повышенными разрешениями (предварительная версия) для диагностики.

Следующий шаг

В этой статье объясняется, как назначать роли для операций управления и плоскости данных на Поиск с использованием ИИ Azure. Полные инструкции по добавлению доступа на основе ролей к коду приложения:

Подключите ваше приложение к Поиск с использованием ИИ Azure с помощью идентификаторов

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-07-28

Подключение к Поиск с использованием ИИ Azure с помощью ролей

Предпосылки

Встроенные роли

Описания ролей

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

Назначьте встроенные роли

Назначьте роли для администрирования сервиса

Назначение ролей для разработки

Назначьте роли для доступа только для чтения

Тестирование назначений ролей

Предоставление доступа к одному индексу

Операции с областью и индексатором для каждого индекса

Создание настраиваемой роли

Создание политики условного доступа

Troubleshooting

Следующий шаг

Обратная связь

Дополнительные ресурсы