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

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

• Зарегистрируйте и вызовите API из Power Apps или Azure Logic Apps.
• Интеграция с Microsoft Copilot Studio.

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

• Visual Studio 2013 или более поздней версии. В этом руководстве используется Visual Studio 2015.

• Код для вашего веб-API. Если у вас ничего нет, попробуйте это руководство: Getting Started with веб-API ASP.NET 2 (C#).

• Подписка Azure. Если у вас нет подписки, вы можете начать с учетной записи free Azure. В противном случае оформите подписку с оплатой по мере использования.

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

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

1. Откройте Visual Studio и выберите File>New Project.

   1. Разверните Installed, затем перейдите к Templates>Visual C#>Web, и выберите ASP.NET Веб-приложение.

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

   

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

   

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

   

4. При повторном появлении окна New ASP.NET веб-приложение, выберите OK.

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

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

   

   Настройки	Предлагаемое значение	Описание
   Ваша Azure рабочая или учебная учетная запись или личная учетная запись Майкрософт	ваша-учетная-запись-пользователя	Выберите свою учетную запись пользователя.
   Имя веб-приложения	настраиваемое-имя-приложения-веб-API или имя по умолчанию	Введите имя для вашего приложения Web API, которое используется в URL-адресе вашего приложения, например: http://имя-приложения-веб-API.
   Subscription	Azure-subscription-name	Выберите Azure подписку, которую вы хотите использовать.
   Группа ресурсов	Azure-resource-group-name	Выберите существующую Azure группу ресурсов или ( если вы еще не сделали) создайте группу ресурсов. Примечание: группа ресурсов Azure организует ресурсы Azure в вашей подписке Azure.
   План службы приложений	имя-плана-службы-приложений	Выберите существующий план службы приложений или, — если вы еще этого не сделали, — создайте план.

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

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

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

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

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 выберите Tools>NuGet диспетчер пакетов>диспетчер пакетов Console.

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

      Install-Package 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, щелкните правой кнопкой мыши веб-проект в Обозреватель решений, выберите Publish и следуйте инструкциям.

   Внимание!

   Если документ 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. Включите проверку подлинности App Service Authentication и выберите Azure Active Directory. В следующей колонке выберите Экспресс.

4. Выберите Select Existing AD App, а затем выберите созданное ранее приложение webAPI Microsoft Entra ID.

Теперь вы сможете использовать 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...

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

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

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

• Идентификатор клиента: идентификатор клиента для webAPI-CustomAPI
• Секрет клиента: ключ клиента webAPI-CustomAPI
• URL-адрес входа: https://login.windows.net
• ResourceUri: идентификатор клиента для webAPI

5. Выберите Создать, чтобы создать подключение к пользовательскому соединителю.

Дополнительные сведения

Узнайте больше о проверке подлинности Microsoft Entra ID

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

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