在 Azure 逻辑应用 中从工作流调用自定义 Web API 和 REST API 的模式

适用于：Azure 逻辑应用（消耗型 + 标准型）

虽然 Azure 逻辑应用提供了 1,400 多个可在逻辑应用工作流中使用的连接器，但你可能希望调用目前尚未作为连接器提供的 API、系统和服务。 可以创建自己的 API，提供在工作流中使用的操作和触发器。 下面是一些其他理由，解释为何建议创建可从工作流调用的自定义 API：

• 扩展当前系统集成和数据集成工作流。
• 帮助客户使用服务来管理专业或个人任务。
• 扩展服务的市场宣传、可发现性和使用。

连接器本质上是 Web API，此类 API 将 REST 用于可插入接口、将 OpenAPI 元数据格式用于文档、将 JSON 用作其数据交换格式。 因为连接器是通过 HTTP 终结点进行通信的 REST API，所以可以使用任何语言生成连接器，如 .NET、Java、Python 或 Node.js。 此外，还可在 Azure 应用服务上托管API，前者是一款平台即服务 (PaaS) 产品，可为 API 托管提供一种最简单且可缩放性最高的最佳方法。

对于要用于逻辑应用工作流的自定义 API，API 可以提供在工作流中执行特定任务的操作。 API 还可充当触发器，在新数据或事件满足指定条件时启动工作流运行。 本主题介绍根据想要 API 提供的行为，在 API 中生成操作和触发器可以遵循的常见模式。

可在 Azure 应用服务 上托管API，它是一款平台即服务 (PaaS) 产品，可提供简单的高缩放性 API 托管。

自定义 API 和自定义连接器有何不同？

自定义 API 和自定义连接器都是 Web API，此类 API 将 REST 用于可插入接口、将 OpenAPI 元数据格式用于文档、将 JSON 用作其数据交换格式。 因为这些 API 和连接器是通过 HTTP 终结点进行通信的 REST API，所以可以使用任何语言生成自定义 API 和连接器，如 .NET、Java、Python 或 Node.js。

自定义 API 允许调用非连接器 API，并提供可使用 HTTP + Swagger、Azure API 管理或应用程序服务调用的终结点。 自定义连接器的工作方式与自定义 API 类似，但它还具有以下属性：

• 在 Azure 中注册为逻辑应用连接器资源。
• 在逻辑应用设计器中，它们会带有图标显示在 Microsoft 托管连接器旁边。
• 仅对连接器作者以及逻辑应用部署所在区域中具有相同 Microsoft Entra 租户和 Azure 订阅的逻辑应用资源用户可用。

还可指定注册的连接器进行 Microsoft 认证。 此过程验证注册的连接器是否满足公共使用的条件，并使这些连接器可供 Power Automate 和 Microsoft Power Apps 中的用户使用。

有关详细信息，请查看以下文档：

• 自定义连接器概述
• 从 Web API 创建自定义连接器
• 在 Azure 逻辑应用中注册自定义连接器

有用的工具

当 API 也具有描述 API 的操作和参数的 OpenAPI 文档时，自定义 API 最适用于逻辑应用。 许多库（如 Swashbuckle）可自动为你生成 Swagger 文件。 若要批注 Swagger 文件的显示名称、属性类型等，也可使用 TRex 以便 Swagger 文件更适用于逻辑应用。

操作模式

对于执行任务的逻辑应用，自定义 API 应提供操作。 API 中的每个操作都对应一个操作项。 基本操作是接受 HTTP 请求并返回 HTTP 响应的控制器。 例如，工作流将 HTTP 请求发送到 Web 应用或 API 应用。 然后应用返回 HTTP 响应及工作流可处理的内容。

对于标准操作，可在 API 中编写 HTTP 请求方法，并在 Swagger 文件中描述该方法。 然后，您可以直接使用HTTP 操作调用 API。在默认情况下，必须在请求超时限制内返回响应。

要让工作流等待 API 完成长时间运行的任务，API 可以遵循本主题中介绍的异步轮询模式或异步 Webhook 模式。 为帮助你形象化这些模式的不同行为，把这一过程想象成从面包店预定定制的蛋糕。 轮询模式类似于你每隔 20 分钟打电话给面包店询问蛋糕是否做好。 Webhook 模式所体现的正是这样一种情形：面包店向你要你的电话号码，以便在蛋糕做好时打电话通知你。

使用轮询操作模式执行长时间运行的任务

如果希望 API 执行运行时间可能超过请求超时限制的任务，可以使用异步轮询模式。 此模式使 API 在单独线程中执行任务，但与 Azure 逻辑应用引擎保持活动连接。 这样一来，在 API 完成工作之前，工作流不会超时或继续进行工作流的下一步。

