Создание пользовательского соединителя для веб-API

  • Статья

В этом руководстве показано, как начать создавать веб-API ASP.NET, разместить его в веб-приложениях Azure (это функция Службы приложений Azure), включить аутентификацию Microsoft Entra ID, а затем зарегистрировать веб-API в ASP.NET в Power Automate, Зарегистрировав API, вы сможете подключиться к нему для вызова из потока. Можно также зарегистрировать и вызывать API из Power Apps или Azure Logic Apps.

Предварительные условия

Создание и развертывание веб-приложения ASP.NET для Azure

Для этого руководства создайте веб-приложение Visual C# ASP.NET.

  1. Откройте Visual Studio, затем выберите Файл > Создать проект.

    1. Разверните элемент Установленные, перейдите в меню Шаблоны > Visual C# > Веб и выберите Веб-приложение ASP.NET.

    2. Введите имя проекта, местоположение и название решения для своего приложения, затем выберите ОК.

    Снимок экрана, показывающий новое веб-приложение Visual C# ASP.NET.

  2. В поле Новое веб-приложение ASP.NET выберите шаблон Веб-API, убедитесь, что установлен флажок Разместить в облаке, затем выберите Изменить аутентификацию.

    Снимок экрана, показывающий диалоговое окно «Новое веб-приложение ASP.NET».

  3. Выберите пункт Без проверки подлинности, затем выберите ОК. Вы можете настроить аутентификацию позже.

    Выберите «Без аутентификации».

  4. Когда снова появится поле Создать веб приложение ASP.NET, выберите ОК.

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

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

    Создайте службу приложений.

    Параметр Предлагаемое значение Описание
    Ваша рабочая или школьная учетная запись Azure или ваша личная учетная запись Microsoft ваша-учетная-запись-пользователя Выберите свою учетную запись пользователя.
    Имя веб-приложения настраиваемое-имя-приложения-веб-API или имя по умолчанию Введите имя для вашего приложения Web API, которое используется в URL-адресе вашего приложения, например: http://имя-приложения-веб-API.
    Подписка имя-подписки-Azure Выберите подписку Azure, которую нужно использовать.
    Группа ресурсов имя-группы-ресурсов-Azure Выберите существующую группу ресурсов Azure или, — если вы еще этого не сделали, — создайте группу ресурсов.

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

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

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

    Чтобы настроить любые другие ресурсы, необходимые для вашего приложения, выберите Обзор дополнительных служб Azure.

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

  6. После того как Visual Studio развернет ваш проект, создайте код для вашего приложения.

Создание файла OpenAPI (Swagger), описывающего ваш веб-API

Чтобы подключить приложение веб-API к Power Automate, Power Apps или Logic Apps, вам потребуется файл OpenAPI (прежнее название — Swagger) с описанием операций этого API. Вы можете написать свое собственное определение OpenAPI для вашего API с помощью Онлайн-редактора Swagger, но в этом руководстве используется инструмент с открытым исходным кодом под названием Swashbuckle.

  1. Если вы этого еще не сделали, установите пакет Swashbuckle NuGet в свой проект Visual Studio:

    1. В Visual Studio выберите Сервис > Диспетчер пакетов NuGet > Консоль диспетчера пакетов.

    2. В окне Консоль диспетчера пакетов перейдите в каталог проекта вашего приложения, если вы еще не находитесь в нем (запустите Set-Location "project-path") и выполните этот командлет PowerShell:

      Install-Package Swashbuckle

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

    Совет

    Если вы запустите свое приложение после установки Swashbuckle, Swashbuckle создаст файл OpenAPI по этому URL-адресу:

      http://{your-web-api-app-root-URL}/swagger/docs/v1

    Swashbuckle также генерирует пользовательский интерфейс по этому URL-адресу:

      http://{your-web-api-app-root-URL}/swagger

  2. Когда будете готовы, опубликуйте приложение веб-API в Azure. Чтобы опубликовать из Visual Studio, щелкните правой кнопкой мыши свой веб-проект в обозревателе решений, выберите Опубликовать и следуйте инструкциям.

    Важно!

    Если документ OpenAPI содержит повторяющиеся идентификаторы операций, он будет недействительным. Образец шаблона C# повторяет идентификатор операции, Values_Get.

    Если вы использовали пример шаблона C#, вы можете решить эту проблему, изменив один экземпляр идентификатора операции на Value_Get и выполнив повторную публикацию.

  3. Получите документ OpenAPI, перейдя в это место:

    http://{your-web-api-app-root-URL}/swagger/docs/v1

    Вы также можете скачать пример документа OpenAPI из этого руководства. Убедитесь, что вы удалили комментарии, которые начинаются с //, прежде чем использовать документ.

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

