深入理解ApexREST与自定义Web服务

### 深入理解Apex REST与自定义Web服务 #### 1. 何时使用自定义端点 Salesforce提供了功能完备的标准REST API，对于自定义对象，它会自动为标准的CRUD操作提供端点。此外，该API还包含查询、运行可调用操作、描述sObject元数据等标准操作的端点，以及用于同时处理多个sObject的复合端点。然而，在某些场景下，构建自定义端点是有必要的。 ##### 1.1 替换旧有集成 当在一个组织中实施Salesforce，且存在使用旧有REST API的遗留解决方案时，旧系统的REST API很可能与Salesforce的标准REST API端点不匹配。这时有两个选择：一是更新现有应用程序以调用Salesforce API；二是在Salesforce上编写一个镜像现有端点的自定义API，使替换过程更简单。 如果缺乏更新现有解决方案代码库的开发技能，或者由于访问受限、成本过高等原因无法更新，那么在Salesforce上镜像现有API端点是明智之举。从架构角度看，这也是一种更简洁的解决方案，因为它不会将其他解决方案与Salesforce紧密绑定。 ##### 1.2 通用端点 标准的Salesforce端点要求调用它的解决方案了解Salesforce实例的数据结构。对于单个客户实例的集成，这通常不是问题。但如果通过AppExchange分发应用程序并希望API更公开可用，这可能就不太理想了。自定义API端点可以抽象掉Salesforce数据模式，提供更通用的端点。 例如，一个客户有两个不同的系统处理客户订单，一个处理商业零售订单，另一个处理消费者订单。一个更通用的自定义端点可以让客户从任一系统接收订单数据，并让Salesforce将数据解析为正确的模式，这也便于组织开发和改进订单捕获系统。 ##### 1.3 自定义逻辑或复杂端点 在将B2B和B2C订单存储在单个Salesforce环境的示例中，需要Salesforce端的逻辑来确定如何将提供的数据映射到Salesforce内的正确元数据项。例如，B2C性质的订单应存储在个人账户中，而B2B订单应存储在账户和联系人组合中。此外，API调用时可能需要在Salesforce内触发其他逻辑，如数据聚合、查询或DML操作。 与电子商务平台集成也是一个很好的例子。当客户在电子商务系统上下单时，我们希望订单信息能在Salesforce中创建一组记录。许多现代电子商务平台在下单或购物车放弃时会触发包含订单信息的Webhook。自定义Apex REST端点可以匹配电子商务平台提供的模式，构建Webhook端点并处理这些有效负载。 #### 2. 定义端点 所有作为Web服务公开的Apex类都需要定义为全局范围，以确保外部用户可见。要将类定义为Apex REST服务，必须使用`@RestResource`注解对类进行注解，并提供URL映射。以下是一个`/Example`端点的Apex类定义示例： ```apex @RestResource(urlMapping = '/Example/*') global with sharing class ApexRESTExample { } ``` 在类中，需要定义方法并使用适当的方法注解将其公开为HTTP方法。这些方法必须是静态的，因为它们在不实例化类的特定实例的情况下被调用。以下是一些带有所有必要注解的基本Apex方法示例： ```apex @RestResource(urlMapping = '/Example/*') global with sharing class ApexRESTExample { @HttpGet global static String getExampleResponse() { return 'Example'; } @HttpPost global static String postExampleResponse(String inputData) { return 'You posted ' + inputData; } @HttpPut global static String putExampleResponse(String inputData) { return 'You put ' + inputData; } @HttpPatch global static String patchExampleResponse(String inputData) { return 'You patched ' + inputData; } @HttpDelete global static String deleteExampleResponse() { return 'Example delete'; } } ``` 这个类提供了一个位于`/services/apexrest/Example`的端点，可处理所有不同的HTTP方法并提供响应。 Apex REST方法可以接受多种输入数据类型，包括： - Apex基元类型（不包括通用sObject类型和Blob） - sObjects - Apex基元类型或sObjects的列表或映射（注意映射的键类型必须是String） - Apex中成员变量为上述类型的用户定义类型 要将值传递给这些参数，需要在请求体中指定它们。在JSON中，示例如下： ```json {"inputData": "Test"} ``` 在XML中，示例如下： ```xml <request> <inputData>Test< ```