在 Azure 逻辑应用中使用 HTTPS 终结点调用、触发或嵌套逻辑应用

  • 项目

若要使逻辑应用可通过 URL 调用，以便逻辑应用能够从其他服务接收传入请求，你可以在逻辑应用上使用基于请求的触发器以原生方式公开同步 HTTPS 终结点。 使用此功能可以从其他逻辑应用调用逻辑应用，并创建一种可调用终结点的模式。 若要设置可调用终结点来处理传入调用，可以使用以下任意一种触发器类型：

本文介绍如何使用请求触发器在逻辑应用上创建可调用终结点，以及从另一个逻辑应用调用该终结点。 所有原理均完全适用于可用于接收传入请求的其他触发器类型。

有关逻辑应用入站调用（例如传输层安全性 (TLS) [以前称为安全套接字层 (SSL)] 和 Azure Active Directory 开放式身份验证 (Azure AD OAuth)）的安全性、授权和加密的详细信息，以及使用 Azure API 管理来公开逻辑应用，或限制发起入站调用的 IP 地址的详细信息，请参阅保护访问和数据 - 对基于请求的触发器的入站调用的访问。

先决条件

创建可调用的终结点

  1. 登录到 Azure 门户。 在逻辑应用设计器中创建并打开一个空白逻辑应用。

  2. 在搜索框下，选择“内置”。 在搜索框中，输入 request 作为筛选器。 在触发器列表中，选择“当收到 HTTP 请求时”。

    Find and select the Request trigger

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

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

    对于本示例，请输入以下架构：

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

    Provide JSON schema for the Request action

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

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

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

      {
 "address": {
    "streetNumber": "00000",
    "streetName": "AnyStreet",
    "town": "AnyTown",
    "postalCode": "11111-1111"
}
}

    3. 准备就绪后，选择“完成”。

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

  4. 保存逻辑应用。

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

    Generated callback URL for endpoint

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

    • 在“HTTP POST URL”框的右侧，选择“复制 URL”（复制文件图标）。

    • 使用“请求”触发器需要的方法进行此调用。 此示例使用 POST 方法：

      POST https://management.chinacloudapi.cn/{logic-app-resource-ID}/triggers/{endpoint-trigger-name}/listCallbackURL?api-version=2016-06-01

    • 从逻辑应用的“概览”窗格中复制回叫 URL。

      1. 在逻辑应用的菜单中，选择“概述”。

      2. 在“摘要”部分，选择“查看触发器历史记录”。

        Get endpoint URL from Azure portal

      3. 在“回调 URL [POST]”下，复制 URL：

        Copy endpoint URL from Azure portal

选择预期的请求方法

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

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

    Add

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

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

    Select request method expected by the trigger

通过终结点 URL 传递参数

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

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

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

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

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

通过 GET 参数接受值

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

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

  2. 在“请求”触发器下，添加要在其中使用参数值的操作。 对于此示例，请添加“响应”操作。

    1. 在“请求”触发器下，选择“新建步骤”>“添加操作”。

    2. 在“选择操作”下的搜索框中，输入 response 作为筛选器。 在操作列表中选择“响应”操作。

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

    1. 在“响应”操作的“正文”属性中单击，以显示动态内容列表，然后选择“表达式”。

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

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

      Add

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

      Resolved

      如果你保存逻辑应用，请通过导航方式离开设计器，然后返回到设计器，该标记将显示你指定的参数名称，例如：

      Resolved expression for parameter name

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

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

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

      Add example

  4. 若要测试可调用终结点，请从“请求”触发器中复制回叫 URL，并将该 URL 粘贴到另一个浏览器窗口中。 在 URL 中，按以下格式将问号 (?) 后面的参数名称和值添加到 URL，然后按 Enter。

    ...?{parameter-name=parameter-value}&api-version=2016-10-01...

    https://prod-07.chinaeast2.logic.azure.cn:433/workflows/{logic-app-resource-ID}/triggers/manual/paths/invoke?{parameter-name=parameter-value}&api-version=2016-10-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig={shared-access-signature}

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

    Response from sending request to callback URL

  5. 若要将参数名称和值置于 URL 中的不同位置，请确保使用与号 (&) 作为前缀，例如：

    ...?api-version=2016-10-01&{parameter-name=parameter-value}&...

    此示例显示了示例参数名称和值 postalCode=123456 位于 URL 中的不同位置的回叫 URL：

    • 第 1 个位置：https://prod-07.chinaeast2.logic.azure.cn:433/workflows/{logic-app-resource-ID}/triggers/manual/paths/invoke?postalCode=123456&api-version=2016-10-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig={shared-access-signature}

    • 第 2 个位置：https://prod-07.chinaeast2.logic.azure.cn:433/workflows/{logic-app-resource-ID}/triggers/manual/paths/invoke?api-version=2016-10-01&postalCode=123456&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig={shared-access-signature}

注意

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

通过相对路径接受值

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

    Add

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

    Specify the relative path for the parameter

  3. 在“请求”触发器下，添加要在其中使用参数值的操作。 对于此示例，请添加“响应”操作。

    1. 在“请求”触发器下，选择“新建步骤”>“添加操作”。

    2. 在“选择操作”下的搜索框中，输入 response 作为筛选器。 在操作列表中选择“响应”操作。

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

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

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

    2. 在动态内容列表中，从“收到 HTTP 请求时”部分选择“postalCode”标记。

      Add the specified parameter to response body

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

      Example response body with parameter

  5. 保存逻辑应用。

    在“请求”触发器中，回叫 URL 已更新，现在包含相对路径，例如：

    https://prod-07.chinaeast2.logic.azure.cn/workflows/{logic-app-resource-ID}/triggers/manual/paths/invoke/address/{postalCode}?api-version=2016-10-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig={shared-access-signature}

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

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

    Response from sending request to callback URL

    注意

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

通过终结点 URL 调用逻辑应用

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

从架构生成的标记

在“请求”触发器中提供 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. 在“选择操作”下，选择“内置”。 在搜索框中，输入 logic apps 作为筛选器。 在操作列表中，选择“选择逻辑应用工作流”。

    Nest logic app inside current logic app

    设计器将显示可供选择的逻辑应用。

  3. 选择要从当前逻辑应用调用的逻辑应用。

    Select logic app to call from current logic app

引用传入请求中的内容

如果传入请求的内容类型为 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，并指定正文包含 town 和 postalCode 属性的值，这些值基于本主题前面所述的“请求”触发器的 JSON 架构。

Provide response content for HTTPS Response action

响应具有以下属性：

属性（显示值） 属性 (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)] 和 Azure Active Directory 开放式身份验证 (Azure AD OAuth)）的安全性、授权和加密的详细信息，以及使用 Azure API 管理来公开逻辑应用，或限制发起入站调用的 IP 地址的详细信息，请参阅保护访问和数据 - 对基于请求的触发器的入站调用的访问。

问：是否可以进一步配置可调用终结点？

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

后续步骤