salesforce零基礎學習（九十二）使用Ant Migration Tool 實現Metadata遷移

ApacheAnt Salesforce · 發表 2019-02-18 00:42:00

摘要：我們在做專案時經常會使用changeset作為部署工具，但是某些場景使用changeset會比較難操作，比如當我們在sandbox將apex class更改名字想要部署到生產的org或者其他環境的org，使用changeset是沒法實現的，這個時候我們需要使用Ant Migration Too...

我們在做專案時經常會使用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 
 7so unset values are treated as empty. Without this, ant expressions such as ${sf.username}
 8will 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