Подключение к поиску ИИ Azure с помощью ключей
Поиск ИИ Azure предлагает проверку подлинности на основе ключей для подключений к службе поиска. Ключ API — это уникальная строка, состоящая из 52 случайных чисел и букв. В исходном коде его можно указать в качестве переменной среды или в качестве параметра приложения в проекте, а затем ссылаться на переменную в запросе. Запрос, сделанный в конечную точку службы поиска, принимается, если запрос и ключ API действительны.
Проверка подлинности на основе ключей используется по умолчанию.
Вы можете заменить его доступом на основе ролей, что устраняет необходимость жестко закодированных ключей в базе кода.
Типы ключей API
Существует два типа ключей, используемых для проверки подлинности запроса:
| Тип | Уровень разрешений | Максимум | Создание |
|---|---|---|---|
| Административный | Полный доступ (чтение и запись) для всех операций содержимого | 2 1 | При создании службы генерируются два ключа администратора, которые на портале называются первичным и вторичным. При необходимости их можно создать заново независимо друг от друга. |
| Query | Доступ только для чтения, ограниченный коллекцией документов индекса поиска | 50 | С помощью службы создается один ключ запроса. Дополнительные сведения можно создать по запросу администратором службы поиска. |
1 Наличие двух позволяет развернуть один ключ при использовании второго ключа для непрерывного доступа к службе.
Визуально нет различий между ключом администратора или ключом запроса. Оба ключа — это строки, состоящие из 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=2024-07-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=2024-07-01&api-key={{queryApiKey}}
Примечание.
В целях безопасности в URI запроса не рекомендуется передавать конфиденциальные данные, например api-key. По этой причине поиск ИИ Azure принимает ключ запроса api-key только в строке запроса. Как правило, мы рекомендуем передавать api-key в заголовке запроса.
Разрешения для просмотра ключей API или управления ими
Разрешения для просмотра ключей API и управления ими передаются с помощью назначений ролей. Просматривать и повторно создавать ключи могут участники следующих ролей:
- Владелец
- Участник
- Участник службы поиска
- Администратор и соадминистратор (классическая модель)
Следующие роли не имеют доступа к ключам API:
- Читатель
- Участник данных индекса поиска
- Читатель данных индекса поиска
Поиск существующих ключей
Можно просматривать ключи API и управлять ими на портале Azure или с помощью PowerShell, Azure CLI или REST API.
Войдите в портал Azure и найдите службу поиска.
В разделе "Параметры" выберите "Ключи", чтобы просмотреть ключи администратора и запроса.
Создание ключей запросов
Ключи запросов используются для доступа к документам только для чтения в индексе для операций, предназначенных для коллекции документов. Запросы поиска, фильтрации и предложений — это все операции, для которых используется ключ запроса. Для выполнения любой операции только для чтения, которая возвращает системные данные или определения объектов, такие как определение индекса или состояние индексатора, требуется ключ администратора.
Ограничение доступа и операций в клиентских приложениях необходимо для защиты ресурсов поиска в вашем службе. Всегда используйте ключ запроса, а не ключ администратора для любого запроса, исходящего из клиентского приложения.
Войдите в портал Azure и найдите службу поиска.
В разделе "Параметры" выберите "Ключи", чтобы просмотреть ключи API.
В разделе "Управление ключами запросов" используйте ключ запроса, уже созданный для службы, или создайте новые ключи запроса. Ключ запроса по умолчанию не называется, но другие созданные ключи запросов можно назвать для управления.
Повторное создание ключей администратора
Для каждой службы создаются два ключа администратора, чтобы можно было сменить первичный ключ при использовании дополнительного ключа для обеспечения непрерывности бизнес-процессов.
В разделе "Параметры" выберите "Ключи", а затем скопируйте вторичный ключ.
Во всех приложениях обновите параметры, добавив вторичный ключ в качестве ключа API.
Заново создайте первичный ключ.
Обновите все приложения, указав новый первичный ключ.
Если непреднамеренно повторно создать оба ключа одновременно, все клиентские запросы, использующие эти ключи, завершатся ошибкой HTTP 403 Forbidden. Однако содержимое не удаляется, и вы не заблокированы навсегда.
Вы по-прежнему можете получить доступ к службе через портал или программным способом. Функции управления работают с помощью идентификатора подписки, а не ключа API службы, и, таким образом, по-прежнему доступны, даже если ключи API не являются.
После создания новых ключей с помощью портала или уровня управления доступ восстанавливается к содержимому (индексы, индексаторы, источники данных, карты синонимов) после предоставления этих ключей по запросам.
Обеспечение безопасности ключей API
Используйте назначения ролей для ограничения доступа к ключам API.
Невозможно использовать шифрование ключей, управляемых клиентом, для шифрования ключей API. Можно шифровать только конфиденциальные данные в самой службе поиска (например, содержимое индекса или строка подключения в определениях объектов источника данных).
Перейдите к странице своей службы поиска на портале Azure.
В области навигации слева выберите Управление доступом (IAM), а затем вкладку Назначение ролей.
В фильтре ролей выберите роли, имеющие разрешение на просмотр ключей или управление ими (владелец, участник, участник службы поиска). Полученные субъекты безопасности, назначенные этим ролям, имеют ключевые разрешения в службе поиска.
В качестве меры предосторожности также проверьте вкладку "Классические администраторы", чтобы определить, имеют ли администраторы и соадминистраторы доступ.
Рекомендации
Используйте только ключи API, если раскрытие данных не является риском (например, при использовании примеров данных) и если вы работаете за брандмауэром. Воздействие ключей API — это риск как для данных, так и для несанкционированного использования службы поиска.
Всегда проверяйте код, примеры и учебные материалы перед публикацией, чтобы убедиться, что вы не оставили допустимые ключи API позади.
Для рабочих нагрузок перейдите на идентификатор Microsoft Entra и доступ на основе ролей. Или, если вы хотите продолжить использование ключей API, всегда следите за доступом к ключам API и повторно создавать ключи API на регулярной основе.