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

2022-12-08 08:39:07

我们在做项目时经常会使用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移除。

 <project name="Sample usage of Salesforce Ant tasks" default="test" basedir="." xmlns:sf="antlib:com.salesforce">

     <property file="build.properties"/>

     <property environment="env"/>

     <!-- Setting default value for username, password and session id properties to empty string

          so unset values are treated as empty. Without this, ant expressions such as ${sf.username}

          will be treated literally.

     -->

     <condition property="sf.username" value=""> <not> <isset property="sf.username"/> </not> </condition>

     <condition property="sf.password" value=""> <not> <isset property="sf.password"/> </not> </condition>

     <condition property="sf.sessionId" value=""> <not> <isset property="sf.sessionId"/> </not> </condition>

     <taskdef resource="com/salesforce/antlib.xml" uri="antlib:com.salesforce">

         <classpath>

             <pathelement location="../ant-salesforce.jar" />

         </classpath>

     </taskdef>

     <target name="retrieveOperation">

       <mkdir dir="retrieveFolder"/>

       <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"/>

     </target>

     <target name="deployOperation">

       <sf:deploy username="${sf.username}" password="${sf.password}" sessionId="${sf.sessionId}" serverurl="${sf.serverurl}" maxPoll="${sf.maxPoll}" deployRoot="retrieveFolder" rollbackOnError="true"/>

     </target>

   <target name="removeOperation">

       <sf:deploy username="${sf.username}" password="${sf.password}" sessionId="${sf.sessionId}" serverurl="${sf.serverurl}" maxPoll="${sf.maxPoll}" deployRoot="remove"/>

     </target>

 </project>