我们在做项目时经常会使用changeset作为部署工具,但是某些场景使用changeset会比较难操作,比如当我们在sandbox将apex class更改名字想要部署到生产的org或者其他环境的org,使用changeset是没法实现的,这个时候我们需要使用Ant Migration Tool还是更好的。
salesforce基于metadata进行管理,Ant Migration Tool 是一个基于 Java/Ant的命令行工具用于将metadata从本地迁移至Sales Org. Migration Tool通常用于以下场景:
- 开发的项目有很多的改动点,这些改动点使用Web界面可能需要花费很长时间;
- 多个阶段Release的发布:开发过程需要重复的构建,测试等才能发布到生产,脚本化的组件检索和部署会更高效;
- 重复部署相同的参数:可以检索出所有的metadata,进行更改,以及部署组件的子集;
- IT进行迁移到生产的操作:Force.com Migration Tool对于喜欢脚本化操作的人来说是一个很熟悉的过程;
- 定时调度部署。
Migration Tool基于Metadata API, Metadata API 包含了一组对象,这些对象用于管理你的org的系统预置的以及自定义的metadata, 我们可以使用SOAP calls来操作这些对象。下面介绍 Migration Tool 如何使用。
Migration Tool 使用前的准备工作
在我们使用Migration Tool时,我们需要保证电脑中已经安装了java的运行环境以及ant。由于salesforce对TLS1.0已经弃用,所以建议java JDK使用1.8(曾经java项目使用1.7,尽管按照要求各种配置了 tls信息仍然会有各种位置错误,使用1.8以后便一点问题没有了,所以推荐使用1.8)。
1. JDK 1.8 下载地址:https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html 按照要求下载以后正常安装即可,安装完如果想确认电脑中是否已经就绪JDK 1.8环境,可以打开命令行,输入 java -version 回车即可(需要配置java的jdk的环境变量,网上找一大堆,如果不配置,ant运行会有问题,因为找不到jdk位置);
2. 下载和配置 Ant: Ant下载地址: http://ant.apache.org/bindownload.cgi , 官方建议下载1.6 及以上版本,目前版本最高为1.10.5, 我这里下载的是这个版本,解压后我放在了C:antapache-ant-1.10.5文件夹下面了。当我们解压以后运行 ant -version后,会发现ant指令是未识别的命令
原因是bin目录以及lib目录用于运行ant指令,我们没有将bin目录放在path中。我们右键计算机,选择属性,选择高级,下面系统变量栏new一个,name为ANT_HOME,value为你解压的ant的根目录;
找到你的path的信息,新增%ANT_HOME%in即可,如果你的环境是win7,在最后需要加;然后输入下面信息
重新运行 ant -version,如果提示你安装的ant 安装的版本,说明安装成功。
3. 下载 Migration Tool,可以在你的org的setup 搜索出搜索 Tools,然后选择 Lightning Platform Tools and Toolkits.在跳转的页面选择下载Ant Migration Tools即可
二. Ant Migration Tool的使用
可以通过以下的步骤去实现 Ant Migration Tool的使用。
1. 配置 Salesforce Connection 信息
我们目的是为了检索和部署metadata组件,所以我们需要源及目标的登陆salesforce的账号以及密码等信息,这些信息配置在build.properties,这个文件存在于解压的 Ant Migration Tool 文件中。
配置信息主要有以下内容:
- sf.username : 用于配置的salesforce的账号名称;
- sf.password : 用于配置的salesforce的账号密码,如果存在security token,将token放在密码后面填写;
- sf.sessionId : 用于配置的salesforce的sessionId,如果配置sessionId,则不用配置username以及password,两者写一个就好,不能同时存在;
- sf.serverurl : 根据生产或者测试环境,分别对应于:https://login.salesforce.com / https://test.salesforce.com。
2.构建项目检索/部署清单
在package.xml中,我们主要需要配置以下的节点的信息:
- fullName:server端想要部署的package的名字,如果不指定则默认unpackage这个package;
- types:这个元素包含了一个name的标签以及多个members标签,用于逻辑哪些类型的哪些metadata组件需要被检索或者部署;
- members:组件元素的API名称;
- name:salesforce 规定的metadata type,可用的metadata type的取值需要参看:https://developer.salesforce.com/docs/atlas.en-us.200.0.api_meta.meta/api_meta/meta_types_list.htm
- version:文件用于检索和部署的metadata API的版本号。
上面的具体怎么使用,后面会给一个例子进行简单说明。
3. 使用Migration Tool 的指令从salesforce org检索/ 部署 / 移除 metadata组件
Ant的jar包里面封装了好多的soap的标准方法,常见的有 retrieve / deploy等等。通过ant指令在cmd中进行操作即可实现通过ant 部署salesforce的metadata组件。
三. Ant Migration Tool实际操作
下面通过一个例子来进行演示,例子浅入浅出,描述的是将我一个org里面的custom label全部迁移至另外一个org里面,然后再将指定的custom label从我的新的org删除(检索、部署以及删除操作的简单描述)。想要了解更多使用的小伙伴欢迎查看Ant Migration Tool的官方文档:https://resources.docs.salesforce.com/218/latest/en-us/sfdc/pdf/salesforce_migration_guide.pdf
上图中的内容为例子中的层级结构: My First Test中包含了两个文件夹:remove(用于指定移除的 destructureChanges.xml的metadata结构)、retrieve(用于指定需要检索部署的metadata结构)。
build.properties配置了登陆salesforce org A的账号信息,build.xml中用来配置你的操作指令。这里主要有三个部分:
- retrieveOperation:配置的检索的指令,当使用ant执行这个指令以后,会生成一个retrieveFolder的文件夹,并且读取retrieve/package.xml里面的metadata文件信息生成到retrieveFolder中
- deployOperation: 配置的执行的指令,当使用ant执行这个指令以后,会将retrieveFolder中的文件内容部署到你指定的salesforce org中;
- removeOperation:配置的删除的指令,当使用ant执行这个指令以后,会将 destructiveChanges.xml中的metadata移除。
1 <project name="Sample usage of Salesforce Ant tasks" default="test" basedir="." xmlns:sf="antlib:com.salesforce"> 2 3 <property file="build.properties"/> 4 <property environment="env"/> 5 6 <!-- Setting default value for username, password and session id properties to empty string 7 so unset values are treated as empty. Without this, ant expressions such as ${sf.username} 8 will be treated literally. 9 --> 10 <condition property="sf.username" value=""> <not> <isset property="sf.username"/> </not> </condition> 11 <condition property="sf.password" value=""> <not> <isset property="sf.password"/> </not> </condition> 12 <condition property="sf.sessionId" value=""> <not> <isset property="sf.sessionId"/> </not> </condition> 13 14 <taskdef resource="com/salesforce/antlib.xml" uri="antlib:com.salesforce"> 15 <classpath> 16 <pathelement location="../ant-salesforce.jar" /> 17 </classpath> 18 </taskdef> 19 20 21 <target name="retrieveOperation"> 22 <mkdir dir="retrieveFolder"/> 23 <sf:retrieve username="${sf.username}" password="${sf.password}" sessionId="${sf.sessionId}" serverurl="${sf.serverurl}" maxPoll="${sf.maxPoll}" retrieveTarget="retrieveFolder" pollWaitMillis="10000" unpackaged="retrieve/package.xml"/> 24 </target> 25 26 <target name="deployOperation"> 27 <sf:deploy username="${sf.username}" password="${sf.password}" sessionId="${sf.sessionId}" serverurl="${sf.serverurl}" maxPoll="${sf.maxPoll}" deployRoot="retrieveFolder" rollbackOnError="true"/> 28 </target> 29 30 <target name="removeOperation"> 31 <sf:deploy username="${sf.username}" password="${sf.password}" sessionId="${sf.sessionId}" serverurl="${sf.serverurl}" maxPoll="${sf.maxPoll}" deployRoot="remove"/> 32 </target> 33 34 </project>
salesforce org A:存在custom label
salesforce org B:不存在custom label
我们将retrieve文件夹下的package.xml中配置以下的内容,目的是读取所有的custom label
切换到 My First Test 文件夹下,执行 ant -p build.xml可以搜索出来当前目录下所有可以执行的ant的指令,因为我们在build.xml中只配置了3个,所以当前目录下ant的指令总共有3个。
执行 ant retrieveOperation便可以将所有的retrieve目录下的metadata xml信息检索出来
retrieveFolder中生成相关的文件信息以及package.xml文件
更改build.properties文件,切换成salesforce org B的账号,执行 ant deployOperation操作便可以将retrieveFolder中的metadata文件部署到salesforce org B中。
Salesforce Org B已经存在刚部署的metadata component了。
在remove文件夹中的destructiveChanges.xml中配置需要移除的metadata组件
执行 ant deleteOperation以后,便可以删除salesforce org B中的配置的metadata组件了。
salesforce org B已经移除指定的metadata组件
总结:篇中只是简单的描述Ant Migration Tool的使用,深入的细节的学习还是要自行查看官方提供的文档以及download下来的ant jar中的sample,篇中有问题的欢迎指出,有不懂的欢迎留言。