在 Azure 逻辑应用中创建可以使用 HTTPS 终结点调用、触发或嵌套的工作流

适用范围:Azure 逻辑应用(消耗型 + 标准型)

某些方案可能要求你创建一个可以接收来自其他服务或工作流的入站请求的逻辑应用工作流,或者创建一个可以使用 URL 调用的工作流。 对于此任务,当你使用以下任何基于请求的触发器类型时,可以在工作流上公开原生的同步 HTTPS 终结点:

本指南演示如何通过添加“请求”触发器为工作流创建可调用终结点,然后从另一个工作流调用该终结点。 所有原则都同样适用于可接收入站请求的其他基于请求的触发器类型。

先决条件

  • Azure 帐户和订阅。 如果没有订阅,可以注册 Azure 帐户

  • 一个逻辑应用工作流,你要在其中使用“请求”触发器来创建可调用终结点。 可以从一个空白的工作流着手,也可以从可在其中替换当前触发器的现有工作流着手。 本示例以空白的工作流着手。

  • 若要测试创建的可调用终结点的 URL,你需要一个工具或应用,例如 Postman

创建可调用的终结点

根据使用的是“标准”还是“消耗”逻辑应用工作流,按相应步骤操作:

  1. Azure 门户的设计器中,打开标准逻辑应用资源和空白工作流。

  2. 按照以下常规步骤添加名为“收到 HTTP 请求时”的请求触发器

  3. (可选)在“请求正文 JSON 架构”框中,可以输入一个 JSON 架构,用于描述预期该触发器要接收的有效负载或数据。

    设计器将使用此架构来生成表示触发器输出的标记。 然后,可以在逻辑应用的整个工作流中轻松引用这些输出。 详细了解从 JSON 架构生成的标记

    对于此示例,请输入以下架构:

    {
       "type": "object",
       "properties": {
          "address": {
             "type": "object",
             "properties": {
                "streetNumber": {
                   "type": "string"
                },
                "streetName": {
                   "type": "string"
                },
                "town": {
                   "type": "string"
                },
                "postalCode": {
                   "type": "string"
                }
             }
          }
       }
    }
    

    屏幕截图显示了“标准”工作流,其中包含请求触发器和包含示例架构的请求正文 JSON 架构参数。

    或者,可以通过提供示例有效负载来生成 JSON 架构:

    1. 在“请求”触发器中,选择“使用示例有效负载生成架构”。

    2. 在“输入或粘贴示例 JSON 有效负载”框中输入示例有效负载,例如:

      {
         "address": {
            "streetNumber": "00000",
            "streetName": "AnyStreet",
            "town": "AnyTown",
            "postalCode": "11111-1111"
        }
      }
      
    3. 准备就绪后,选择“完成”。

      “请求正文 JSON 架构”框现在会显示生成的架构。

  4. 保存工作流。

    “HTTP POST URL”框现在会显示生成的回叫 URL,其他服务可以使用该 URL 来调用和触发逻辑应用工作流。 此 URL 包含查询参数,这些参数指定了用于身份验证的共享访问签名 (SAS) 密钥。

    屏幕截图显示了“标准”工作流、请求触发器和为终结点生成的回叫 URL。

  5. 若要复制回叫 URL,可以使用以下选项:

    • 在“HTTP POST URL”框的右侧,选择“复制 URL”(复制文件图标)。

    • 从工作流的“概述”页中复制回叫 URL。

      1. 在工作流的菜单上,选择“概述”。

      2. 在“概述”页的“工作流 URL”下,将指针移到该 URL 上,然后选择“复制到剪贴板”

        屏幕截图显示了“标准”工作流和“概述”页,其中包含工作流 URL。

  6. 若要测试回叫 URL 并触发工作流,请使用 HTTP 请求工具及其说明将 HTTP 请求发送到 URL,包括“请求”触发器所需的方法

    此示例使用 POST 方法与复制的 URL 配合使用,如以下示例所示

    POST https://{logic-app-name}.chinacloudsites.cn:443/api/{workflow-name}/triggers/{trigger-name}/invoke?api-version=2022-05-01&sp=%2Ftriggers%2F{trigger-name}%2Frun&sv=1.0&sig={shared-access-signature}

