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