2018年7月22日,星期日

在Flow中使用自定义Azure函数(例如,调用图)

PowerApps和Flow很棒,但是在某些时候,您可能需要使用一些自定义代码对其进行扩展。与其他系统集成时,您可以对Flow(尤其是HTTP操作)执行很多操作,但是如果您可以将Azure Function插入应用程序或进程中,则可以打开更多的门。也许您有一个需要与之交谈的特定系统,或者一些自定义逻辑,该逻辑更容易在代码中而不是在Flow中表达。或者,也许您需要调用Graph,并通过自定义代码(而不是另一种方式)进行操作。在接下来的两篇文章中,我想讨论如何创建自定义连接器,以便您可以从Office 365中的不同位置讨论您的功能:

  • 在Flow中使用自定义Azure函数[本文]
  • 在PowerApps中使用自定义Azure函数

We’将完成本文中的大部分工作。如果你没有’尚未完成使用针对自定义API的Open API / Swagger定义的过程,关键是您的方法将获得具有强类型的各个参数,并且在PowerApps / Flow中易于使用。您必须为此做一些工作,但是’考虑到它的下面很好’只是在PowerApps / Flow和函数之间传递的一个难看的JSON字符串。在这个例子中’在这些文章中使用时,我有一个功能可以为当前用户更新Office 365 / AAD记录(使用图表)–完成OpenAPI工作并定义了自定义连接器后,在Flow中,我的API的操作将公开各个参数,从而可以轻松调用:

SNAGHTMLf85374f

It’在PowerApps中也有类似的故事。因此,如果要向这些技术中插入一些自定义代码,这些步骤几乎是必需的。

让’逐步完成将这些内容拼凑在一起的过程。

定义Azure功能

首先,我们需要一个Azure功能来完成这项工作。我赢了’由于我们的重点是使用Swagger定义API并使其可从PowerApps / Flow进行调用,因此我们将遍历所有方面。但是设置是:

  • HTTP触发函数,用于接收请求主体中(以自Flow / PowerApps/其他客户端的形式)以JSON形式传递的一些数据
    • 对于功能验证,我们只使用“key” option
  • AAD应用注册,具有调用适当的Graph端点的权限
  • 可选-使用托管服务身份+ Azure密钥保管库获取AAD应用程序注册的客户端ID /秘密(N.B.这是您应该做的并且相当琐碎,但是我’省略此示例以使其简单– see 如何在App Service和Azure函数中使用Azure托管服务身份 有关此的MSFT文档)
  • 函数中的代码以获取传递的数据并调用 /v1.0/用户/端点使用PATCH方法更新用户配置文件
身份验证说明
I’m使用功能/密钥身份验证(调用者必须将代码作为查询字符串参数传递给功能URL,例如/ api / DoUpdate?code = foo)。如果你没有’如果希望调用者必须提供密钥,则一种选择是在函数之前使用Azure函数代理–这将为后端提供密钥,但为调用者提供一个简单的URL。
还请注意,可以在PowerApps / Flow和您的功能之间使用AAD身份验证。不过,这里涉及的事情更多,因为您需要2 x AAD应用程序注册(一个用于连接器,一个用于API)和正确的配置– see //docs.microsoft.com/en-us/connectors/custom-connectors/create-web-api-connector#add-the-custom-connector-to-microsoft-flow for 更多 on this. 您 might want to start with 键 authentication first though.

这里’s the code –一些值得注意的地方:

  • 那里’大量的日志记录– useful as you’恢复工作,但是一旦您将其拨下,’re happy
  • 您应该使用静态类级别的HttpClient对象,而不是在每次执行期间实例化一个新对象(这是Azure函数的最佳做法,该函数使用此对象进行HTTP调用)
  • 的data passed from the client is basically in exactly the same format that the Graph endpoint needs to –这简化了我们的功能代码,因为我们只需要再次对其进行序列化
  • ADAL.Net用于获取用于AAD应用程序注册的令牌

