本篇參考：https://resources.docs.salesforce.com/sfdc/pdf/integration_patterns_and_practices.pdf
本篇部落格介紹 Remote Call-In 整合模式，一言以蔽之：此種模式用於儲存在Lightning Platform中的資料由遠端系統建立、檢索、更新或刪除
先說一下針對 salesforce的 callout 以及 call in 。 簡單的來說, callout就是 salesforce call外部系統。 Call in 就是外部系統 call salesforce。此模式用於 外部系統 call salesforce的場景。
一. 上下文
我們在salesforce中走著sales cloud的流程，從 lead 轉換到 Account Opportunity，對Opportunity進行追蹤。當贏單以後建立訂單。 但是訂單由外部（遠端）系統管理。當訂單通過其處理階段時，遠端系統需要更新Salesforce中的訂單狀態。
上述的場景是官方的一個sample，當然除了這個場景以外，我們實際專案中這種例子比比皆是。
比如針對國內的專案，特別是銷售或者零售相關的操作，很多操作都是基於平板或者手機進行操作，然後實時或者點指定按鈕同步到salesforce端，這種都屬於 Remote Call-In的場景。
二. 問題和考慮因素
問題： 遠端系統如何與Salesforce連線並進行身份驗證，以通知Salesforce外部事件、建立記錄和更新現有記錄？
考慮因素：
- 遠端呼叫Salesforce的目的是使用事件驅動系統結構通知Salesforce外部發生的事件嗎？或者目的是對特定記錄執行操作？如果使用事件驅動系統結構，則事件生產者（遠端程式）將與Salesforce事件使用者分離。
- 對Salesforce的呼叫是否要求遠端程式在繼續處理之前等待響應？對Salesforce的遠端呼叫始終是同步的request-reply，但是如果不需要遠端程式來模擬非同步呼叫，則遠端程式可以放棄響應。
- 每個事務是針對單個Salesforce物件還是針對多個相關物件進行操作？
- 訊息的格式是什麼（例如，通過HTTP的SOAP或REST，或兩者）？
- 訊息大小是相對較小還是較大？
- 如果遠端系統支援SOAP，那麼遠端系統是否能夠參與契約優先(contract-first)方法？在使用SOAP API的地方，這是必需的，為此提供了預定義的WSDL。
- 是否需要進行transaction處理？
- 對Salesforce定製的容忍程度如何？是否有足夠的資源去做 salesforce的自定製
三. 解決方案
基於上述的問題和考慮因素，salesforce推薦了相關的解決方案，詳情如下表格所示
|
解決方案 |
適配程度 |
Comments |
|
SOAP API |
Best |
Salesforce提供了一個標準的SOAP API，遠端系統可以使用該API進行以下操作：
–釋出事件以通知您的Salesforce組織 –查詢組織中的資料 –建立、更新和刪除資料 –獲取組織的後設資料 –執行實用程式以執行管理任務 •同步API發出API呼叫後，遠端客戶端應用程式將等待，直到收到來自服務的響應。不支援對Salesforce的非同步呼叫。 •生成的WSDL Salesforce為遠端系統提供了兩個WSDL： –企業WSDL提供特定於Salesforce組織的強型別WSDL。 –合作伙伴WSDL包含一個鬆散型別的WSDL，它不是特定於Salesforce組織的。 •安全執行SOAP API的客戶端必須具有有效的登入名，並獲得會話以執行任何API呼叫。API尊重Salesforce中基於登入使用者配置檔案配置的物件級和欄位級安全性。 •事務/提交行為預設情況下，如果某些記錄標記有錯誤，則每個API呼叫都允許部分成功。這可以更改為“全部或無”行為，如果發生任何錯誤，將回滾所有結果。不可能跨多個API呼叫跨事務。為了克服這個限制，一個API呼叫可以影響多個物件。 •批量資料—任何包含2000條以上記錄的資料操作都是Bulk API 2.0成功準備、執行和管理使用批量框架的非同步工作流的理想選擇。少於2000條記錄的作業應該涉及REST（例如，複合）或SOAP中的“批量化”同步呼叫。 •事件驅動架構平臺事件的定義方式與Salesforce物件的定義方式相同。通過soapi釋出事件與建立Salesforce記錄相同。僅支援建立和插入操作。 |
|
REST API |
Best |
Salesforce提供了一個標準的REST API，遠端系統可以使用該API：
–釋出事件以通知您的Salesforce組織 –查詢組織中的資料 –建立、更新和刪除資料 –獲取組織的後設資料 –執行實用程式以執行管理任務 •同步API發出API呼叫後，遠端客戶端應用程式將等待，直到收到來自服務的響應。不支援對Salesforce的非同步呼叫。 •REST API與SOAP API-REST將資源（實體/物件）公開為URI，並使用HTTP謂詞定義對這些資源的CRUD操作。與SOAP不同，restapi不需要預定義的契約，使用XML和JSON進行響應，並且具有鬆散的型別。restapi是輕量級的，它提供了一種與Salesforce互動的簡單方法。它的優點包括易於整合和開發，是與移動應用程式和web應用程式配合使用的最佳選擇。 •安全執行REST API的客戶端必須具有有效的登入名，並獲得會話以執行任何API呼叫。API尊重Salesforce中基於登入使用者配置檔案配置的物件級和欄位級安全性。 •事務/提交行為預設情況下，每個記錄都被視為一個單獨的事務並分別提交。一個記錄更改失敗不會導致其他記錄更改回滾。此行為可以更改為“全有或全無”行為。使用restapi複合資源在一個API呼叫中進行一系列更新。 •REST複合資源使用這些REST API資源在單個API呼叫中執行多個操作。也可以使用一個呼叫的輸出作為下一個呼叫的輸入。請求的所有響應主體和HTTP狀態都在單個響應主體中返回。整個請求都算作一個符合API限制的呼叫。 •批量資料—任何包含2000條以上記錄的資料操作都是批量API 2.0成功準備、執行和管理使用批量框架的非同步工作流的理想選擇。少於2000條記錄的作業應該涉及REST（例如，複合）或SOAP中的“批量化”同步呼叫。 •事件驅動架構平臺事件的定義方式與Salesforce物件的定義方式相同。通過restapi釋出事件與建立Salesforce記錄相同。僅支援建立和插入操作。 |
|
Apex web services |
Suboptimal |
Apex類方法可以作為web服務方法公開給外部應用程式。此方法是SOAP API的替代方法，通常僅在必須滿足以下附加要求的情況下使用。
•需要全面的事務支援（例如，在一個事務中建立帳戶、聯絡人和機會）。 •在提交之前，必須在Salesforce端應用自定義邏輯。使用apexweb服務的好處必須與Salesforce中需要維護的額外程式碼進行權衡。不適用於Platform Event，因為使用者處的事務預插入邏輯不適用於基於事件驅動的體系結構。要通知Salesforce組織發生了事件，請使用SOAP API、REST API或Bulk API 2.0。 |
|
Apex REST services |
Suboptimal |
Apex類可以公開為對映到特定uri的REST資源，並使用針對它定義的HTTP謂詞（例如POST或GET）。您可以使用restapi複合資源在單個事務中執行多個更新。Apex REST服務與SOAP不同，它不需要客戶機使用服務定義/約定（WSDL）並生成客戶機存根。遠端系統只需要能夠形成HTTP請求並處理返回的結果（XML或JSON）。不適用於Platform Event，因為使用者處的事務預插入邏輯不適用於基於事件驅動的體系結構。要通知Salesforce組織發生了事件，請使用SOAP API、REST API或Bulk API 2.0。 |
|
Bulk API 2.0 |
Optimal for bulk operations |
bulkapi2.0基於REST原理，並針對載入或刪除大型資料集進行了優化。它與restapi具有相同的可訪問性和安全行為。任何包含超過2000條記錄的資料操作都是BulkAPI2.0成功準備、執行和管理利用Bulk框架的非同步工作流的理想選擇。少於2000條記錄的作業應該涉及REST（例如，複合）或SOAP中的“批量化”同步呼叫。bulkapi2.0允許客戶機應用程式通過提交Salesforce在後臺處理的大量批來非同步查詢、插入、更新、升級或刪除大量記錄。相比之下，soapi針對一次更新少量記錄的實時客戶機應用程式進行了優化。儘管SOAP-API也可以用於處理大量記錄，但當資料集包含數十萬到數百萬條記錄時，它就變得不太實用了。這是由於其相對較高的開銷和較低的效能特點。
•事件驅動架構平臺事件的定義方式與Salesforce物件的定義方式相同。通過批量API 2.0釋出事件與建立Salesforce記錄相同。僅支援建立和插入操作。批處理作業處理時，批處理中的事件將非同步釋出到Salesforce事件匯流排 |
四. 流程草圖
下圖說明了在使用RESTAPI（用於外部事件的通知）或SOAP API（用於查詢Salesforce物件）實現此模式時的事件序列。使用restapi時，事件的順序是相同的。
下圖為SOAP API流程
下圖為REST API流程
五. 其他關鍵點
1.呼叫機制：呼叫機制取決於為實現此模式而選擇的解決方案。
|
呼叫機制 |
描述 |
|
SOAP API |
遠端系統使用Salesforce企業或合作伙伴WSDL生成客戶機存根，這些存根反過來用於呼叫標準soapapi。 |
|
REST API |
遠端系統必須在訪問任何Apex REST服務之前進行身份驗證。遠端系統可以使用OAuth 2.0或使用者名稱/密碼身份驗證。在任何一種情況下，客戶機都必須使用適當的值設定授權HTTP頭（OAuth訪問令牌或會話ID可以通過對soapapi的登入呼叫獲得）。然後，遠端系統使用適當的動詞生成REST呼叫（HTTP請求），並處理返回的結果（支援JSON和XML資料格式）。 |
|
Apex web service |
遠端系統使用定製Apex web服務WSDL來生成客戶機存根，這些存根反過來用於呼叫定製Apex web服務。 |
|
Apex REST service |
根據restapi，資源URI和適用的謂詞是使用@RestResource、@HttpGet和@HttpPost註釋定義的。 |
|
Bulk API 2.0 |
bulkapi2.0是一個基於REST的API，因此應用了與restapi相同的呼叫機制。 |
|
REST API to invoke Flow |
使用restapi呼叫自定義invocable操作端點以呼叫自動啟動的流。 |
2.Error Handling & Recovery
整合就涉及到握手操作以及通過 token或者session等授權資訊進行SOQL Query或者資料的DML操作。以國內為例。因為salesforce在國內沒有伺服器，並且訪問很慢，基於SOAP / REST 標準的API都是同步操作，很容易經常碰到超時現象，除此以外，我們還要考慮DML的程式問題或者 validation rule / trigger等 addError的行為。針對 Error Handling以及 Recovery官方建議如下：
錯誤處理—所有遠端調入方法、標準或自定義API都要求遠端系統處理任何後續錯誤，例如超時和重試管理。必要情況下可以引入中介軟體，中介軟體可用於提供錯誤處理和恢復的邏輯。
恢復—如果服務質量要求要求，則需要建立自定義重試機制。在這種情況下，確保冪等設計特性非常重要。Platform Event使訂閱者能夠在訊息釋出後的特定時間段內使用replay ID獲取訊息
3.冪等性考慮：冪等函式功能保證重複呼叫是安全的，不會產生負面影響。如果未實現冪等性，則對同一訊息的重複呼叫可能會產生不同的結果，可能會導致資料完整性問題，例如，建立重複記錄、重複處理事務等。在發生錯誤或超時的情況下，遠端系統必須管理多個（重複）呼叫，以避免重複插入和冗餘更新（尤其是在觸發下游觸發器和工作流規則時）。雖然可以在Salesforce中管理其中一些情況（特別是在定製SOAP和REST服務的情況下），但我們建議遠端系統（或中介軟體）管理錯誤處理和冪等設計。
4.及時性以及資料量
及時性：SOAP API 以及Apex Web service API都是同步的操作，遵循著以下的 timeout limitation
Session timeout ：根據Salesforce組織的會話超時設定，如果沒有活動，會話將超時（不一定100%的貼近，比如session setting設定的2小時，有時候即使超過2小時也不會會話超時，有可能3、4小時以後才會超時，不絕對，但是要遵循最壞情況的處理原則）
Query timeout：每一個SOQL的查詢有一個獨立的120秒的限制。
資料量：資料量的考慮需要取決於我們採用了哪個方案，可以看一下下面的表格
|
解決方案 |
通訊型別 |
限制點 |
|
SOAP API或者REST API |
同步 |
SOAP Login： SOAP login request 大小要限制在10K以內。每個人每小時呼叫 login函式最多3600次，如果超過了這個限制，就會報錯 Create/ Update/ Delete：一次操作最多操作200條資料。如果運算元據超過了200條，需要多個call，但是需要保證每個call最多200條資料 Query Results Size： 通過呼叫 query()以及queryMore預設是500，最多可以2000. Event Message—最大事件訊息大小為1 MB。使用Salesforce API釋出事件將也計算在標準API限制中。 |
|
Bulk API 2.0 |
同步 |
Bulk API適用於運算元量超過2000條的情況，如果操作的數量超過了2000條，最好使用 bulk，而不是 SOAP/REST |
六： 常見考題
Universal Containers (UC) has integrations developed between Salesforce and back-end ERP applications. During peak load, UC is getting an error at the integration layer indicating, "Login Rate Exceeded". Which two recommendations would mitigate this issue?
Use a different user for each integration.
Cache the session ID to avoid a login call.
一個user1小時有最多3600次 login呼叫的限制，如果出現了 Login Rate Exceeded問題，要麼使用其他的賬號，要麼成功登入以後儲存session 資訊，減少 login方法的呼叫
總結：篇中主要介紹了Remote Call in整合模式的相關知識，這個整合模式實際場景也經常用到。篇中有錯誤地方歡迎指出，又不懂歡迎留言。