Использование службы агента Azure AI Foundry с указанными средствами OpenAPI

2025-06-30

Теперь агент ИИ Azure можно подключить к внешнему API с помощью указанного средства OpenAPI 3.0, что позволяет масштабировать взаимодействие с различными приложениями. Включите пользовательские средства для проверки подлинности доступа и подключений с помощью управляемых удостоверений (Идентификатор Microsoft Entra) для дополнительной безопасности, что делает его идеальным для интеграции с существующей инфраструктурой или веб-службами.

Указанное средство OpenAPI улучшает интерфейс вызова функций, предоставляя стандартизированные, автоматизированные и масштабируемые интеграции API, которые повышают возможности и эффективность агента. Спецификации OpenAPI предоставляют формальный стандарт для описания API HTTP. Это позволяет людям понять, как работает API, как работает последовательность API, создавать клиентский код, создавать тесты, применять стандарты проектирования и многое другое. В настоящее время мы поддерживаем три типа проверки подлинности с помощью указанных средств OpenAPI 3.0: anonymous, API key, managed identity.

Поддержка использования

Поддержка платформы Azure AI Foundry	Python SDK	Пакет SDK для C#	REST API	Базовая настройка агента	Настройка стандартного агента
✔️	✔️	✔️	✔️	✔️	✔️

Предпосылки

Убедитесь, что вы выполнили предварительные требования и инструкции по настройке в кратком руководстве.
Проверьте спецификацию OpenAPI для следующих требований:
1. Хотя это и не требуется спецификацией OpenAPI, operationId необходимо для использования каждой функции с инструментом OpenAPI.
2. operationId должен содержать только буквы и -_. Его можно изменить в соответствии с требованием. Мы рекомендуем использовать описательное имя, чтобы помочь моделям эффективно решить, какую функцию следует использовать.

Проверка подлинности с помощью ключа API

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

Обновите схемы безопасности спецификаций OpenAPI. Он содержит securitySchemes раздел и одну схему типа apiKey. Рассмотрим пример.
```
 "securitySchemes": {
     "apiKeyHeader": {
             "type": "apiKey",
             "name": "x-api-key",
             "in": "header"
         }
 }
```
Обычно нужно обновить только поле name, которое соответствует имени key в подключении. Если схемы безопасности включают несколько схем, рекомендуется сохранить только одну из них.
Обновите спецификацию OpenAPI, чтобы включить security раздел:
```
"security": [
     {  
     "apiKeyHeader": []  
     }  
 ]
```
Удалите любой параметр в спецификации OpenAPI, требующей ключа API, так как ключ API будет храниться и передаваться через подключение, как описано далее в этой статье.
custom keys Создайте подключение для хранения ключа API.
1. Перейдите на портал Azure AI Foundry и выберите проект ИИ. Выберите подключенные ресурсы.
2. Выберите +создать подключение на странице параметров.
  
  Замечание
  
  При повторном создании ключа API на более позднюю дату необходимо обновить подключение с новым ключом.
3. Выберите настраиваемые ключи в других типах ресурсов.
4. Введите следующие сведения
  - ключ: name поле схемы безопасности. В этом примере должно быть x-api-key
```
       "securitySchemes": {
          "apiKeyHeader": {
                    "type": "apiKey",
                    "name": "x-api-key",
                    "in": "header"
                }
        }
```
  - значение: YOUR_API_KEY
  - Имя подключения: YOUR_CONNECTION_NAME (это имя подключения будет использоваться в примере кода ниже.)
  - Доступ: вы можете выбрать только этот проект или предоставить общий доступ ко всем проектам. Просто убедитесь, что в приведенном ниже примере кода проект, введенный строка подключения для доступа к этому подключению.
После создания подключения его можно использовать с помощью пакета SDK или REST API. Используйте вкладки в верхней части этой статьи, чтобы просмотреть примеры кода.

Аутентификация с помощью управляемой идентичности (Microsoft Entra ID)

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

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

Включите службу ИИ Azure, так как у вашего агента уже включена system assigned managed identity.
Создайте ресурс службы, к которой вы хотите подключиться через спецификацию OpenAPI.
Назначьте правильный доступ к ресурсу.
1. Щелкните "Управление доступом " для ресурса
2. Нажмите кнопку "Добавить " и добавьте назначение ролей в верхней части экрана.
3. Выберите нужное назначение роли, как правило, потребуется по крайней мере роль ЧИТАТЕЛЯ . Затем нажмите Далее.
4. Выберите управляемое удостоверение, затем нажмите выбрать участников.
5. В раскрывающемся меню управляемого удостоверения найдите службы ИИ Azure и выберите службу ИИ вашего агента.
6. Нажмите кнопку Готово.
После завершения установки можно продолжить работу с помощью средства с помощью портала Azure AI Foundry, пакета SDK или REST API. Используйте вкладки в верхней части этой статьи, чтобы просмотреть примеры кода.

Поделиться через

Использование службы агента Azure AI Foundry с указанными средствами OpenAPI

Поддержка использования

Предпосылки

Проверка подлинности с помощью ключа API

Аутентификация с помощью управляемой идентичности (Microsoft Entra ID)

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

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