SugarCRM 是世界領先的開源 Customer Relationship Management (CRM) 軟件供應商，全世界擁有 5,000 位客戶，SugarCRM 應用程序的總下載次數高達 500,000 次。2009 年 12 月，SugarCRM 發布了其 5.5 版本的應用程序套件，該版本完全恢復了 Web Services 平台的生機。新版本中包含了一個更快、更易用的 API，能夠輕松擴展呈現給 Web 服務客戶機的 API ，並新增了 REST 支持。
什麼是 REST？
常用縮略詞
API：應用程序編程接口
CSS：層疊樣式表
DOM：文檔對象模型
Html：超文本標記語言
HTTP：超文本傳輸協議
JSON：JavaScript 對象符號
REST：具象狀態傳輸
RPC：遠程過程調用
URL：統一資源定位符
XML：可擴展標記語言
REST，代表 REpresentational State Transfer，旨在成為普通精益化 Web 服務協議。它的出現是對 SOAP 和 XML-RPC 等重量級 Web 服務協議的響應，這些重量級的 Web 服務協議依賴於一種預定義的消息傳遞格式和方法在服務器和客戶機之間來回傳遞協議。而 REST 沒有規定這些限制；您可以使用任何喜歡的消息格式（無論是 JSON、XML、Html、序列化數據還是純文本），並使用標准的 HTTP 動詞 GET、DELETE 和 POST 執行其操作。用於 REST 客戶機/服務器交互的規則可以完全通過應用程序要求定義。因此，如果要定義一個打算由 JavaScript 客戶機使用的 REST 接口，您也許希望數據以 JSON 格式返回；但是如果打算由 PHP 客戶機來使用數據，那麼序列化數據或 XML 也許是更好的選擇。
每個 REST Web 服務調用只是一個簡單的 HTTP 請求，使用標准的 HTTP 動詞。通常，您需要使用最適合當前操作的動詞：
GET 用於從服務器獲取數據。
POST 用於將數據發送到服務器。
DELETE 用於刪除服務器上的資源。
清單 1 展示了一個示例如何與 Yahoo! 交互。您可以通過 PHP 搜索 REST Web 服務（參見 下載 部分獲取本文使用的所有示例）。
清單 1. 在 PHP 中與 REST Web 服務交互的示例
<?PHP
// specify the REST web service to interact with
$url = 'http://search.yahooapis.com/WebSearchService/V1/
webSearch?appid=YahooDemo&query=sugarcrm';
// make the web services call; the results are returned in XML format
$resultsXML = file_get_contents($url);
// convert XML to a SimpleXML object
$xmlObject = simplexml_load_string($resultsXML);
// iterate over the object to get the title of each search result
foreach ( $XMLObject->Result as $result )
echo "{$result->Title}\n";
對於 清單 1 中的這個示例，使用 Yahoo Web Search Service 來搜索 sugarcrm。使用 PHP 函數 file_get_contents()，該函數使用指定的 URL 來執行 GET 請求。默認情況下，服務以 XML 字符串的形式返回查詢結果，然後 PHP SimpleXML 庫用於將該字符串解析為 PHP 對象，我們可以迭代該對象來獲取正在尋找的數據。
現在您已經了解了 REST Web 服務的工作方式，下面看看如何使用 SugarCRM 的 Web 服務接口與之交互。
使用 REST 連接到 SugarCRM
SugarCRM 提供一個開箱即用的 Web 服務接口，地址是：http://path_to_Sugar_instance/v2/rest.PHP。通過使用對該 URL 的 POST 請求來進行調用，將所需參數作為 POST 參數傳遞到該 Web 服務調用。對於與 Web 服務的每次交互，客戶機必須使用登錄方法調用來進行驗證，如 清單 2 所示。
清單 2. 通過 REST Web 服務接口登錄到 SugarCRM 實例
<?PHP
// specify the REST web service to interact with
$url = 'http://localhost/sugar/v2/rest.PHP';
// Open a curl session for making the call
$curl = curl_init($url);
// Tell curl to use HTTP POST
curl_setopt($curl, CURLOPT_POST, true);
// Tell curl not to return headers, but do return the response
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
// Set the POST arguments to pass to the Sugar server
$parameters = array(
'user_name' => 'user',
'password' => 'passWord',
);
$json = JSon_encode($parameters);
$postArgs = 'method=login&input_type=JSon&
response_type=json&rest_data=' . $JSon;
curl_setopt($curl, CURLOPT_POSTFIELDS, $postArgs);
// Make the REST call, returning the result
$response = curl_exec($session);
// Close the connection
curl_close($session);
// Convert the result from JSON format to a PHP array
$result = JSon_decode($response);
// Echo out the session id
echo $result['id'];
由於您需要對 Web 服務發送 POST 請求而非 GET 請求，因此應使用 PHP curl 庫而不是 file_get_contents() 來調用 Sugar Web 服務。然後，將用於這個 Web 服務調用的參數集合為一個數組，並將其編碼為 JSON 字符串。您需要指定用於這個 Web 服務調用的參數、方法（對於這個調用是 login）以及參數格式；參數格式使用 input_type POST 參數指定，可以是 json，也可以是 serialized。您還必須使用 response_type 參數指定期望返回的結果格式，這個參數可以是 json、rss 或 serialized；然後將該 Web 服務方法使用的 JSON 編碼的參數字符串指定為 rest_data。之後執行實際調用，並解碼從服務器返回的 JSON 字符串。對於該請求，我們主要關心的返回值是 id 參數，這個參數將用於後續的請求中，以便已經驗證的服務所在的服務器能夠識別客戶機。
創建一條新記錄
現在可以在 清單 2 中示例的基礎上構建，實際修改 Sugar Web 服務。在 清單 3 中，您將看到如何使用該接口將新記錄添加到 Accounts 模塊。
清單 3. 使用 REST Web 服務接口添加新帳戶
<?PHP
// specify the REST web service to interact with
$url = 'http://localhost/sugar/v2/rest.PHP';
// Open a curl session for making the call
$curl = curl_init($url);
// Tell curl to use HTTP POST
curl_setopt($curl, CURLOPT_POST, true);
// Tell curl not to return headers, but do return the response
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
// Set the POST arguments to pass to the Sugar server
$parameters = array(
'user_name' => 'user',
'password' => 'passWord',
);
$json = JSon_encode($parameters);
$postArgs = 'method=login&input_type=JSon&
response_type=json&rest_data=' . $JSon;
curl_setopt($curl, CURLOPT_POSTFIELDS, $postArgs);
// Make the REST call, returning the result
$response = curl_exec($session);
// Close the connection
curl_close($session);
// Convert the result from JSON format to a PHP array
$result = JSon_decode($response);
// Get the session id
$sessionId = $result['id'];
// Now, let's add a new Accounts record
$parameters = array(
'session' => $session,
'module' => 'Accounts',
'name_value_list' => array(
array('name' => 'name', 'value' => 'New Account'),
array('name' => 'description', 'value' => 'This is an
account created from a REST web services call'),
),
);
$json = JSon_encode($parameters);
$postArgs = 'method=set_entry&input_type=JSon&
response_type=json&rest_data=' . $JSon;
curl_setopt($curl, CURLOPT_POSTFIELDS, $postArgs);
// Make the REST call, returning the result
$response = curl_exec($session);
// Convert the result from JSON format to a PHP array
$result = JSon_decode($response);
// Get the newly created record id
$recordId = $result['id'];
登錄到 Web 服務後，進行第二個 Web 服務調用，這次是調用 set_entry Web 服務方法。將 login 方法返回的會話 ID 指定為 session 參數，將在其中添加記錄的模塊指定為 module 參數。name_value_list 參數是想為新創建的記錄設置的字段值的 “名稱/值” 對列表。然後調用該 Web 服務，並收到新創建記錄的記錄 ID。
您還可以通過再次調用 set_entry 方法來更新一條記錄，確保在 name_value_pair 列表中傳遞您想要更新的記錄 ID，如 清單 4 所示。
清單 4. 使用 REST Web 服務接口創建並更新聯系人
<?PHP
// specify the REST web service to interact with
$url = 'http://localhost/sugar/v2/rest.PHP';
// Open a curl session for making the call
$curl = curl_init($url);
// Tell curl to use HTTP POST
curl_setopt($curl, CURLOPT_POST, true);
// Tell curl not to return headers, but do return the response
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
// Set the POST arguments to pass to the Sugar server
$parameters = array(
'user_name' => 'user',
'password' => 'passWord',
);
$json = JSon_encode($parameters);
$postArgs = 'method=login&input_type=JSon&
response_type=json&rest_data=' . $JSon;
curl_setopt($curl, CURLOPT_POSTFIELDS, $postArgs);
// Make the REST call, returning the result
$response = curl_exec($session);
// Close the connection
curl_close($session);
// Convert the result from JSON format to a PHP array
$result = JSon_decode($response);
// Get the session id
$sessionId = $result['id'];
// Now, let's add a new Contacts record
$parameters = array(
'session' => $session,
'module' => 'Contacts',
'name_value_list' => array(
array('name' => 'first_name', 'value' => 'John'),
array('name' => 'last_name', 'value' => 'Mertic'),
),
);
$json = JSon_encode($parameters);
$postArgs = 'method=set_entry&input_type=JSon&
response_type=json&rest_data=' . $JSon;
curl_setopt($curl, CURLOPT_POSTFIELDS, $postArgs);
// Make the REST call, returning the result
$response = curl_exec($session);
// Convert the result from JSON format to a PHP array
$result = JSon_decode($response);
// Get the newly created record id
$recordId = $result['id'];
// Now let's update that record we just created
$parameters = array(
'session' => $session,
'module' => 'Contacts',
'name_value_list' => array(
array('name' => 'id', 'value' => $recordId),
array('name' => 'title', 'value' => 'Engineer'),
),
);
$json = JSon_encode($parameters);
$postArgs = 'method=set_entry&input_type=JSon&
response_type=json&rest_data=' . $JSon;
curl_setopt($curl, CURLOPT_POSTFIELDS, $postArgs);
// Make the REST call, returning the result
$response = curl_exec($session);
// Convert the result from JSON format to a PHP array
$result = JSon_decode($response);
// Get the record id of the record we just updated
$recordId = $result['id'];
在這個 清單 4 示例中，僅調用第二個 set_entry 方法來更新創建的記錄。這次，將要更新記錄的記錄 ID 指定為傳遞到這個 Web 服務方法調用的 name_value_list 參數中的一個條目，並將正在更新的每個字段條目作為調用的一部分（在本例中，將 title 字段值更新為 Engineer）。然後您發出請求，不出意外，這個記錄 ID 將返回，這是 Web 服務方法調用成功執行的標志。
創建多條記錄
要在一個模塊中創建多條記錄，可以使用 Web 服務方法 set_entrIEs 將對該 Web Services API 的調用數量減少到 1，而不是在一個循環中反復調用 set_entry，如 清單 5 所示。
清單 5. 通過一次方法調用在一個模塊中創建多條記錄
<?PHP
// specify the REST web service to interact with
$url = 'http://localhost/sugar/v2/rest.PHP';
// Open a curl session for making the call
$curl = curl_init($url);
// Tell curl to use HTTP POST
curl_setopt($curl, CURLOPT_POST, true);
// Tell curl not to return headers, but do return the response
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
// Set the POST arguments to pass to the Sugar server
$parameters = array(
'user_name' => 'user',
'password' => 'passWord',
);
$json = JSon_encode($parameters);
$postArgs = 'method=login&input_type=JSon&
response_type=json&rest_data=' . $JSon;
curl_setopt($curl, CURLOPT_POSTFIELDS, $postArgs);
// Make the REST call, returning the result
$response = curl_exec($session);
// Close the connection
curl_close($session);
// Convert the result from JSON format to a PHP array
$result = JSon_decode($response);
// Get the session id
$sessionId = $result['id'];
// Now, let's add a new Contacts record
$parameters = array(
'session' => $session,
'module' => 'Contacts',
'name_value_lists' =>
array(
array('name' => 'first_name', 'value' => 'John'),
array('name' => 'last_name', 'value' => 'Mertic'),
),
array(
array('name' => 'first_name', 'value' => 'Dominic'),
array('name' => 'last_name', 'value' => 'Mertic'),
),
array(
array('name' => 'first_name', 'value' => 'Mallory'),
array('name' => 'last_name', 'value' => 'Mertic'),
),
);
$json = JSon_encode($parameters);
$postArgs = 'method=set_entry&input_type=JSon&
response_type=json&rest_data=' . $JSon;
curl_setopt($curl, CURLOPT_POSTFIELDS, $postArgs);
// Make the REST call, returning the result
$response = curl_exec($session);
// Convert the result from JSON format to a PHP array
$result = JSon_decode($response);
// Get the newly created record ids as an array
$recordIds = $result['ids'];
set_entrIEs 的參數與 set_entry 基本相同，但有一個例外：這個方法不使用 name_value_list 參數，而是使用 name_value_lists 參數，這個參數是使用 Web Services API 創建的多條記錄的一個關聯數組。已創建記錄的記錄 ID 在 ids 參數中作為數組返回，數組中記錄 ID 的順序與在參數列表中傳送它們的順序相同。
關聯記錄
SugarCRM 的一個主要特性是能夠使記錄相互關聯。這種關系的一個示例是 Account 和 Contact 之間的關系：SugarCRM 中的每個 Account 可以與一個或多個 Contact 關聯。可以使用 Web 服務框架來完整地構建這種關系，如 清單 6 所示。
清單 6. 使用 REST Web Services API 關聯 Account 和 Contact
<?PHP
// specify the REST web service to interact with
$url = 'http://localhost/sugar/v2/rest.PHP';
// Open a curl session for making the call
$curl = curl_init($url);
// Tell curl to use HTTP POST
curl_setopt($curl, CURLOPT_POST, true);
// Tell curl not to return headers, but do return the response
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
// Set the POST arguments to pass to the Sugar server
$parameters = array(
'user_name' => 'user',
'password' => 'passWord',
);
$json = JSon_encode($parameters);
$postArgs = 'method=login&input_type=JSon&
response_type=json&rest_data=' . $JSon;
curl_setopt($curl, CURLOPT_POSTFIELDS, $postArgs);
// Make the REST call, returning the result
$response = curl_exec($session);
// Close the connection
curl_close($session);
// Convert the result from JSON format to a PHP array
$result = JSon_decode($response);
// Get the session id
$sessionId = $result['id'];
// Now, let's add a new Accounts record
$parameters = array(
'session' => $session,
'module' => 'Accounts',
'name_value_list' => array(
array('name' => 'name', 'value' => 'New Account'),
array('name' => 'description', 'value' => 'This is an
account created from a REST web services call'),
),
);
$json = JSon_encode($parameters);
$postArgs = 'method=set_entry&input_type=JSon&
response_type=json&rest_data=' . $JSon;
curl_setopt($curl, CURLOPT_POSTFIELDS, $postArgs);
// Make the REST call, returning the result
$response = curl_exec($session);
// Convert the result from JSON format to a PHP array
$result = JSon_decode($response);
// Get the newly created Account record id
$accountId = $result['id'];
// Now, let's add a new Contacts record
$parameters = array(
'session' => $session,
'module' => 'Contacts',
'name_value_list' => array(
array('name' => 'first_name', 'value' => 'John'),
array('name' => 'last_name', 'value' => 'Mertic'),
),
);
$json = JSon_encode($parameters);
$postArgs = 'method=set_entry&input_type=JSon&
response_type=json&rest_data=' . $JSon;
curl_setopt($curl, CURLOPT_POSTFIELDS, $postArgs);
// Make the REST call, returning the result
$response = curl_exec($session);
// Convert the result from JSON format to a PHP array
$result = JSon_decode($response);
// Get the newly created Contact record id
$contactId = $result['id'];
// Now let's relate the records together
$parameters = array(
'session' => $session,
'module_id' => $accountId
'module_name' => 'Accounts',
'link_fIEld_name' => 'contacts',
'related_ids' => array($contactId),
);
$json = JSon_encode($parameters);
$postArgs = 'method=set_relationship&input_type=JSon&
response_type=json&rest_data=' . $JSon;
curl_setopt($curl, CURLOPT_POSTFIELDS, $postArgs);
// Make the REST call
$response = curl_exec($session);
創建需要關聯的 Account 和 Contact 之後，構建請求調用 set_relationship Web 服務方法。然後，傳遞以下參數：
session 參數，用於獲取 Web 服務會話的會話 ID。
module_name 參數，用於獲取關系的主模塊。
module_id 參數，用於獲取將作為關系基礎的模塊中的記錄 ID。
link_fIEld_name 參數，用於獲取模塊中用於鏈接到其他模塊的關系的名稱（在本例中，關系名為 contacts）。
最後，指定一個記錄 ID 列表，這個列表將關聯到指定的模塊記錄。執行調用後，這種關系就會建立。
這只是大量可用 Web 服務方法的冰山一角；您可以查閱 SugarCRM Developer Documentation，了解可用 Web 服務方法的完整列表。
結束語
在本文中，我們了解了 SugarCRM 5.5 中的一個新特性，即 Sugar Web 服務框架的 REST 接口。首先了解了 REST Web 服務的工作方式，然後，查看了幾個運用 Sugar Web 服務框架 REST 接口的示例。我們學習了如何向模塊添加新記錄，以及如何修改該記錄。還學習了如何通過一個方法調用添加多條記錄，避免了連續執行多個遠程服務器調用的開銷。最後，我們了解了如何使用 Web 服務框架的 set_relationship 方法來關聯兩個不同的記錄。
本文示例源代碼或素材下載