在 PowerApps 中生成 Web API 自定义连接器Build a custom connector for a Web API in PowerApps

本教程介绍了如何开始生成 ASP.NET Web API,在 Azure Web 应用上托管它,启用 Azure Active Directory 身份验证,然后在 PowerApps 中注册 ASP.NET Web API。This tutorial shows you how to start bulding an ASP.NET Web API, host it on Azure Web Apps, enable Azure Active Directory authentication, and then register the ASP.NET Web API in PowerApps. 注册 API 后,便可以连接它,并在应用中调用它。After the API is registered, you can connect to it and call it from your app.

必备组件Prerequisites

创建 ASP.NET Web API 并将其部署到 AzureCreate an ASP.NET Web API and deploy it to Azure

  1. 在 Visual Studio 中,依次单击“文件” > “新建项目”,创建新的 C# ASP.NET Web 应用。In Visual Studio, click File > New Project to create a new C# ASP.NET web application.

    新建 Web 应用

  2. 选择“Web API”模板。Select the Web API template. 保持选中“在云中托管”不变。Leave Host in the cloud checked. 单击“更改身份验证”。Click Change Authentication.

    新建 Web 项目的模板

  3. 选中“无身份验证”,然后单击“确定”。Select No Authentication, and then click OK.

    无身份验证

  4. 单击“新建 ASP.NET 项目”对话框中的“确定”。Click OK on the New ASP.NET Project dialog. 此时,“配置 Microsoft Azure Web 应用”对话框显示。The Configure Microsoft Azure Web App dialog appears.

    配置 Microsoft Azure Web 应用]]

    选择你的 Azure 帐户,键入 Web 应用名称(或保留默认名称),然后选择你的 Azure 订阅Select your Azure account, type a Web App name (or leave the default), and select your Azure Subscription. 选择或创建应用服务计划(订阅中的 Web 应用集合)。Select or create an App Service plan (a collection of Web Apps within your subscription). 选择或创建一个资源组(订阅中的 Azure 资源分组)。Select or create a Resource group (a grouping of Azure resources within your subscription). 选择应在其中部署 Web 应用的区域。Select the region where the Web App should be deployed. 如果 Web API 需要,请选择或创建一个 Azure 数据库服务器If required for your Web API, select or create an Azure Database server. 最后,单击“确定”。Finally, click OK.

  5. 生成 Web API。Build out your Web API.

    注意:如果尚无可用的 Web API 代码,请尝试学习教程 ASP.NET Web API 2 (C#) 入门Note: If you don't already have code ready for a Web API, try the tutorial Getting Started with ASP.NET Web API 2 (C#).

  6. 若要连接 Web API 和 PowerApps,我们需要使用描述 API 操作的 OpenAPI 文件。To connect our Web API to PowerApps, we'll need an OpenAPI file that describes its operations. 可以使用联机编辑器编写你自己的 OpenAPI 文件,但在本教程中,将使用名为 Swashbuckle 的开放源代码工具。You could write an OpenAPI of your own using the online editor, but for this tutorial, you'll use an open-source tool named Swashbuckle. 依次单击“工具” > “NuGet 包管理器” > “包管理器控制台”,然后在包管理器控制台中键入命令“Install-Package Swashbuckle”,从而在 Visual Studio 项目中安装 Swashbuckle Nuget 包。Install the Swashbuckle Nuget package in your Visual Studio project by clicking Tools > NuGet Package Manager > Package Manager Console, and then, in the Package Manager Console, type the command Install-Package Swashbuckle.

    Install-Package Swashbuckle

    提示:现在,在安装 Swashbuckle 后运行 Web API 应用时,可以在 URL http://<your root URL>/swagger/docs/v1 处生成 OpenAPI 文件。Tip: When you run your Web API application after installing Swashbuckle, an OpenAPI file will now be generated at the URL http://<your root URL>/swagger/docs/v1. http://<your root URL>/swagger 处还生成了一个用户界面。A generated user interface is also available at http://<your root URL>/swagger.

  7. 当 Web API 就绪时,将其发布到 Azure。When your Web API is ready, publish it to Azure. 若要从 Visual Studio 发布,请右键单击解决方案资源管理器中的 Web 项目,单击“发布...”,然后按“发布”对话框中的提示操作。To publish from Visual Studio, right-click on the web project in Solution Explorer, click Publish..., and then follow the prompts in the Publish dialog.
  8. 转到 https://<azure-webapp-url>/swagger/docs/v1 检索 OpenAPI JSON。Retrieve the OpenAPI JSON by navigating to https://<azure-webapp-url>/swagger/docs/v1. 将内容另存为 JSON 文件。Save the content as a JSON file. 可能需要将文本复制并粘贴到空的文本文件中,具体视浏览器而定。Depending on your browser, you may need to copy and paste the text into an empty text file.

    重要说明:包含重复操作 ID 的 OpenAPI 文档无效。Important: An OpenAPI document with duplicate operation IDs is invalid. 如果使用的是示例 C# 模板,操作 ID Values_Get 就会重复两次。If you are using the sample C# template, the operation ID Values_Get is repeated twice. 若要修复此问题,可以将一个实例更改为 Value_Get,然后重新发布。You can correct this by changing one instance to Value_Get and re-publishing. 也可以从本教程中下载示例 OpenAPI 文件You can also download a sample OpenAPI file from this tutorial. 请务必先删除注释(以 // 开头),然后再使用。Be sure to remove the comments (starting with //) before using it.

设置 Azure Active Directory 身份验证Set up Azure Active Directory authentication

现在,将在 Azure 中创建两个 Azure Active Directory (AAD) 应用。You will now create two Azure Active Directory (AAD) applications in Azure. 有关如何执行此操作的示例,请参阅 Azure 资源管理器教程For an example of how to do this, see the Azure Resource Manager tutorial.

重要说明:两个应用必须位于同一目录中。Important Both apps must be in the same directory.

第一个 AAD 应用:保护 Web API 安全First AAD application: Securing the Web API

第一个 AAD 应用可用于保护 Web API 安全。The first AAD application is used to secure the Web API. 将此应用命名为“webAPI”。Name it webAPI. 按照上面链接的教程步骤(即“在 Azure Active Directory 中启用身份验证”部分下的步骤)操作,使用的值如下:Follow the above linked tutorial steps (just the section titled "Enable authentication in Azure Active Directory") with the following values:

  • 登录 URL:https://login.windows.netSign-on URL: https://login.windows.net
  • 答复 URL:https://<your-root-url>/.auth/login/aad/callbackReply URL: https://<your-root-url>/.auth/login/aad/callback
  • 无需使用客户端密钥。There is no need for a client key.
  • 无需委托任何权限。There is no need to delegate any permissions.
  • 重要说明:请记下应用 ID。Important: Note the application ID. 稍后将需要使用。You will need it later.

第二个 AAD 应用:保护自定义连接器并获取委托访问权限Second AAD application: Securing the custom connector and delegated access

第二个 AAD 应用可用于保护注册的自定义连接器,并获取对第一个应用保护的 Web API 的委托访问权限。The second AAD application is used to secure the custom connector registration and acquire delegated access to the Web API protected by the first application. 将此应用命名为“webAPI-customAPI”。Name this one webAPI-customAPI .

  • 登录 URL:https://login.windows.netSign-on URL: https://login.windows.net
  • 答复 URL:https://msmanaged-na.consent.azure-apim.net/redirectReply URL: https://msmanaged-na.consent.azure-apim.net/redirect
  • 添加对 Web API 的委托访问权限。Add permissions to have delegated access to Web API.
  • 由于稍后将需要使用此应用的应用 ID,因此请记下。You need the application ID of this application later as well, so note it.
  • 生成客户端密钥,并存储在安全位置。Generate a client key and store is somewhere safe. 稍后将需要使用此密钥。We need this key later.

向 Azure Web 应用添加身份验证Add authentication to your Azure Web App

  1. 登录 Azure 门户,然后找到在第一部分中部署的 Web 应用。Sign in to the Azure portal and then find your Web App that you deployed in the first section.
  2. 单击“设置”,然后选择“身份验证/授权”。Click Settings, and then select Authentication / Authorization.
  3. 启用“应用服务身份验证”,然后选择“Azure Active Directory”。Turn on App Service Authentication and then select Azure Active Directory. 选择下一个边栏选项卡上的“快速”。On the next blade, select Express.
  4. 单击“选择现有 AD 应用”,然后选择之前创建的“webAPI”AAD 应用。Click Select Existing AD App, and select the webAPI AAD application you created earlier.

现在应能够使用 AAD 对 Web 应用进行身份验证。You should now be able to use AAD to authenticate your web application.

将自定义连接器添加到 PowerAppsAdd the custom connector to PowerApps

  1. 将 OpenAPI 文件修改为添加 securityDefintions 对象和用于 Web 应用的 AAD 身份验证。Modify your OpenAPI file to add the securityDefintions object and AAD authentication used for the Web App. 包含“host”属性的 OpenAPI 文件部分应如下所示:The section of your OpenAPI file with the host property should look like this:
// File header should be above here...

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

// The rest of the OpenAPI document follows...
  1. 转到 PowerApps,然后添加自定义连接器,如在 PowerApps 中注册并使用自定义连接器中所述。Browse to PowerApps, and add a custom connector as described in Register and use custom connectors in PowerApps.
  2. 上载 OpenAPI 文件后,向导便会立即自动检测你是否在对 Web API 使用 AAD 身份验证。Once you have uploaded your OpenAPI file, the wizard auto-detects that you are using AAD authentication for your Web API.
  3. 为自定义连接器配置 AAD 身份验证。Configure the AAD authentication for the custom connector.

    • 客户端 ID:webAPI-CustomAPI 的客户端 IDClient ID: Client ID of webAPI-CustomAPI
    • 密码:webAPI-CustomAPI 的客户端密钥Secret: Client key of webAPI-CustomAPI
    • 登录 URL:https://login.windows.netLogin URL: https://login.windows.net
    • 资源 URI:webAPI 的客户端 IDResourceUri: Client ID of webAPI
  4. 单击“创建”,建立与自定义连接器的连接。Click Create and creating a connection to the custom connector.

后续步骤Next Steps

了解 Azure 资源管理器自定义连接器教程Walk through the Azure Resource Manager custom connector tutorial.