我们的Azure功能还需要允许CORS,以便可以使用通配符(*)条目或PowerApps / Flow使用的域从PowerApps / Flow调用它。

    使用OpenAPI(以前称为Swagger)定义API

    Azure尝试通过为您的函数提供默认的API定义来发挥作用,但是通常我们需要对其进行扩展,然后才能将您的函数与PowerApps / Flow一起使用。在这一步中,我们’将扩展默认的API定义,以便还定义有关如何传递和返回JSON的底层细节。您可以通过多种方式执行此操作– options include:

      1. 直接在Azure编辑器中
      2. Using an online Swagger editor which provides a bit 更多 support (e.g. http://editor.swagger.io/)
      3. 使用工具从您的代码生成定义。 Mikael Svenson具有Swagger定义生成器 -我遇到了一些问题,但是我’确保这只是用户错误(缺少注释?),老实说我没有’不要花太多时间在上面。看起来很有用。
      4. 在PowerApps / Flow / Logic应用中从头开始定义API“从头开始创建自定义连接器” process.

      选项1-3让您以某种形式使用OpenAPI定义文件。选项4允许您使用设计器为您构建OpenAPI文件(我们’ll look 在 later) –这听起来不错,但由于某种原因,我发现我更喜欢快速“复制/粘贴一些JSON”选项1或2的经验。除非您的函数有很多参数,否则您会’可能会发现这些选项可以很好地完成工作,但是您可以选择。

      使用函数的OpenAPI定义时,我们将更新定义,然后将PowerApps和Flow指向它:

      处理
      1. 转到“API definition”功能应用程序区域:
        SNAGHTML5be03d27
      2. Notice the default API定义 that is provided for you – this is what we’re going to update:
        SNAGHTML5be22484
      3. 使用上述方法之一,请确保:
        1. API中的每个函数都在“paths”
        2. 的“parameters” and “responses”每个方法的部分正确描述了如何将JSON传入和传出函数–您需要提供一个“schema”描述这个的元素
        3. 的“produces” and “consumes”元素设置为“application/json”
      4. 保存更新的定义。

      的best way to illustrate this is with a before and after – 在下面的定义中,您可以看到在编辑“parameters” and “responses”部分为空或最小。我添加了传递到这些部分的JSON对象的详细信息(以及其他一些附加信息):

      之前

      API的定义看起来不错之后,’是时候将其提供给使用它的地方了。

      Export your API to PowerAppsand Flow

      下一步是通过API在PowerApps / Flow / Logic Apps中定义自定义连接器–OpenAPI定义是此基础。您可以从Azure功能端或PowerApps / Flow端开始此过程。在PowerApps / Flow中,您可以执行以下操作:

      SNAGHTML57484ba

      SNAGHTML5740f2c

      或者,您可以从Azure函数开始。两种方法都可以得到相同的结果。在Azure方面,“API definition” area you’ll find this button:

      SNAGHTML5774987

      让’使用这种方法。执行此操作时,Azure要求您提供一些详细信息,以将OpenAPI定义与PowerApps / Flow链接–要小心,因为你可以’稍后重命名(不影响使用它的任何PowerApps / Flow):

      处理:

      1. 为您的API提供一个名称,并设置其他初始详细信息:
        SNAGHTML59cdaf6

        注意– in the “API Key Name” field above, I’m向连接器的用户提供有关如何获取密钥的提示(必须将其传递给后端的函数)。每当有人第一次使用连接器时,它就会出现。

        SNAGHTML57e4791
      2. 您的API现在将显示为“custom connector”在PowerApps或Flow中:
        SNAGHTML57f68ef    

      注意–连接器目前仅与您共享。为了使它能够由在您的组织中创建PowerApps / Flow的其他人使用,它也需要与他们(或每个人)共享。

      [OPTIONAL] Extending your API定义 for PowerApps/Flow/Logic Apps

      既然PowerApps / Flow知道您的API,那么您可以选择在PowerApps / Flow / Logic Apps方面使用该定义。这被称为“extending an OpenAPI”定义。 Microsoft对OpenAPI规范有一些特定的扩展,您可以使用它们做一些漂亮的事情,例如将参数标记为 “important” or “advanced” in the x-ms可见性 标签。使用时“advanced”例如,设置隐藏在“advanced” or “more” option, which might make 更多 sense for some of your 参数:

      图片

      的process of 扩展OpenAPI definition looks like this – and although it’从技术上讲是可选的,如果您的OpenAPI定义完美,那么您’我会经常发现这个过程非常适合 证实 您的定义并帮助您找到缺少的属性等。就我而言,我发现我的方法缺少需要添加的摘要:

      注意
      我们仍在此处编辑OpenAPI定义,您的更改保存在此处–但是,这不会返回到存储在您的Azure函数中的定义,而是PowerApps / Flow / Logic Apps拥有的版本。

    1. Click the edit button on your 定制连接器:
      SNAGHTML5a021a5
    2. 在“General”标签,提供说明(也许还有图标):
      SNAGHTML5a42a8b
    3. 在“Security”选项卡,保留默认值:
      SNAGHTML5a548eb
    4. 在“Definition”标签,您可能需要做一些工作-就我而言,在这里’在我发现我的方法最初发出警告的地方,因为它们对 概要。您’ll see an “Action”对于每个功能’重新暴露在您的API中–您可以看到我的提取和更新操作,例如:
      SNAGHTML5a6ed35
      逐个执行每个操作。添加所有缺少的详细信息并确保所有警告均已消失后,您应该深入查看“Body”:     
        SNAGHTML1385d187 [4]
      在这里,您应该检查JSON中要传递给您的API的各个数据位是否得到反映。就我而言’m返回用户个人资料信息,它看起来像这样: 
      SNAGHTML138845d3
      您 should also check the parameter validates OK:
        SNAGHTML13895f61
      一旦您’为您的所有方法完成此操作,然后保存更改:
      SNAGHTML138c6677
      您’现在可以在PowerApps / Flow / Logic Apps中使用您的API。

      在Flow中使用连接器

      在Flow设计器中时,您现在可以添加一个调用API的操作。如果创建或编辑流并搜索连接器,它将显示定义的操作(在我的情况下,获取或更新用户配置文件):

      SNAGHTMLbd8598e

      当然,我现在受益于易于使用的单独定义的字段(此处显示了我的更新操作):

      SNAGHTMLbd9eef3

      如果您通过执行触发操作来测试流程(I’m使用Postman进行HTTP POST调用),那么您应该会看到一切正常:
      SNAGHTMLbde557a

      SNAGHTMLbde9a62

      ..当然,我的Office 365配置文件确实已更新为以下值:

      SNAGHTMLbe0530f
          

      概要

      能够将自定义代码插入PowerApps / Flow / Logic Apps是现代Office 365架构师或开发人员的工具箱中的工具。您为函数或API创建OpenAPI定义,然后为其创建自定义连接器,以确保所有操作都得到验证,并且在POST正文中传递的参数是单独定义的。一旦您’在这一点上,您几乎可以在PowerApps和Flow中构建任何东西–太棒了!在我的示例中,我使用了一个自定义连接器,该连接器调用一个Azure函数,该函数调用该图–这可能是许多不同情况的基础。

      Waldek对此也有一些很好的信息,特别是关于可以用于长时间运行的异步连接器的信息。那里’是您的API返回的模型“location” and “retry-after”如果操作仍在进行中,则会向Flow标头,这会告诉Flow在X秒内再次进行检查(但是您在“retry-after”)。在某些情况下这可能非常有用,因此我建议阅读他的文章 关于构建Microsoft Flow连接器的知识。其他好的读物:

      没意见: