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

Статья
04/22/2024

Служба поиска ИИ Azure предлагает проверку подлинности на основе ключей, которую можно использовать для подключений к службе поиска. Ключ API — это уникальная строка, состоящая из 52 случайных чисел и букв. Запрос, сделанный в конечную точку службы поиска, принимается, если запрос и ключ API действительны.

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

Примечание.

Краткое примечание о ключевой терминологии. Ключ API — это GUID, используемый для проверки подлинности. Отдельный термин, ключ документа — это уникальная строка в индексированного содержимого, которое однозначно идентифицирует документы в индексе поиска.

Типы ключей API

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

Тип	Уровень разрешений	Максимум	Создание
Администрирование	Полный доступ (чтение и запись) для всех операций содержимого	2 ¹	При создании службы генерируются два ключа администратора, которые на портале называются первичным и вторичным. При необходимости их можно создать заново независимо друг от друга.
Query	Доступ только для чтения, область в коллекцию документов индекса поиска	50	С помощью службы создается один ключ запроса. Дополнительные сведения можно создать по запросу администратором службы поиска.

¹ Наличие двух позволяет развернуть один ключ при использовании второго ключа для непрерывного доступа к службе.

Визуально нет различий между ключом администратора или ключом запроса. Оба ключа — это строки, состоящие из 52 случайно созданных альфа-числовых символов. Если вы не знаете, какой тип ключа указан в приложении, вы можете проверить значения ключа на портале.

Использование ключей API для подключений

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

Администратор ключи используются для создания, изменения или удаления объектов. Администратор ключи также используются для определения объектов GET и системной информации.

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

Как ключи API используются в вызовах REST:

Задайте ключ администратора в заголовке запроса. Невозможно передать ключи администратора в URI или в тексте запроса. Администратор ключи используются для операции create-read-update-delete и для запросов, выданных самой службе поиска, например Индексы LIST или GET Service Statistics.

Ниже приведен пример использования ключа API администратора в запросе на создание индекса:

### Create an index
POST {{baseUrl}}/indexes?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{adminApiKey}}

    {
        "name": "my-new-index",  
        "fields": [
            {"name": "docId", "type": "Edm.String", "key": true, "filterable": true},
            {"name": "Name", "type": "Edm.String", "searchable": true }
         ]
   }

Задайте ключ запроса в заголовке запроса для POST или URI для GET. Ключи запросов используются для операций, предназначенных для коллекции: поиск документов, автозаполнения, предложения или GET Document.index/docs

Ниже приведен пример использования ключа API запроса для запроса "Документы поиска" (GET):

### Query an index
GET /indexes/my-new-index/docs?search=*&api-version=2023-11-01&api-key={{queryApiKey}}

Примечание.

В целях безопасности в URI запроса не рекомендуется передавать конфиденциальные данные, например api-key. По этой причине поиск ИИ Azure принимает ключ запроса api-key только в строке запроса. Как правило, мы рекомендуем передавать api-key в заголовке запроса.

Использование ключей API в PowerShell:

Задайте ключи API в заголовке запроса с помощью следующего синтаксиса:

$headers = @{
'api-key' = '<YOUR-ADMIN-OR-QUERY-API-KEY>'
'Content-Type' = 'application/json' 
'Accept' = 'application/json' }

Пример скрипта, показывающий использование ключа API для различных операций, см. в кратком руководстве. Создание индекса поиска ИИ Azure в PowerShell с помощью REST API.

Разрешения для просмотра ключей API или управления ими

Разрешения для просмотра ключей API и управления ими передаются с помощью назначений ролей. Просматривать и повторно создавать ключи могут участники следующих ролей:

Владелец
Участник
Участник службы поиска
Администратор istrator и соадминистратор (классическая модель)

Следующие роли не имеют доступа к ключам API:

Читатель
Участник данных индекса поиска
Читатель данных индекса поиска

Поиск существующих ключей

Можно просматривать ключи API и управлять ими на портале Azure или с помощью PowerShell, Azure CLI или REST API.

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

Az.Search Установите модуль:
```
Install-Module Az.Search
```

Возврат ключей администратора:

Get-AzSearchAdminKeyPair -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>

Возвращать ключи запроса:

Get-AzSearchQueryKey -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>

Используйте следующие команды для возврата ключей API администратора и запросов соответственно:

az search admin-key show --resource-group <myresourcegroup> --service-name <myservice>

az search query-key list --resource-group <myresourcegroup> --service-name <myservice>

Используйте ключи списка Администратор или ключи запросов списка в REST API управления для возврата ключей API.

Для возврата или обновления ключей API необходимо иметь допустимое назначение роли . Сведения о требованиях к роли для удовлетворения требований к роли с помощью REST API см. в статье "Управление служба ИИ Azure с помощью REST API".

POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers//Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2023-11-01

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

Ключи запросов используются для доступа к документам только для чтения в индексе для операций, предназначенных для коллекции документов. Запросы поиска, фильтрации и предложений — это все операции, для которых используется ключ запроса. Для выполнения любой операции только для чтения, которая возвращает системные данные или определения объектов, такие как определение индекса или состояние индексатора, требуется ключ администратора.

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

Войдите в портал Azure и найдите службу поиска.
В разделе Параметры выберите ключи для просмотра ключей API.
В разделе "Управление ключами запросов" используйте ключ запроса, уже созданный для службы, или создайте новые ключи запроса. Ключ запроса по умолчанию не называется, но другие созданные ключи запросов можно назвать для управления.

Используйте ключи запросов в REST API управления.

Необходимо иметь допустимое назначение роли для создания ключей API или управления ими. Сведения о требованиях к роли для удовлетворения требований к роли с помощью REST API см. в статье "Управление служба ИИ Azure с помощью REST API".

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/createQueryKey/{name}?api-version=2023-11-01

Повторное создание ключей администратора

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

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

Если непреднамеренно повторно создать оба ключа одновременно, все клиентские запросы, использующие эти ключи, завершатся ошибкой HTTP 403 Forbidden. Однако содержимое не удаляется, и вы не заблокированы навсегда.

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

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

Обеспечение безопасности ключей API

Используйте назначения ролей для ограничения доступа к ключам API.

Невозможно использовать шифрование ключей, управляемых клиентом, для шифрования ключей API. Можно шифровать только конфиденциальные данные в самой службе поиска (например, содержимое индекса или строка подключения в определениях объектов источника данных).

Перейдите к странице своей службы поиска на портале Azure.
В области навигации слева выберите Управление доступом (IAM), а затем вкладку Назначение ролей.
В фильтре ролей выберите роли, имеющие разрешение на просмотр ключей или управление ими (владелец, участник, участник службы поиска). Полученные субъекты безопасности, назначенные этим ролям, имеют ключевые разрешения в службе поиска.
В качестве меры предосторожности также проверка вкладку классических администраторов, чтобы определить, имеют ли администраторы и соадминистратора доступ.