选择预期的请求方法

默认情况下,“请求”触发器的预期请求是 POST 请求。 不过,可以指定调用方必须使用不同的方法,但只能指定一个方法。

  1. 在“请求”触发器中打开“高级参数”列表,然后选择“方法”,将此属性添加到触发器中。

  2. 在“方法”列表中,选择触发器所应当预期的方法。 或者,可以指定自定义方法。

    例如,选择“GET”方法,以便稍后可以测试终结点的 URL。

通过终结点 URL 传递参数

如果希望通过终结点的 URL 接受参数值,可以使用以下选项:

  • 通过 GET 参数接受值,或者通过 URL 参数接受值。

    这些值在终结点的 URL 中作为名称/值对传递。 对于此选项,你需要在请求触发器中使用 GET 方法。 在后续操作中,可以通过在表达式中使用 triggerOutputs() 函数,在触发器输出中获取参数值。

  • 通过相对路径接受值,适用于“请求”触发器中的参数。

    这些值通过终结点 URL 中的相对路径传递。 你还需要显式选择触发器预期的方法。 在后续操作中,可以通过直接引用触发器输出,在这些输出中获取参数值。

通过 GET 参数接受值

  1. 在“请求”触发器中,打开“高级参数”,将“方法”属性添加到触发器,然后选择“GET”方法。

    有关详细信息,请参阅选择预期的请求方法

  2. 在设计器中,按照这些常规步骤添加要在其中使用参数值的操作

    对于此示例,请选择名为“响应”的操作。

  3. 若要构建检索参数值的 triggerOutputs() 表达式,请执行以下步骤:

    1. 在“响应”操作中,选中“正文”属性内部,以便显示动态内容(闪电图标)和表达式编辑器(公式图标)的选项。 选择公式图标以打开表达式编辑器。

    2. 在表达式框中输入以下表达式,将 parameter-name 替换为你的参数名称,然后选择“确定”

      triggerOutputs()['queries']['parameter-name']

      屏幕截图显示了“标准”工作流、响应操作和 triggerOutputs() 表达式。

      在“正文”属性中,表达式将解析为 triggerOutputs() 标记。

      屏幕截图显示了“标准”工作流,以及响应操作的解析 triggerOutputs() 表达式。

      如果你保存工作流,离开设计器,然后返回到设计器,该标记会显示你指定的参数名称,例如:

      屏幕截图显示了“标准”工作流,其中包含响应操作的参数名称解析表达式。

      在代码视图中,“正文”属性显示在“响应”操作的定义中,如下所示:

      "body": "@{triggerOutputs()['queries']['parameter-name']}",

      例如,假设你要为名为 postalCode 的参数传递值。 “正文”属性指定带尾随空格的字符串 Postal Code: ,后跟相应的表达式:

      屏幕截图显示了“标准”工作流,以及响应操作和示例 triggerOutputs() 表达式。

测试可调用终结点

  1. 从“请求”触发器中复制工作流 URL,并将该 URL 粘贴到另一个浏览器窗口中。 在 URL 中,按以下格式将参数名称和值添加到 URL,然后按 Enter。

    ...invoke/{parameter-name}/{parameter-value}?api-version=2022-05-01...

    例如:

    https://mystandardlogicapp.chinacloudsites.cn/api/Stateful-Workflow/triggers/When_a_HTTP_request_is_received/invoke/address/12345?api-version=2022-05-01&sp=%2Ftriggers%2FWhen_a_HTTP_request_is_received%2Frun&sv=1.0&sig={shared-access-signature}

    浏览器将返回包含以下文本的响应:Postal Code: 123456

    屏幕截图显示了浏览器,其中显示了从请求到回叫 URL 的“标准”工作流响应。

注意

