今天介绍一下如果创建Custom API,我们首先需要知道它和action有什么区别,什么时候使用Custom API或者Action?
- Custom API和Action的区别
Create your own messages (Microsoft Dataverse) - Power Apps | Microsoft Learn
- 什么时候使用Custom API或者Action?
Custom API与Action在参数较少的情况下,性能类似,但随着参数的增加,action的性能会开始下降。并且Custom API相较于Action更易于维护,比如在参数维护这块。对于新开发的API,只要不是有特殊需求的,我们都可以使用Custom API;对于老的action,我们可以根据它目前的性能来决定是否转成Custom API。
如果需要将Action转成Custom API的话,可以使用XrmToolBox里的Custom Action to Custom API Converter工具。
我们使用Power Apps创建一个custom api需要通常需要创建创建三条记录在解决方案中:自定义 API, 自定义API请求参数,自定义API响应参数
1. 创建自定义API
- 我们需要有一个新的解决方案,或者使用已有的解决方案,这里我们创建一个新的解决方案来用来存放Custom API。
- 进入解决方案,新建 -> 更多 -> 其他 -> 自定义API(New > More > Other > custom API )
- 按照下面的截图去填写:
- 负责人:可以填写user或者team的引用
- 唯一名称:这个有填写规则,可以看我最后的注意事项
- 描述:描述该custom api
- 绑定类型:全局,实体,实体集合三种;如果想只针对某一个实体可用则选实体,并且在“绑定的实体逻辑名称”字段中填入实体的逻辑名称,比如:account; 全局的话“绑定的实体逻辑名称”字段为空。
- 是否为功能:如果为是则走http get请求不会改变数据,并且url的长度不能超过32768个字符;如果为否则走http post请求,可以修改数据。
- 允许的自定义处理步骤类型:这个我们选成"同步和异步"
- 插件类型:这个字段虽然不是必填的,但是当我们创建完成Custom API,并且为我们的Custom API写好了插件代码后,我们需要把这个插件填入进去,这个我会在之后的帖子里进行演示。
2. 创建自定义API请求参数
解决方案,新建 -> 更多 -> 其他 -> 自定义API请求参数(New > More > Other > Custom API Request Parameter)
建议自定义API请求参数的名称和显示名称前加上自定义API的名称来进行区分,这样在解决方案中看起来会更加直观。
有几个输入参数就需要创建几条自定义API请求参数记录。
3. 创建自定义API响应属性
解决方案,新建 -> 更多 -> 其他 -> 自定义API响应属性(New > More > Other > Custom API Response Property)
自定义API响应属性也一样建议在名称和显示名称前加上自定义API的名称来进行区分,这样在解决方案中看起来会更加直观。
有几个响应参数就需要创建几条自定义API响应属性记录。
4. 创建完成上面的几步之后,我们就可以通过查看元数据来检查我们创建的这个API了,但前提是我们没有在创建自定义API的时候将"为专用"字段设为是。
查看元数据的方法:https://<yourorg>.<yourcrm>.dynamics.com/api/data/v9.1/$metadata
需要注意上面查看元数据的方法只适用于Global的D365,如果你的D365是21V的,也就是中国区的,那和这个地址是不一样的。
上面这些步骤完成后,接下来就是为Custom API编写插件代码,并与Custom API进行关联了,这一步我会在之后的帖子里去说明。
注意
- 一旦Custom API创建后,有些字段就不可更改了,所以创建前需要谨慎填写
- 对于自定义API中的唯一名称:它的值必须包含与解决方案发布者的前缀相匹配的自定义前缀,并且必须以字母开头,而且只能由字母数字和_.{}!字符。比如后面的这几个都是不可以的:djgetaccountbyid, djgetaccountbyid@
- 对于自定义API中中的允许的自定义处理步骤类型,如果这个选为"无",我们在后续创建step步骤的时候是会失败的,而如果没有步骤我们是不能使用插件注册工具这种方式来进行调试的。
- 对于自定义API请求参数和自定义API响应属性:唯一名称不需要加前缀,并且调用api时的参数名称就是它
参考链接
Create and use custom APIs (Microsoft Dataverse) - Power Apps | Microsoft Learn
CustomAPI tables (Microsoft Dataverse) - Power Apps | Microsoft Learn
Create a custom API in Power Apps (Microsoft Dataverse) - Power Apps | Microsoft Learn