以下是常规模式：

1. 请确保引擎知道 API 接受了请求并已开始工作。
2. 当引擎针对作业状态进行后续请求时，让引擎知道 API 完成任务的时间。
3. 返回引擎的相关数据，以便工作流可以继续。

现在将之前的面包店类比用于轮询模式，假设你打电话给面包店预订定制的蛋糕并要求送货。 做蛋糕的过程需要花费时间，而且你不想在面包店做蛋糕的时候拿着电话等待。 面包店确认订单，并让你每隔 20 分钟打电话确认蛋糕是否做好。 20 分钟之后，你打电话给面包店，但是面包店告诉你蛋糕还没有做好，请过 20 分钟再打电话。 这一来一回的过程会一直持续，直到你打电话，面包店告诉你你的订单已经准备好了，并把蛋糕送到你手上。

那么我们把这个轮询模式对应回去。 面包店代表自定义 API，而你（预订蛋糕的客户）代表 Azure 逻辑应用引擎。 当引擎向你的 API 发出请求时，你的 API 会确认该请求，并返回引擎可以检查作业状态的时间间隔。 引擎继续检查作业状态，直到 API 响应作业已完成，并将数据返回给逻辑应用，随之推进工作流。

以下是 API 要跟随的具体步骤（从 API 的角度）：

1. 当您的 API 收到启动工作的 HTTP 请求时，立即返回一个 HTTP 202 ACCEPTED 响应，并包含本步骤后文所述的 location 标头。 此响应让 Azure 逻辑应用引擎知道 API 收到了请求、接受了请求有效负载（数据输入），并且现在正在处理。

   202 ACCEPTED 响应应包含这些标头：

   • 必需：一个 location 标头，用于指定一个 URL 的绝对路径，Azure 逻辑应用引擎可在该 URL 检查您的 API 作业状态

   • 可选：一个 retry-after 标头，用于指定引擎在检查 location URL 以获取作业状态之前应等待的秒数。

     默认情况下，引擎会在一秒后轮询 location URL。 若要指定不同的时间间隔，请包括 retry-after 标头和下次轮询前的秒数。

2. 超过指定的时间后，Azure 逻辑应用引擎轮询 location URL 来检查作业状态。 API 应执行以下检查，并返回以下响应：

   • 如果作业已完成，返回 HTTP 200 OK 响应及响应有效负载（下一步的输入）。

   • 如果作业仍在处理，返回另一个 HTTP 202 ACCEPTED 响应，但其标头与初始响应相同。

当 API 遵循此模式时，若要继续检查作业状态，无需在工作流定义中执行任何操作。 当引擎收到 HTTP 202 ACCEPTED 响应并带有有效的 location 标头时，它会遵循异步模式，并持续检查 location 标头，直到你的 API 返回非 202 的响应。

使用 Webhook 操作模式执行长时间运行任务

作为替代方法，可对长时间运行的任务和异步处理使用 Webhook 模式。 此模式暂停工作流并等待 API 的“回叫”，以完成处理并继续工作流。 此回调是一个 HTTP POST 请求，当事件发生时，它会向某个 URL 发送消息。

现在将之前的面包店类比用于 Webhook 模式，假设你打电话给面包店预订定制的蛋糕并要求送货。 做蛋糕的过程需要花费时间，而且你不想在面包店做蛋糕的时候拿着电话等待。 面包店确认你的订单，但这一次，你把电话号码给面包店，以便蛋糕做好后他们可以给你打电话。 这一次，面包店会在你的订单准备好时通知你，并把蛋糕送到你手上。

如果我们把这种 Webhook 模式对应回这个例子中，面包店代表你的自定义 API，而作为蛋糕顾客的你则代表 Azure 逻辑应用引擎。 引擎会调用你的 API，并在请求中包含一个“回调”URL。 完成作业后，API 使用 URL 来通知引擎并将数据返回到逻辑应用，然后继续工作流。

对于此模式，在控制器上设置两个终结点：subscribe 和 unsubscribe

• subscribe 终结点：当执行到达工作流中的 API 操作时，Azure 逻辑应用引擎调用 subscribe 终结点。 此步骤会使工作流创建一个供您的 API 存储的回调 URL，然后在工作完成后等待您的 API 发出回调。 然后，您的 API 会通过 HTTP POST 向该 URL 发起回调，并将任何返回的内容和标头作为输入传递给逻辑应用。

• unsubscribe 终结点：如果工作流运行已取消，Azure 逻辑应用引擎将调用 unsubscribe 终结点。 然后，您的 API 可以取消注册回调 URL，并根据需要停止相关进程。

