salesforce零基础学习（九十二）使用Ant Migration Tool 实现Metadata迁移

咱们在作项目时常常会使用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:\ant\apache-ant-1.10.5文件夹下面了。当咱们解压之后运行 ant -version后，会发现ant指令是未识别的命令

缘由是bin目录以及lib目录用于运行ant指令，咱们没有将bin目录放在path中。咱们右键计算机，选择属性，选择高级，下面系统变量栏new一个，name为ANT_HOME，value为你解压的ant的根目录；

找到你的path的信息，新增%ANT_HOME%\bin便可，若是你的环境是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>

build.xml

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，篇中有问题的欢迎指出，有不懂的欢迎留言。