Salesforce Integration 概览(五) Remote Call-In（远程操作 外部->salesforce）

本篇参考：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集成模式的相关知识，这个集成模式实际场景也经常用到。篇中有错误地方欢迎指出，又不懂欢迎留言。