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 定义:
如果我们环境有 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')
常用符号
符号 | 作用 |
---|---|
' | 仅用单引号来表示字符串,例如,’’。不要使用双引号 (""),这与整个表达式周围的 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。
查找
查找可以直接使用 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