目前，工作流设计器不支持通过 Swagger 发现 Webhook 终结点。 因此对于此模式，需要添加 Webhook 操作并指定 URL、标头以及请求正文。 另请参阅工作流操作和触发器。 有关 Webhook 模式的示例，查看 GitHub 中的 Webhook 触发器示例。

下面是一些其他提示和说明：

• 若要传入回调 URL，可以根据需要在前面的任意字段中使用 @listCallbackUrl() 工作流函数。

• 如果同时拥有逻辑应用资源和订阅的服务，则在调用回调 URL 之后，无需调用 unsubscribe 终结点。 否则，Azure 逻辑应用运行时需要调用 unsubscribe 终结点以表示不需要更多调用，并且允许在服务器端进行资源清理。

触发模式

自定义 API 可充当触发器，在新数据或事件满足指定条件时启动工作流运行。 此触发器既可以定期检查，也可以等待并侦听来自您的服务终结点的新数据或事件。 如果新数据或事件满足指定的条件，触发器触发并启动正在侦听该触发器的逻辑应用。 若要以这种方式启动逻辑应用，API 可以遵循轮询触发器或 Webhook 触发器模式。 这些模式类似于轮询操作和webhook 操作的对应模式。 另请详细了解触发器的用量计量。

使用轮询触发器模式定期检测新数据或事件

轮询触发器的行为非常类似于本主题中前面所述的轮询操作。 Azure 逻辑应用引擎定期调用并检查触发器终结点，查看新数据或事件。 如果引擎发现满足指定条件的新数据或事件，触发器即触发。 然后，引擎创建将数据处理为输入的工作流实例。

以下是从 API 的角度描述的轮询触发器的具体步骤：

例如，若要定期检查服务中是否有新文件，可以创建一个具有以下行为的轮询触发器：

使用 Webhook 触发器模式等待并监听新的数据或事件

Webhook 触发器是一种推送触发器，它会在您的服务端点等待并侦听新的数据或事件。 如果新数据或事件满足指定的条件，触发器即触发，并创建工作流实例，然后将数据处理为输入。 Webhook 触发器的行为非常类似于之前本主题中所述的 Webhook 操作，并设置有 subscribe 和 unsubscribe 终结点。

• subscribe 终结点：在逻辑应用中添加和保存 Webhook 触发器时，Azure 逻辑应用引擎调用 subscribe 终结点。 此步骤会使工作流创建一个供您的 API 存储的回调 URL。 当有新数据，或发生满足指定条件的事件时，您的 API 会通过 HTTP POST 向该 URL 发起回调。 内容负载和标头作为输入传递给逻辑应用。

• unsubscribe 终结点：如果删除 Webhook 触发器或整个逻辑应用资源，Azure 逻辑应用 引擎会调用 unsubscribe 终结点。 届时，您的 API 可以注销回调 URL，并根据需要停止任何必要的进程。

目前，工作流设计器不支持通过 Swagger 发现 Webhook 终结点。 因此对于此模式，需要添加 Webhook 触发器并指定 URL、 标头以及请求正文。 另请参阅 HTTPWebhook 触发器。 有关 Webhook 模式的示例，请查看 GitHub 中的 Webhook 触发器控制器示例。

下面是一些其他提示和说明：

• 若要传入回调 URL，可以根据需要在前面的任意字段中使用 @listCallbackUrl() 工作流函数。

• 若要防止多次处理相同数据，触发器应清理已读取且传递到逻辑应用的数据。

• 如果同时拥有逻辑应用资源和订阅的服务，则在调用回调 URL 之后，无需调用 unsubscribe 终结点。 否则，逻辑应用运行时需要调用 unsubscribe 终结点以表示不需要更多调用，并且允许在服务器端进行资源清理。

提高从逻辑应用对 API 进行调用的安全性

创建自定义 API 后，请为 API 设置身份验证，以便可以通过逻辑应用安全地调用它们。 了解如何提高从逻辑应用对自定义 API 进行调用的安全性。

部署和调用 API

设置身份验证后，为您的 API 配置部署。 了解如何通过逻辑应用部署和调用自定义 API。

将自定义 API 发布到 Azure

要使自定义 API 可供其他 Azure 逻辑应用用户使用，必须添加安全性并将这些 API 注册为 Azure 逻辑应用连接器。 有关详细信息，请参阅自定义连接器概述。

要使自定义 API 可供逻辑应用、Power Automate 和 Microsoft Power Apps 中所有用户使用，必须添加安全性、将 API 注册为 Azure 逻辑应用连接器并向 Azure 认证计划提名连接器。

后续步骤

• 处理错误和异常
• 使用 HTTP 终结点调用、触发或嵌套逻辑应用
• 操作和触发器的使用量计量