Настройка проверки подлинности Microsoft Entra ID

Теперь вам нужно создать два приложения Microsoft Entra ID в Azure. Подробнее см. в статье Интеграция приложений с Microsoft Entra ID.

Важно!

Оба приложения должны находиться в одном каталоге.

Первое приложение Microsoft Entra ID: защита веб-API

Первое приложение Microsoft Entra ID используется для защиты веб-API. Назовите его webAPI. Вы можете включить аутентификацию Microsoft Entra ID в своем веб-API, выполнив эти действия со следующими значениями:

  • URL-адрес входа: https://login.windows.net
  • URL-адрес ответа: https://<your-root-url>/.auth/login/aad/callback
  • Вам не нужен ключ клиента.
  • Вам не требуется делегировать какие-либо полномочия.
  • Скопируйте идентификатор приложения, потому что он понадобится вам позже.

Второе приложение Microsoft Entra ID: защита пользовательского соединителя и получение делегированного доступа

Второе приложение Microsoft Entra ID используется для защиты регистрации пользовательского соединителя и получения делегированного доступа к веб-API, защищенному первым приложением. Назовите это приложение webAPI-customAPI.

  • URL-адрес входа: https://login.windows.net
  • URL-адрес ответа: https://msmanaged-na.consent.azure-apim.net/redirect
  • Добавьте разрешения, чтобы делегировать доступ к веб-API.
  • Скопируйте идентификатор приложения, потому что он понадобится вам позже.
  • Сгенерируйте клиентский ключ и скопируйте его, потому что он понадобится вам позже.

Добавление проверки подлинности для веб-приложения Azure

  1. Войдите на портал Azure и найдите веб-приложение, развернутое в первом разделе.

  2. Выберите Параметры, а затем выберите Проверка подлинности/авторизация.

  3. Включите Аутентификация службы приложений, затем выберите Azure Active Directory. В следующей колонке выберите Экспресс.

  4. Выберите Выбрать существующее приложение AD и выберите ранее созданное приложение Microsoft Entra ID webAPI.

Теперь вы сможете использовать Microsoft Entra ID для проверки подлинности веб-приложения.

Добавление настраиваемого соединителя в Power Automate

  1. Внесите изменения в OpenAPI, чтобы добавить объект securityDefintions и аутентификацию Microsoft Entra ID, используемую для веб-приложения. Раздел OpenAPI со свойством host должен выглядеть так:
// File header should be above here...

"host": "<your-root-url>",
"schemes": [
    "https"      //Make sure this is https!
],
"securityDefinitions": {
    "Microsoft Entra ID": {
        "type": "oauth2",
        "flow": "accessCode",
        "authorizationUrl": "https://login.windows.net/common/oauth2/authorize",
        "tokenUrl" : "https://login.windows.net/common/oauth2/token",
        "scopes": {}
    }
},

// The rest of the OpenAPI follows...

  1. Перейдите в службу Power Automate и добавьте настраиваемый соединитель, как описано в статье Использование настраиваемого соединителя в Power Automate.

  2. После отправки OpenAPI в систему мастер автоматически определит, что для веб-API используется аутентификация Microsoft Entra ID.

  3. Настройте аутентификацию Microsoft Entra ID для пользовательского соединителя.

  • Идентификатор клиента: идентификатор клиента для webAPI-CustomAPI
  • Секрет: клиентский ключ для webAPI-CustomAPI
  • URL-адрес входа: https://login.windows.net
  • ResourceUri: идентификатор клиента для webAPI
  1. Выберите Создать, чтобы создать подключение к настраиваемому соединителю.

См. также

Подобнее об аутентификации Microsoft Entra ID

Предоставление отзывов

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