若要在 URI 中包含哈希符号或井号 ( # ),请改用以下编码版本:%25%23

通过相对路径接受值

  1. 在“请求”触发器中打开“高级参数”列表,然后选择“相对路径”,将此属性添加到触发器中。

    屏幕截图显示了“标准”工作流、请求触发器和名为 Relative path 的属性。

  2. 在“相对路径”属性中,指定希望 URL 接受的 JSON 架构中参数的相对路径,例如 /address/{postalCode}

    屏幕截图显示了“标准”工作流、请求触发器以及 Relative path 参数值。

  3. 在“请求”触发器下,按照这些常规步骤添加要在其中使用参数值的操作

    对于此示例,请添加“响应”操作。

  4. 在响应操作的“正文”属性中,包含表示在触发器相对路径中指定的参数的标记。

    例如,假设你希望“响应”操作返回 Postal Code: {postalCode}

    1. 请在“正文”属性中,输入 Postal Code: 和一个尾部空格。 将光标停留在编辑框内,使动态内容列表保持打开状态。

    2. 在动态内容列表中,从“收到 HTTP 请求时”部分选择“路径参数 postalCode”触发器输出

      屏幕截图显示了“标准”工作流、响应操作以及要包含在响应正文中的指定触发器输出。

      “正文”属性现在包含选定的参数:

      屏幕截图显示了“标准”工作流和带参数的示例响应正文。

  5. 保存工作流。

    在“请求”触发器中,回调 URL 已更新,现在包含相对路径,例如:

    https://mystandardlogicapp.chinacloudsites.cn/api/Stateful-Workflow/triggers/When_a_HTTP_request_is_received/invoke/address/%7BpostalCode%7D?api-version=2022-05-01&sp=%2Ftriggers%2FWhen_a_HTTP_request_is_received%2Frun&sv=1.0&sig={shared-access-signature}

  6. 若要测试可调用终结点,请从“请求”触发器中复制更新的回调 URL,并将该 URL 粘贴到另一个浏览器窗口中,将 URL 中的 %7BpostalCode%7D 替换为 123456,然后按 Enter。

    浏览器将返回包含以下文本的响应:Postal Code: 123456

    屏幕截图显示了浏览器,其中显示了从请求到回叫 URL 的“标准”工作流响应。

注意

若要在 URI 中包含哈希符号或井号 ( # ),请改用以下编码版本:%25%23

通过终结点 URL 调用工作流

创建终结点后,可以将 HTTPS 请求发送到该终结点的完整 URL,从而触发工作流。 Azure 逻辑应用工作流对直接访问终结点提供内置支持。

从架构生成的标记

在“请求”触发器中提供 JSON 架构时,工作流设计器会在该架构中生成属性的标记。 然后,可以使用这些标记通过你的工作流传递数据。

例如,如果将其他属性(例如 "suite")添加到 JSON 架构,则可以在工作流的后续步骤中使用这些属性的标记。 下面是完整的 JSON 架构:

{
   "type": "object",
   "properties": {
      "address": {
         "type": "object",
         "properties": {
            "streetNumber": {
               "type": "string"
            },
            "streetName": {
               "type": "string"
            },
            "suite": {
               "type": "string"
            },
            "town": {
               "type": "string"
            },
            "postalCode": {
               "type": "string"
            }
         }
      }
   }
}

调用其他工作流

可以通过将请求嵌套在当前工作流中来调用其他可以接收请求的工作流。 若要调用这些工作流,请执行以下步骤:

  1. 在设计器中,按照这些常规步骤添加名为“在此工作流应用中调用工作流”的“工作流操作”操作

    “工作流名称”列表会显示可供选择的工作流。

  2. 从“工作流名称”列表中选择要调用的工作流,例如:

    屏幕截图显示了“标准”工作流、名为“调用此工作流应用中的工作流”的操作、打开的“工作流名称”列表以及可供调用的工作流。

从入站请求引用内容

如果传入请求的内容类型为 application/json,则可以在传入请求中引用属性。 否则,此内容被视为可以传递给其他 API 的单个二进制单元。 若要在逻辑应用的工作流内部引用此内容,首先需要转换此内容。

例如,如果传递 application/xml 类型的内容,可以使用 @xpath() 表达式执行 XPath 提取,或使用 @json() 表达式将 XML 转换为 JSON。 详细了解如何处理支持的内容类型

若要从传入请求中获取输出,可以使用 @triggerOutputs 表达式。 例如,假设输出如以下示例所示:

{
   "headers": {
      "content-type" : "application/json"
   },
   "body": {
      "myProperty" : "property value"
   }
}

若要专门访问 body 属性,可以使用 @triggerBody() 表达式作为快捷方式。

对请求的响应

有时,你希望通过向调用方返回内容,对触发工作流的某些请求做出响应。 若要构造响应的状态代码、标头和正文,请使用“响应”操作。 此操作可以出现在工作流中的任何位置,而不仅仅是工作流的末尾。 如果工作流不包含“响应”操作,则终结点会立即以“202 已接受”状态进行响应。

要使原始调用方能够成功获取响应,除非调用了用作嵌套工作流的已触发工作流,否则响应所需的所有步骤必须在请求超时限制内完成。 如果在此限制时间内未返回响应,传入请求将会超时,并收到“408 客户端超时”响应。

对于嵌套工作流,父工作流会继续等待响应,直到所有步骤已完成,而不考虑所需的时间。

构造响应

在响应正文中,可以包含多个标头和任意类型的内容。 例如,以下响应的标头指定响应的内容类型为 application/json,并指定正文包含 townpostalCode 属性的值,这些值基于本主题前面所述的“请求”触发器的 JSON 架构。

屏幕截图显示了“响应”操作和响应内容类型。

响应具有以下属性:

属性(显示值) 属性 (JSON) 说明
状态代码 statusCode 要在传入请求的响应中使用的 HTTPS 状态代码。 该代码可以是以 2xx、4xx 或 5xx 开头的任何有效状态代码。 但是,不允许使用 3xx 状态代码。
标头 headers 要包含在响应中的一个或多个标头
正文 body 正文对象,可以是字符串、JSON 对象甚至是从上一步引用的二进制内容

若要查看“响应”操作的 JSON 定义以及工作流的完整 JSON 定义,请从设计器视图更改为代码视图。

"Response": {
   "type": "Response",
   "kind": "http",
   "inputs": {
      "body": {
         "postalCode": "@triggerBody()?['address']?['postalCode']",
         "town": "@triggerBody()?['address']?['town']"
      },
      "headers": {
         "content-type": "application/json"
      },
      "statusCode": 200
   },
   "runAfter": {}
}

问答

问:入站调用的 URL 安全性如何?

:Azure 使用共享访问签名 (SAS) 安全生成逻辑应用回调 URL。 此签名以查询参数的形式传递,在运行工作流之前必须先验证它。 Azure 使用每个逻辑应用的机密密钥、触发器名称和执行的操作的唯一组合生成签名。 因此,除非用户对机密逻辑应用密钥拥有访问权限,否则他们无法生成有效的签名。

重要

对于生产系统和安全性较高的系统,强烈建议不要直接从浏览器调用工作流,原因如下:

  • URL 中会出现共享访问密钥。
  • 由于域在 Azure 逻辑应用客户之间共享,你将无法管理安全内容策略。

若要详细了解工作流入站调用的安全性、授权和加密,例如传输层安全性 [TLS](以前称为安全套接字层 [SSL])、Microsoft Entra ID 开放式身份验证 (Microsoft Entra ID OAuth)、使用 Azure API Management 公开逻辑应用工作流或限制发起入站调用的 IP 地址,请参阅保护访问和数据 - 对基于请求的触发器的入站调用的访问

问:是否可以进一步配置可调用终结点?

:可以,HTTPS 终结点支持通过 Azure API 管理进行更高级的配置。 此服务还提供相应的功能,使你能够以一致的方式管理所有 API(包括逻辑应用)、设置自定义域名和使用其他身份验证方法等等,例如:

后续步骤