在 PowerApps 中注册和使用自定义连接器Register and use custom connectors in PowerApps

借助 PowerApps,无需使用任何传统应用代码,即可生成功能齐全的应用。PowerApps enables you to build full-featured apps with no traditional application code. 但在某些情况下,需要扩展 PowerApps 功能,而 Web 服务则自然派上用场了。But in some cases you need to extend PowerApps capabilites, and web services are a natual fit for this. 应用可以连接服务、执行操作并传回数据。Your app can connect to a service, perform operations, and get data back. 若有要使用 PowerApps 进行连接的 Web 服务,请将此服务注册为自定义连接器。When you have a web service you want to connect to with PowerApps, you register the service as a custom connector. 这样一来,PowerApps 可以了解 Web API 的特性,包括需要执行的身份验证、支持的操作以及每项操作的参数和输出。This process enables PowerApps to understand the characteristics of your web API, including the authentication that it requires, the operations that it supports, and the parameters and outputs for each of those operations.

本主题将逐步介绍如何注册和使用自定义连接器,我们将以 Azure 认知服务文本分析 API 为例。In this topic, we'll look at the steps required to register and use a custom connector, and we'll use the Azure Cognitive Services Text Analytics API as an example. 此 API 可以标识向其传递的文本的语言、情绪和关键短语。This API identifies the language, sentiment, and key phrases in text that you pass to it. 下图展示了此服务、我们通过此服务创建的自定义连接器以及调用 API 的应用之间的交互。The following image shows the interaction between the service, the custom connector we create from it, and the app that calls the API.

API、自定义连接器和应用

必备组件Prerequisites

  • PowerApps 帐户A PowerApps account.
  • JSON 格式的 OpenAPI 文件、OpenAPI 定义 URL 或 API 的 Postman 集合。An OpenAPI file in JSON format, a URL to an OpenAPI definition, or a Postman Collection for your API. 如果你没有其中任一内容,我们将为你提供指南。If you don't have any of these, we'll provide guidance for you.
  • 用作自定义连接器图标的图像(可选)。An image to use as an icon for your custom connector (optional).

自定义连接器流程步骤Steps in the custom connector process

自定义连接器流程有多项步骤,我们将在下面进行简要介绍。The custom connector process has several steps, which we describe briefly below. 本文假设你已有可对其进行某种验证的访问的 RESTful API,因此我们将在本文的剩余部分中重点介绍第 3-6 步。This article assumes you already have a RESTful API with some type of authenticated access, so we'll focus on steps 3-6 in the rest of the article. 有关第 1-2 步的示例,请参阅创建适用于 PowerApps 的自定义 Web APIFor an example of steps 1 and 2, see Create a custom Web API for PowerApps.

  1. 用选择的语言和平台生成 RESTful APIBuild a RESTful API in the language and platform of your choice. 对于 Microsoft 技术,建议使用以下技术之一。For Microsoft technologies, we recommend one of the following.

    • Azure FunctionsAzure Functions
    • Azure Web 应用Azure Web Apps
    • Azure API 应用Azure API Apps
  2. 使用以下身份验证机制之一保护 APISecure your API using one of the following authentication mechanisms. 可以允许对 API 进行未经身份验证的访问,但不建议这样做。You can allow unauthenticated access to your APIs, but we don't recommend it.

  3. 采用两种行业标准方式之一描述 API,以便 PowerApps 可以连接它。Describe your API in one of two industry-standard ways, so that PowerApps can connect to it.

    • OpenAPI 文件(亦称为“Swagger 文件”)An OpenAPI file (also known as a Swagger file)
    • Postman 集合A Postman Collection

      也可以在第 4 步的注册过程中生成 OpenAPI 文件。You can also build an OpenAPI file in step 4 as part of the registration process.

  4. 使用 PowerApps 中的向导注册自定义连接器,可以在向导中指定 API 说明、安全详细信息和其他信息。Register your custom connector using a wizard in PowerApps, where you specify an API description, security details, and other information.
  5. 在应用中使用自定义连接器Use your custom connector in an app. 在应用中创建与 API 的连接,并调用 API 提供的任何操作,就像在 PowerApps 中调用本机函数一样。Create a connection to the API in your app, and call any operations that the API provides, just like you call native functions in PowerApps.
  6. 共享自定义连接器,就像在 PowerApps 中共享其他数据连接一样。Share your custom connector like you do other data connections in PowerApps. 虽然此为可选步骤,但通常有必要跨多个应用创建者共享自定义连接器。This step is optional, but it often makes sense to share custom connectors across multiple app creators.

