Power Automate

Power Automate 构建于 Azure Logic Apps 之上，在 Office 365 中提供了一种用户友好且专注的体验，一旦分配了适当的许可证，就可以轻松地让最终用户开始使用。当我们在创建自动化应用时，其实就是在定义一个工作流，该工作流描述了在你的应用中运行的实际逻辑，该工作流定义使用 JSON 定义，完整的工作流定义结构可以查看该文档：Schema reference guide for the Workflow Definition Language in Azure Logic Apps。

该工作流定义的主要组成部分包括：

  • parameters（参数）

  • triggers（触发器）

  • actions（动作）

  • outputs（输出）

我们在这里添加的步骤，就是以触发器开始的动作的组合排列，我们可以在每个步骤的菜单 Peek code 选项下查看该触发器或动作的 JSON 定义：

power-automate-peekcode

如果我们环境有 Dataverse，则可以使用 Dataverse 的 Web API 来查看管理 Flow，详见：Power Automate Web API

这里的 OAuth2 Scope 的资源 ID 和当前环境 URL 相同，例如：https://org9cd9d9a7.api.crm.dynamics.com/.default

没有 Dataverse，也可以统一使用工作流服务 Flow Service 来管理，参考：Everything to know about Power Automate REST API to manage and administer your flows

表达式

在定义工作流应用的步骤时，我们会大量用到表达式 Expression，该表达式以 @ 符号开头，可以包含任意多个函数（functions）、运算符（operators）、变量（variables）和常量等。

这里的表达式框中的内容就是除 @ 符号外的表达式主体：@concat('Hello', 'World', 'Power Automate')

power-automate-expression

常用符号

符号作用
'仅用单引号来表示字符串，例如，’’。不要使用双引号 ("")，这与整个表达式周围的 JSON 格式冲突。
[]使用方括号引用数组中特定位置（或索引）的值，例如：myArray[1]；也可以使用方括号获取对象属性路径下的值，例如：@parameters('userObject')['role/name']
.使用点运算符引用对象中的属性。例如，获取用户 JSON 对象下角色对象的名称属性："@parameters('userObject').role.name"
?要在没有运行时错误的情况下引用对象中的空属性，请使用问号运算符。例如，要处理触发器的空输出，您可以使用以下表达式：@coalesce(trigger().outputs?.body?.<someProperty>, '<property-default-value>')，换做方括号取值的方式也可以写作：@coalesce(trigger().outputs?['body']?['<someProperty>'], '<property-default-value>')

常用函数

在工作流中，我们通常会在表达式中使用函数来进行数据操作或者获取动态值，系统提供了大量的函数，可以参考该文档：Reference guide to workflow expression functions in Azure Logic Apps and Power Automate。

函数的使用和 JS 一样，语法为：@<functionName>(<item>)，符号 @ 代表该函数在表达式使用，例如：@parameters('customerName');

函数也可以嵌套使用：@<functionName2>(<functionName>(<item>))，例如：@concat(parameters('firstName'), parameters('lastName'));

也可以访问函数返回结果：@<functionName>(<item>).<propertyName>，例如：@outputs('Get_a_row_by_ID')?.body.new_name 或 @outputs('Get_a_row_by_ID')?['body/new_name']

工作流函数（Workflow functions）

在 Automate 中我们会大量用到工作流函数来：

  • 在运行时获取其它工作流步骤的详细信息
  • 用于工作流步骤的输入
  • 引用其它触发器和动作步骤的输出

例如获取触发器输出值：@triggerOutputs()?['body/_new_examtemplate_value']；

获取动作输出：@outputs('<actionName>')?['body/new_name']；

获取遍历项：@items('<applyToEachName>')['new_Score']

日期函数

Dateverse 和 Sharepoint 等接口返回的日期一般都存储的是 UTC 时区的日期格式，如果要基于日期来做判断或处理，通常会用到日期函数，例如：

  • 查看北京东八区日期：convertFromUtc(utcDateTime, 'China Standard Time', 'yyyy-MM-dd')

Dataverse 操作

在工作流中，我们可以使用 Dataverse 连接器来监听和操作数据，可以查看该文档了解该连接器功能详情：Microsoft Dataverse。

该连接器本质上是使用 Dataverse 的 Web API 来访问和操作数据，该 Web API 是实现 OData（开放数据协议）4.0 版本的 RESTful 风格的 API 。如果要使用程序代码访问该 API，可以在 https://www.odata.org/libraries/ 找到支持 OData 4.0 版的库列表，也可以通过 Postman 接口及文档快速学习 OData 协议。

对实体的数据操作符合 RESTful 风格，操作的资源名称为实体的 Entity Set Name，小写下划线复数形式。

获取实体定义元数据

在做任何操作之前，我们先必须了解我们的实体集的真实结构，通常通过 Web API 接口的服务文档来查看，它可以通过下图中的 API link to table definition 链接地址来访问。

然后我们可以从 Web API 的 Common Schema Definition Language (CSDL) $metadata 来查看元数据文档，这个文档是与 Web API 相关的所有内容的真实来源，例如所有的实体定义 EntityType、自定义接口 Action、自定义函数 Function 等等；

我们会经常需要查看该文档，想要查看某个实体的定义信息，可以通过搜索：EntityType Name="<name>"，name 为实体的 Logical Name。我们可以从表格的 Tools 工具栏的 Logic Name 复制，也可以查看表格属性的高级选项中的 Logic Name。

power-table-logic-name

power-entity-type-define

查找

查找可以直接使用 Web API，也可以使用 FetchXml，具体请查看链接文档。

查找 Lookup

要通过关联实体过滤数据，我们可以通过外键直接过滤，也可以通过 OData 嵌套属性的方式来过滤。

  • 关联实体的外键 ID 在实体属性中以：_<name>_value 的形式展示，name 为字段的 Logical Name，小写下划线单数形式。所以基于某个外键 ID 的查找就变为：

    GET [Organization URI]/api/data/v9.2/new_courseitemtemplates?$select=new_name&$filter=_new_coursetemplate_value eq '<courseTemplateGUID>'

  • 关联实体在上述文档中以 NavigationProperty 表示，要通过嵌套属性的方式来过滤数据，则变为：

    GET [Organization URI]/api/data/v9.2/new_courseitemtemplates?$select=new_name&$filter=new_CourseTemplate/new_coursetemplateid eq '<courseTemplateGUID>'

关联

最简单和最常用的方法是将 @odata.bind 注释附加到关联字段属性的名称后，然后将值设置为其他实体的 EntitySetName(<GUID>) 形式，例如设置上述课件的课程："[email protected]": "new_coursetemplates(ce9eaaef-f718-ed11-b83e-00224837179f)"。详情查看该文档。

SharePoint 操作

SharePoint 服务接口的文档地址前缀（site_url）一般格式为：https://<SharePointServerName>/sites/<SiteName>；

获取该站点某个 list 资源的接口则为：https://{site_url}/_api/web/lists/getbytitle('{list_name}')，该资源地址中也会包含它拥有的子资源链接地址，例如 Fields、Items、Views；

SharePoint 支持对资源有限的 OData 查询操作，具体查看文档：Use OData query operations in SharePoint REST requests；

在使用 API 请求数据时，首先也需要获取到 OAuth2 的 token，我们可以在 AAD 注册应用的 API permissions 中添加 SharePoint 的 AllSites.FullControl 权限，OAuth2 的 Scope 为资源唯一标识加权限名，例如该资源的默认权限：https://<SharePointServerName>/.default