描述 APIDescribe your API

假设已有可对其进行某种验证的访问的 API,所以需要使用一种方法来描述 API,以便 PowerApps 可以连接它。Assuming you have an API with some type of authenticated access, you need a way to describe the API so that PowerApps can connect to it. 为此,可以从任意 REST API 终结点创建 OpenAPI 文件或 Postman 集合,具体包括:To do this, you create an OpenAPI file or a Postman Collection – which you can do from any REST API endpoint, including:

  • 公用 API。Publicly available APIs. 部分示例包括 SpotifyUberSlackRackspace,等等。Some examples include Spotify, Uber, Slack, Rackspace, and more.
  • 创建并部署到任意云托管提供程序(包括Azure、Amazon Web Services (AWS)、Heroku、Google Cloud 等)的 API。An API that you create and deploy to any cloud hosting provider, including Azure, Amazon Web Services (AWS), Heroku, Google Cloud, and more.
  • 在网络上部署的自定义业务线 API,前提是在公共 Internet 上公开该 API。A custom line-of-business API deployed on your network as long as the API is exposed on the public internet.

虽然 OpenAPI 文件和 Postman 集合使用的格式不同,但两者都是与语言无关的机器可读文档,其中描述了 API 操作和参数:OpenAPI files and Postman Collections use different formats, but both are language-agnostic machine-readable documents that describe your API's operations and parameters:

  • 可以使用各种工具生成这些文档,具体视生成 API 时使用的语言和平台而定。You can generate these documents using a variety of tools depending on the language and platform that your API is built on. 有关 OpenAPI 文件的示例,请参阅文本分析 API 文档See the Text Analytics API documentation for an example of an OpenAPI file.
  • 如果还没有为 API 提供 OpenAPI 文件,也不想创建此文件,仍可以使用 Postman 集合轻松创建自定义连接器。If you don't already have an OpenAPI file for your API and don't want to create one, you can still easily create a custom connector by using a Postman Collection. 有关详细信息,请参阅创建 Postman 集合See Create a Postman Collection for more information.
  • 由于 PowerApps 最终会在幕后使用 OpenAPI,因此 Postman 集合会被分析并转换成 OpenAPI 定义文件。PowerApps ultimately uses OpenAPI behind the scenes, so a Postman Collection is parsed and translated into an OpenAPI definition file.

注意:文件必须小于 1 MB。Note: Your file size must be less than 1MB.

OpenAPI 和 Postman 入门Getting started with OpenAPI and Postman

注册自定义连接器Register your custom connector

现在,使用 OpenAPI 文件或 Postman 集合在 PowerApps 中注册自定义连接器。You will now use the OpenAPI file or Postman Collection to register your custom connector in PowerApps.

  1. powerapps.com 的左侧菜单中,单击“连接”。In powerapps.com, in the left menu, select Connections. 依次选择省略号(“...”)和右上角的“管理自定义连接器”。Select the ellipsis (...), then select Manage custom connectors in the upper right corner.

    提示:如果在移动浏览器中找不到自定义连接器的管理位置,可能是位于左上角的菜单下方。Tip: If you can't find where to manage custom connectors in a mobile browser, it might be under a menu in the upper left corner.

    创建自定义连接器

  2. 选择“创建自定义连接器”。Select Create custom connector.

    自定义连接器属性

  3. 在“常规”选项卡上,选择自定义连接器的创建方式。In the General tab, choose how you want to create the custom connector.

    • 上载 OpenAPI 文件Upload an OpenAPI file
    • 使用 OpenAPI URLUse an OpenAPI URL
    • 上载 Postman 集合 V1Upload Postman Collection V1

      如何创建自定义连接器

      上载自定义连接器的图标。Upload an icon for your custom connector. “说明”、“主机”和“基 URL”字段通常由 OpenAPI 文件中的信息进行自动填充。Description, Host, and Base URL fields are typically auto-populated with the information from the OpenAPI file. 如果未自动填充,可以手动将其中的信息添加到这些字段。If they are not auto-populated, you can add information to those fields. 选择“继续”。Select Continue.

  4. 在“安全性”选项卡中,输入所有身份验证属性。In the Security tab, enter any authentication properties.

    身份验证类型

    • 身份验证类型是根据 OpenAPI securityDefinitions 对象中定义的内容进行自动填充。The authentication type is auto-populated based on what is defined in your OpenAPI securityDefinitions object. 下面是 OAuth2.0 示例。Below is an OAuth2.0 example.

      "securityDefinitions": {
          "AAD": {
          "type": "oauth2",
          "flow": "accessCode",
          "authorizationUrl": "https://login.windows.net/common/oauth2/authorize",
          "scopes": {}
          }
      },
      
    • 如果 OpenAPI 文件未使用 securityDefintions 对象,则无需输入其他任何值。If the OpenAPI file does not use the securityDefintions object, then no additional values are needed.
    • 如果使用的是 Postman 集合,仅在使用支持的身份验证类型(如 OAuth 2.0 或 Basic)时,才会自动填充身份验证类型。When using a Postman Collection, authentication type is auto-populated only when using supported authentication types, such as OAuth 2.0 or Basic.
    • 有关如何设置 Azure Active Directory (AAD) 身份验证的示例,请参阅创建适用于 PowerApps 的自定义 Web APIFor an example of setting up Azure Active Directory (AAD) authenthication, see Create a custom Web API for PowerApps.
  5. “定义”选项卡中会自动填充 OpenAPI 文件或 Postman 集合中定义的所有操作,以及请求和响应值。In the Definitions tab, all the operations defined in your OpenAPI file or Postman Collection, along with request and response values, are auto-populated. 如果所有必需操作均已定义,请转到注册过程中的第 6 步,无需在此屏幕上进行任何更改。If all your required operations are defined, you can go to step 6 in the registration process without making changes on this screen.

    “定义”选项卡

    如果要编辑现有操作或向自定义连接器添加新操作,请继续阅读下面的内容。If you want to edit existing actions or add new actions to your custom connector, continue reading below.

    1. 如果要添加 OpenAPI 文件或 Postman 集合中没有的新操作,请选择左侧窗格中的“新建操作”,然后在“常规”部分中填写操作的名称、说明和公开范围。If you want to add a new action that was not already in your OpenAPI file or Postman Collection, select New action in the left pane and fill in the General section with the name, description, and visibility of your operation.
    2. 在“请求”部分中,选择右上角的“从示例导入”。In the Request section, select Import from sample on the top right. 在右侧窗体中,粘贴示例请求。In the form on the right, paste in a sample request. 示例请求通常位于 API 文档中,可以使用其中的信息来填充“谓词”、“请求 URL”、“标头”和“正文”字段。Sample requests are usually available in the API documentation, where you can get information to fill out the Verb, Request URL, Headers, and Body fields. 有关示例,请参阅文本分析 API 文档See the Text Analytics API documentation for an example.

      从示例导入

    3. 选择“导入”,完成请求定义。Select Import to complete the request definition. 以类似的方式定义响应。Define the response in a similar way.
  6. 定义完所有操作后,请选择“创建”,创建自定义连接器。Once you have all your operations defined, select Create to create your custom connector.
  7. 创建自定义连接器后,请转到“测试”选项卡,测试 API 中定义的操作。Once you have created your custom connector, go to the Test tab to test the operations defined in the API. 选择一个连接,然后提供输入参数来测试操作。Choose a connection, and provide input parameters to test an operation.

    测试自定义连接器

    如果调用成功,将返回有效响应。If the call is successful, you get a valid response.

    测试 API 响应

使用自定义连接器Use your custom connector

至此,已经注册了 API,可将自定义连接器添加到应用中,就像添加其他任何数据源一样。Now that you've registered your API, add the custom connector to your app like you would any other data source. 我们将以一个简单示例为例。We'll go through a brief example here. 有关数据连接的详细信息,请参阅在 PowerApps 中添加数据连接For more information about data connections, see Add a data connection in PowerApps.

  1. 在 PowerApps Studio 中,单击或点击右侧窗格中的“添加数据源”。In PowerApps Studio, in the right pane, click or tap Add data source.

  2. 单击或点击已创建的自定义连接器。Click or tap the custom connector that you created.

  3. 完成登录要连接的服务所需的全部步骤。Complete any steps necessary to sign in to the service you're connecting to. 如果 API 使用 OAuth 身份验证,可能会看到登录屏幕。If your API uses OAuth authentication, you might be presented a sign-in screen. 如果使用的是 API 密钥身份验证,系统可能会提示你输入密钥值。For API key authentication, you might be prompted for a key value.
  4. 在应用中调用 API。Call the API in your app. 以我们为例,我们创建的应用可以将文本提交到认知服务,并返回介于 0 到 1 之间的情绪得分(应用以百分比的形式显示得分)。For our example, we created an app that submits text to Cognitive Services and gets back a sentiment score of 0 to 1, which the app shows as a percentage.

    • 使用此连接器,如果开始在编辑栏中键入“Az”,可以查看此 API 及其提供的操作。With this connector, if you start typing "Az" in the formula bar, you see the API and the operations that it makes available.

    • 完整的调用如下所示,其中我们从 TextInput 控件传递文本,然后应用中会显示返回的得分:The complete call looks like this, where we pass in text from the TextInput control and get back a score to display in the app:

      'AzureMachineLearning-TextAnalytics'.Sentiment({documents:Table({language:"en",id:"1",text:TextInput.Text})}).documents.score)
      
    • 虽然我们要在应用中多执行一些操作来处理返回的数据,但并不太复杂。We do a little more work in the app to handle the data that comes back, but it's not too complicated.

完成的应用如下图所示。The finished app looks like the following image. 虽然这是一个简单应用,但可以通过自定义连接器调用认知服务,从而实现强大的功能。It's a simple app, but it gains powerful functionality by being able to call Cognitive Services through a custom connector.

配额和限制Quota and throttling

  • 有关自定义连接器创建配额的详细信息,请参阅 PowerApps 定价页。See the PowerApps Pricing page for details about custom connector creation quotas. 与你共享的自定义连接器不计入此配额。Custom connectors that are shared with you don't count against this quota.
  • 对于在自定义连接器中创建的每个连接,用户每分钟最多可以发出 500 个请求。For each connection created on a custom connector, users can make up to 500 requests per minute.

共享自定义连接器Share your custom connector

至此,已拥有自定义连接器,可以与组织中的其他用户进行共享。Now that you have a custom connector, you can share it with other users in your organization. 请注意,共享 API 后,其他用户可能会开始依赖它,而删除自定义连接器则会删除与此 API 的所有连接。Keep in mind that when you share an API, others might start to depend on it, and deleting a custom connector deletes all the connections to the API. 如果要为组织以外的用户提供连接器,请参阅有关在 PowerApps 中验证自定义连接器的概述If you want to provide a connector for users outside your organization, see Overview of certifying custom connectors in PowerApps.

  1. powerapps.com 的左侧菜单中,单击“连接”。In powerapps.com, in the left menu, select Connections. 依次选择省略号(“...”)和右上角的“管理自定义连接器”。Select the ellipsis (...), then select Manage custom connectors in the upper right corner.

    新建连接

  2. 依次选择连接器的省略号(“...”)按钮和“查看属性”。Select the ellipsis (. . .) button for your connector, then select View properties.

    查看连接器属性

  3. 选择你的 API,选择“共享”,然后输入要向其授予该 API 访问权限的用户或组。Select your API, select Share, and then enter the users or groups to whom you want to grant access to your API.

    共享自定义连接器

  4. 选择“保存”。Select Save.

后续步骤Next steps

了解如何创建 Postman 集合Learn how to create a Postman Collection

使用 ASP.NET Web APIUse an ASP.NET Web API.

注册 Azure 资源管理器 APIRegister an Azure Resource Manager API.