Salesforce API(9)Web服务

学习目标

完成本单元后,您将能够:

  • 描述两种类型的Apex Web服务并提供这些服务的高级概述。
  • 创建一个包含每个HTTP方法的方法的Apex REST类。
  • 使用端点调用自定义的Apex REST方法。
  • 通过以JSON格式发送请求主体,将数据传递给自定义的Apex REST方法。
  • 编写Apex REST方法的测试方法,并在测试REST请求中设置属性。
  • 通过调用具有参数值的方法编写Apex REST方法的测试方法。

将Apex类公开为Web服务

您可以将Apex类方法公开为REST或SOAP Web服务操作。通过使您的方法可以通过Web进行调用,您的外部应用程序可以与Salesforce集成以执行各种漂亮的操作。
例如,假设贵公司的呼叫中心正在使用内部应用程序来管理本地资源。预计客户支持代表将使用相同的应用程序来执行其日常工作,包括管理Salesforce中的案例记录。通过使用一个接口,代表可以查看和更新​​案例记录并访问内部资源。该应用程序调用Apex Web服务类来管理Salesforce案例记录。

公开一个类作为REST服务

使您的Apex类可用作REST Web服务非常简单。定义您的类为全局,并将方法定义为全局静态。为类和方法添加注释。例如,此示例Apex REST类使用一种方法。 getRecord方法是一个自定义的REST API调用。它使用@HttpGet进行注释,并被GET请求调用。

@RestResource(urlMapping='/Account/*')
global with sharing class MyRestResource {
    @HttpGet
    global static Account getRecord() {
        // 添加你的代码
    }
}
正如你所看到的,这个类用@RestResource注解(urlMapping =’/ Account / *)。 Apex REST的基本端点是https://yourInstance.salesforce.com/services/apexrest/。 URL映射附加到基本端点以形成REST服务的端点。例如,在类示例中,REST端点是https://yourInstance.salesforce.com/services/apexrest/Account/。对于您的组织,它可能看起来像https://yourInstance.salesforce.com/services/apexrest/Account/。

URL映射区分大小写,可以包含通配符(*)。

将每个暴露的方法定义为全局静态,并添加注释以将其与HTTP方法相关联。以下注释可用。每个Apex类中只能使用一次每个注释。

注解 行动 细节
@HttpGet Read 读取或检索记录。
@HttpPost Create 创建记录。
@HttpDelete Delete 删除记录。
@HttpPut Upsert 通常用于更新现有记录或创建记录。
@HttpPatch Update 通常用于更新现有记录中的字段。

公开一个类作为SOAP服务

使您的Apex类作为SOAP Web服务可用,就像使用REST一样简单。将您的课程定义为全球课程。将webservice关键字和静态定义修饰符添加到您要公开的每个方法。 webservice关键字提供对其添加方法的全局访问权限。

例如,这里有一个方法的示例类。 getRecord方法是一个定制的SOAP API调用,它返回一个Account记录。

global with sharing class MySOAPWebService {
    webservice static Account getRecord(String id) {
        // 添加你的代码
    }
}

外部应用程序可以通过使用类WSDL文件来调用您的自定义Apex方法作为Web服务操作。从类详细信息页面为您的类生成此WSDL,可从“安装程序”中的“Apex类”页面进行访问。通常,您可以将WSDL文件发送给第三方开发人员(或者自己使用)来编写Web服务的集成。

由于平台安全性是一流的Salesforce公民,因此您的Web服务需要身份验证。除了Apex类WSDL外,外部应用程序还必须使用Enterprise WSDL或Partner WSDL作为登录功能。

Apex REST演练

现在有趣的东西。接下来的几个步骤将引导您完成构建Apex REST服务的过程。首先,创建作为REST服务公开的Apex类。然后你尝试从客户端调用几个方法,最后编写单元测试。有相当多的代码,但这将是值得的努力!
您的Apex课程管理案例记录。该类包含五个方法,每个方法对应一个HTTP方法。例如,当客户端应用程序调用GET HTTP方法的REST调用时,将调用getCaseById方法。

由于该类是使用/ Cases / *的URL映射定义的,因此用于调用此REST服务的端点是以https://yourInstance.salesforce.com/services/apexrest/Cases/开头的任何URI。

我们建议您也考虑对API端点进行版本控制,以便在不破坏现有代码的情况下提供功能升级。您可以创建两个指定 /Cases/v1/*/Cases/v2/* 的URL映射的类来实现此功能。

让我们开始创建一个Apex REST类。

  1. 从设置档(打开设备齿轮图标Setup gear icon)打开开发者控制台。
  2. 在开发者控制台中,选择 File | New | Apex Class.
  3. 对于课程名称,输入CaseManager,然后单击 OK.
  4. 将自动生成的代码替换为以下类定义。
    @RestResource(urlMapping='/Cases/*')
    global with sharing class CaseManager {
    
        @HttpGet
        global static Case getCaseById() {
            RestRequest request = RestContext.request;
            // 从URL的末尾抓取caseId
            String caseId = request.requestURI.substring(
              request.requestURI.lastIndexOf('/')+1);
            Case result =  [SELECT CaseNumber,Subject,Status,Origin,Priority
                            FROM Case
                            WHERE Id = :caseId];
            return result;
        }
    
        @HttpPost
        global static ID createCase(String subject, String status,
            String origin, String priority) {
            Case thisCase = new Case(
                Subject=subject,
                Status=status,
                Origin=origin,
                Priority=priority);
            insert thisCase;
            return thisCase.Id;
        }   
    
        @HttpDelete
        global static void deleteCase() {
            RestRequest request = RestContext.request;
            String caseId = request.requestURI.substring(
                request.requestURI.lastIndexOf('/')+1);
            Case thisCase = [SELECT Id FROM Case WHERE Id = :caseId];
            delete thisCase;
        }     
    
        @HttpPut
        global static ID upsertCase(String subject, String status,
            String origin, String priority, String id) {
            Case thisCase = new Case(
                    Id=id,
                    Subject=subject,
                    Status=status,
                    Origin=origin,
                    Priority=priority);
            // 通过Case Id匹配,如果存在的话。
            // 否则,创建新的案例。
            upsert thisCase;
            // 返回案例ID。
            return thisCase.Id;
        }
    
        @HttpPatch
        global static ID updateCaseFields() {
            RestRequest request = RestContext.request;
            String caseId = request.requestURI.substring(
                request.requestURI.lastIndexOf('/')+1);
            Case thisCase = [SELECT Id FROM Case WHERE Id = :caseId];
            // 将JSON字符串反序列化为名称 - 值对
            Map<String, Object> params = (Map<String, Object>)JSON.deserializeUntyped(request.requestbody.tostring());
            // 遍历每个参数字段和值
            for(String fieldName : params.keySet()) {
                // 设置Case sObject的字段和值
                thisCase.put(fieldName, params.get(fieldName));
            }
            update thisCase;
            return thisCase.Id;
        }    
    
    }
  5. 按下CTRL + S保存。

使用POST方法创建一个记录

让我们使用您刚刚创建的Apex REST类,并获得一些乐趣。首先,我们将调用POST方法来创建一个案例记录。
要调用您的REST服务,您需要使用… REST客户端!几乎可以使用任何REST客户端,例如您自己的API客户端,cURL命令行工具或PHP的curl库。我们将使用Workbench工具作为我们的REST客户端应用程序,但稍后我们将会看看cURL。

Apex REST支持两种格式来表示资源:JSON和XML。 JSON表示在请求或响应的主体中默认传递,格式由HTTP头中的Content-Type属性指示。由于JSON比XML更易于阅读和理解,因此该设备仅使用JSON。在这一步中,您将以JSON格式发送案例记录。

Apex REST支持OAuth 2.0和会话认证机制。简而言之,这意味着我们使用行业标准来保证您的应用程序和数据安全。幸运的是,您可以使用Workbench来简化测试。 Workbench是一个功能强大的基于Web的工具套件,供管理员和开发人员通过Force.com API与组织进行交互。使用Workbench,您在使用您的用户名和密码登录到Salesforce时使用会话身份验证。而您使用REST资源管理器来调用您的REST服务。

  1. 导航到 https://workbench.developerforce.com/login.php.
  2. 对于环境,请选择 Production.
  3. 从“API版本”下拉列表中选择最新的API版本。
  4. 接受服务条款,然后单击 Login with Salesforce.
  5. 要允许工作台访问您的信息,请单击 Allow.
  6. 输入您的登录凭据,然后单击 Log in to Salesforce.
  7. 登录后,选择 utilities | REST Explorer.
  8. 选择 POST.
  9. REST Explorer接受的URL路径相对于您的组织的实例URL。仅提供追加到实例URL的路径。在相对URI输入字段中,将缺省URI替换为/services/apexrest/Cases/.
  10. 对于请求主体,插入要插入的对象的以下JSON字符串表示形式。
    {
      "subject" : "Bigfoot Sighting!",
      "status" : "New",
      "origin" : "Phone",
      "priority" : "Low"
    }
  11. 点击 Execute.
    该调用调用与POST HTTP方法关联的方法,即createCase方法。
  12. 要查看返回的响应,请单击 Show Raw Response.
    返回的响应与此响应类似。该响应包含新案例记录的ID。您的ID值可能与50061000000t7kYAAQ不同。保存您的ID值以便在下一步中使用。

    HTTP/1.1 200 OK
    Date: Wed, 07 Oct 2015 14:18:20 GMT
    Set-Cookie: BrowserId=F1wxIhHPQHCXp6wrvqToXA;Path=/;Domain=.salesforce.com;Expires=Sun, 06-Dec-2015 14:18:20 GMT
    Expires: Thu, 01 Jan 1970 00:00:00 GMT
    Content-Type: application/json;charset=UTF-8
    Content-Encoding: gzip
    Transfer-Encoding: chunked
    
    "50061000000t7kYAAQ" 

使用自定义GET方法检索数据

按照以前类似的步骤,使用Workbench来调用GET HTTP方法。

  1. 在Workbench中,选择 GET.
  2. 输入URI /services/apexrest/Cases/<Record ID>,将 <Record ID> 替换为您在上一步中创建的记录的ID。
  3. 点击 Execute.

    该调用调用与GET HTTP方法关联的方法,即getCaseById方法。

  4. 要查看返回的响应,请单击 Show Raw Response.

    返回的响应与此响应类似。响应包含为新的案例记录查询方法的字段。

    HTTP/1.1 200 OK
    Date: Wed, 07 Oct 2015 14:28:20 GMT
    Set-Cookie: BrowserId=j5qAnPDdRxSu8eHGqaRVLQ;Path=/;Domain=.salesforce.com;Expires=Sun, 06-Dec-2015 14:28:20 GMT
    Expires: Thu, 01 Jan 1970 00:00:00 GMT
    Content-Type: application/json;charset=UTF-8
    Content-Encoding: gzip
    Transfer-Encoding: chunked
    
    {
      "attributes" : {
        "type" : "Case",
        "url" : "/services/data/v34.0/sobjects/Case/50061000000t7kYAAQ"
      },
      "CaseNumber" : "00001026",
      "Subject" : "Bigfoot Sighting!",
      "Status" : "New",
      "Origin" : "Phone",
      "Priority" : "Low",
      "Id" : "50061000000t7kYAAQ"
    }
    

使用cURL检索数据

每个好的开发者至少应该知道三件事:1)如何制作一个自己动画的GIF,吃自己喜欢的冰淇淋; 2)pi的值到小数点后25位; 3)如何使用cURL。前两个超出了本模块的范围,所以我们将专注于最后一个。

cURL是一个使用URL语法获取或发送文件的命令行工具。使用REST端点时,它非常方便。您可以使用cURL来调用GET HTTP方法,而不是使用Workbench作为Apex REST服务。每当您“ROCK”您的REST端点时,您传递会话ID进行授权。在Workbench中工作时,你被宠坏了,因为在你登录之后,它会在你的封面下传递会话ID。

要获取会话ID,您首先在Salesforce组织中创建一个连接的应用程序并启用OAuth。在这种情况下,您的客户端应用程序cURL使用连接的应用程序连接到Salesforce。按照这些说明创建一个连接的应用程序,为您提供消费者密钥和消费者密钥,您需要获得您的会话ID。为连接的应用程序选择OAuth范围时,请选择“访问和管理数据(api)”范围。连接的应用程序可能需要5到10分钟才能完成设置。准备就绪后,对凭证和连接的应用程序使用以下cURL命令。

curl -v https://login.salesforce.com/services/oauth2/token -d "grant_type=password" -d "client_id=<your_consumer_key>" -d "client_secret=<your_consumer_secret>" -d "username=<your_username>" -d "password=<your_password_and_security_token>" -H 'X-PrettyPrint:1'
如果全部成功,则结果包含access_token,这是您的组织的会话ID和instance_url。

cURL response with access token

现在输入您的cURL命令(将与以下内容类似),以调用您的Apex REST服务并返回案例信息。

curl https://yourInstance.salesforce.com/services/apexrest/Cases/<Record_ID> -H 'Authorization: Bearer <your_session_id>' -H 'X-PrettyPrint:1'
按Enter后,您会看到类似于以下内容的内容。现在你已经是一个命令行的主人,随心所欲地为你的内容添加cURL,jq,sed,awk和grep。有关cURL的更多信息,请参阅参考资料部分。

cURL and response from the command line

使用自定义PUT或PATCH方法更新数据

您可以使用PUT或PATCH HTTP方法更新记录。 PUT方法要么更新整个资源(如果存在的话),要么创建资源(如果它不存在)。 PUT本质上是一个upsert方法。 PATCH方法只更新现有资源的指定部分。在Apex中,更新操作只更新指定的字段,不覆盖整个记录。我们将编写一些Apex代码来确定我们的方法是更新还是上传。

使用PUT方法更新数据

您添加到CaseManager类的upsertCase方法实现了PUT操作。这里包括这个方法供您参考。该方法使用内置的upsert Apex DML方法通过匹配ID值来创建或覆盖大小写记录字段。如果在请求的主体中发送了一个ID,则会使用它填充案例sObject。否则,创建没有ID的案例sObject。 upsert方法用填充的case sObject调用,DML语句做其余部分。瞧!

@HttpPut
global static ID upsertCase(String subject, String status,
    String origin, String priority, String id) {
    Case thisCase = new Case(
        Id=id,
        Subject=subject,
        Status=status,
        Origin=origin,
        Priority=priority);
    // 通过Id匹配大小写,如果存在的话。
    // 否则,创建新的案例。
    upsert thisCase;
    // 返回案例ID。
    return thisCase.Id;
}
要调用PUT方法:

  1. 在Workbench REST Explorer中,选择 PUT.
  2. 对于URI,输入 /services/apexrest/Cases/.
  3. upsertCase方法期望字段值在请求主体中传递。为请求主体添加以下内容,然后将<Record ID>替换为您之前创建的案例记录的ID。
    {
      "id": "<Record_ID>",
      "status" : "Working",
      "subject" : "Bigfoot Sighting!",
      "priority" : "Medium"
    }

    注意

    ID字段是可选的。要创建案例记录,请忽略此字段。在我们的例子中,你传递这个字段是因为你想更新案例记录。

  4. 点击 Execute.

    该请求从您的REST服务调用upsertCase方法。状态,主题和优先级字段被更新。即使主题的值与旧主题相匹配,主题也会更新。此外,由于请求主体不包含“案例源”字段的值,因此upsertCase方法中的origin参数为null。因此,记录更新时,“原始”字段将被清除。

    要检查这些字段,请通过导航到 https://yourInstance.salesforce.com/<Record ID>中查看此记录。

使用PATCH方法更新数据

作为PUT方法的替代方法,使用PATCH方法更新记录字段。你可以用不同的方式实现PATCH方法。一种方法是在方法中指定参数以更新每个字段。例如,您可以创建一个方法来更新具有以下签名的案例的优先级:updateCasePriority(String priority)。要更新多个字段,可以列出所有需要的字段作为参数。

提供更多灵活性的另一种方法是将字段作为请求主体中的JSON名称/值对传递。这种方法可以接受任意数量的参数,并且参数在方法的签名中不固定。这种方法的另一个优点是没有字段被意外清除,因为是空的。您添加到CaseManager类的updateCaseFields方法使用第二种方法。此方法将请求正文中的JSON字符串反序列化为名称/值对映射,并使用sObject PUT方法设置字段。

@HttpPatch
global static ID updateCaseFields() {
    RestRequest request = RestContext.request;
    String caseId = request.requestURI.substring(
        request.requestURI.lastIndexOf('/')+1);
    Case thisCase = [SELECT Id FROM Case WHERE Id = :caseId];
    // 将JSON字符串反序列化为名称 - 值对
    Map<String, Object> params = (Map<String, Object>)JSON.deserializeUntyped(request.requestbody.tostring());
    // 遍历每个参数字段和值
    for(String fieldName : params.keySet()) {
        // 设置Case sObject的字段和值
        thisCase.put(fieldName, params.get(fieldName));
    }
    update thisCase;
    return thisCase.Id;
}
要调用PATCH方法:

  1. 在Workbench REST Explorer中,单击 PATCH.
  2. 对于URI,输入 /services/apexrest/Cases/<Record ID>. 将<Record ID> 替换为先前创建的案例记录的ID。在请求正文中输入以下JSON。
    {
      "status" : "Escalated",
      "priority" : "High"
    }
    这个JSON有两个字段值:状态和优先级。 updateCaseFields方法从提交的JSON中检索这些值,并用于指定要在对象中更新的字段。
  3. 点击 Execute.

    该请求调用REST服务中的updateCaseFields方法。案例记录的状态和优先级字段被更新为新值。要检查这些字段,请通过导航到https://yourInstance.salesforce.com/<Record ID>在Salesforce中查看此记录。

测试您的Apex REST类

测试您的Apex REST类与测试其他Apex类相似,只需传入参数值即可调用类方法,然后验证结果。对于不接受参数或依赖REST请求中的信息的方法,创建一个测试REST请求。
一般来说,以下是测试Apex REST服务的方法。要模拟REST请求,请在测试方法中创建RestRequest,然后按如下方式在请求上设置属性。您也可以在请求中添加“通过”的参数来模拟URI参数。
// 设置一个测试请求
RestRequest request = new RestRequest();

// 设置请求属性
request.requestUri =
    'https://yourInstance.salesforce.com/services/apexrest/Cases/'
    + recordId;
request.httpMethod = 'GET';

// 设置其他属性,如参数
request.params.put('status', 'Working');

// 更令人敬畏的代码在这里...
// 最后,如果使用,将请求分配给RestContext
RestContext.request = request;
如果您正在测试的方法通过RestContext访问请求值,则将请求分配给RestContext以填充它(RestContext.request = request;)。

现在,让我们将整个课程保存在Developer Console中,然后运行结果。

  1. 在开发者控制台中,选择 File | New | Apex Class.
  2. 对于类名称,输入CaseManagerTest,然后单击 OK.
  3. 将自动生成的代码替换为以下类定义。
    @IsTest
    private class CaseManagerTest {
    
        @isTest static void testGetCaseById() {
            Id recordId = createTestRecord();
            // 设置一个测试请求
            RestRequest request = new RestRequest();
            request.requestUri =
                'https://yourInstance.salesforce.com/services/apexrest/Cases/'
                + recordId;
            request.httpMethod = 'GET';
            RestContext.request = request;
            // 调用测试方法
            Case thisCase = CaseManager.getCaseById();
            // 验证结果
            System.assert(thisCase != null);
            System.assertEquals('Test record', thisCase.Subject);
        }
    
        @isTest static void testCreateCase() {
            // 调用测试方法
            ID thisCaseId = CaseManager.createCase(
                'Ferocious chipmunk', 'New', 'Phone', 'Low');
            // 验证结果
            System.assert(thisCaseId != null);
            Case thisCase = [SELECT Id,Subject FROM Case WHERE Id=:thisCaseId];
            System.assert(thisCase != null);
            System.assertEquals(thisCase.Subject, 'Ferocious chipmunk');
        }
    
        @isTest static void testDeleteCase() {
            Id recordId = createTestRecord();
            // 设置一个测试请求
            RestRequest request = new RestRequest();
            request.requestUri =
                'https://yourInstance.salesforce.com/services/apexrest/Cases/'
                + recordId;
            request.httpMethod = 'GET';
            RestContext.request = request;
            // 调用测试方法
            CaseManager.deleteCase();
            // 验证记录被删除
            List<Case> cases = [SELECT Id FROM Case WHERE Id=:recordId];
            System.assert(cases.size() == 0);
        }
    
        @isTest static void testUpsertCase() {
            // 1.插入新记录
            ID case1Id = CaseManager.upsertCase(
                    'Ferocious chipmunk', 'New', 'Phone', 'Low', null);
            // 验证新记录是否已创建
            System.assert(Case1Id != null);
            Case case1 = [SELECT Id,Subject FROM Case WHERE Id=:case1Id];
            System.assert(case1 != null);
            System.assertEquals(case1.Subject, 'Ferocious chipmunk');
            // 2. 将现有记录的状态更新为Working
            ID case2Id = CaseManager.upsertCase(
                    'Ferocious chipmunk', 'Working', 'Phone', 'Low', case1Id);
            // 验证记录已更新
            System.assertEquals(case1Id, case2Id);
            Case case2 = [SELECT Id,Status FROM Case WHERE Id=:case2Id];
            System.assert(case2 != null);
            System.assertEquals(case2.Status, 'Working');
        }    
    
        @isTest static void testUpdateCaseFields() {
            Id recordId = createTestRecord();
            RestRequest request = new RestRequest();
            request.requestUri =
                'https://yourInstance.salesforce.com/services/apexrest/Cases/'
                + recordId;
            request.httpMethod = 'PATCH';
            request.addHeader('Content-Type', 'application/json');
            request.requestBody = Blob.valueOf('{"status": "Working"}');
            RestContext.request = request;
            // 将现有记录的状态更新为Working
            ID thisCaseId = CaseManager.updateCaseFields();
            // 验证记录已更新
            System.assert(thisCaseId != null);
            Case thisCase = [SELECT Id,Status FROM Case WHERE Id=:thisCaseId];
            System.assert(thisCase != null);
            System.assertEquals(thisCase.Status, 'Working');
        }  
    
        // Helper method
        static Id createTestRecord() {
            // Create test record
            Case caseTest = new Case(
                Subject='Test record',
                Status='New',
                Origin='Phone',
                Priority='Medium');
            insert caseTest;
            return caseTest.Id;
        }          
    
    }
  4. 按下CTRL + S保存。
  5. 通过选择测试|运行您的组织中的所有 Test | Run All.

测试结果显示在“测试”选项卡中。测试执行完成后,请检查“总体代码覆盖率”窗格中的CaseManager行。这是在100%的覆盖面。

告诉我更多…

了解Apex REST,Salesforce API和安全注意事项中支持的数据类型和名称空间。
Apex REST支持的数据类型
Apex REST支持这些数据类型的参数和返回值。

  • Apex基元(不包括sObject和Blob)。
  • sObjects
  • Apex基元或sObjects的列表或映射(仅支持使用String键的映射)。
  • 用户定义的类型包含上面列出的类型的成员变量。
Apex REST端点中的命名空间
Apex REST端点中的命名空间
Apex REST方法可用于托管和非托管包中。调用托管包中包含的Apex REST方法时,需要将托管包名称空间包含在REST调用URL中。例如,如果该类包含在名为packageNamespace的托管包名称空间中,并且Apex REST方法使用/ MyMethod / *的URL映射,则通过REST调用这些方法的URL将采用https:// instance形式。 salesforce.com/services/apexrest/packageNamespace/MyMethod/。
自定义Apex Web服务和Salesforce API
外部应用程序可以使用Salesforce的REST和SOAP API与Salesforce集成,而不是使用REST和SOAP服务的自定义Apex代码。这些API使您可以创建,更新和删除记录。但是,使用Apex Web服务的优势在于Apex方法可以封装复杂的逻辑。这个逻辑对消费应用程序是隐藏的。此外,Apex类操作可能比单独调用API更快,因为在客户端和Salesforce服务器之间执行的往返次数较少。通过Apex Web服务调用,仅发送一个请求,并且方法中的所有操作都在服务器上执行。
Apex Web服务的安全注意事项
Apex Web服务方法运行的安全上下文与Salesforce API的安全上下文不同。与Salesforce API不同,Apex Web服务方法以系统权限运行,并且不尊重用户的对象和字段权限。但是,Apex Web服务方法在使用with sharing关键字声明时会强制执行共享规则。

Salesforce API(8)SOAP外调

学习目标

完成本单元后,您将能够:

  • 使用WSDL2Apex生成Apex类。
  • 执行标注以使用SOAP将数据发送到外部服务。
  • 使用模拟标注测试标注。

使用WSDL2Apex生成Apex代码

除了REST标注外,Apex还可以使用XML对SOAP Web服务进行标注。使用SOAP可能是一个痛苦的(但必要的)经验。幸运的是,我们有工具来简化这个过程。
WSDL2Apex从WSDL文档自动生成Apex类。您下载Web服务的WSDL文件,然后上传WSDL,WSDL2Apex为您生成Apex类。 Apex类构造SOAP XML,传输数据,并将响应XML解析到Apex对象中。而不是开发构建和分析Web服务消息的XML的逻辑,让由WSDL2Apex生成的Apex类在内部处理所有这些开销。如果您熟悉WSDL2Java或使用.NET作为Web引用导入WSDL,则此功能类似于WSDL2Apex。别客气。

注意

尽可能使用出站消息处理集成解决方案。仅在必要时才使用对第三方Web服务的标注。

对于这个例子,我们使用一个简单的计算器Web服务来添加两个数字。这是一个开创性的服务,是所有的愤怒!我们需要做的第一件事是下载WSDL文件来生成Apex类。点击此链接并将calculator.xml文件下载到您的计算机上。记住你保存这个文件的位置,因为你在下一步需要它。

从WSDL生成一个Apex类

  1. 从“设置”中,在“快速查找”框中输入“Apex类”,然后单击 Apex Classes.
  2. 点击 Generate from WSDL.
  3. 点击 Choose File 然后选择下载的calculator.xml文件。
  4. 点击 Parse WSDL. 应用程序为WSDL文档中的每个名称空间生成默认的类名称,并报告任何错误。

    对于这个例子,使用默认的类名称。但是,在现实生活中,强烈建议您更改默认名称,以使其更易于使用,并使代码更直观。

    现在该坦诚地谈谈WSDL解析器了。 WSDL2Apex解析是一个臭名昭着的善变。解析过程可能由于多种原因而失败,例如不支持的类型,多个绑定或未知元素。不幸的是,您可能会被迫手动编写调用Web服务的Apex类或使用HTTP。

  5. 点击 Generate Apex code. 向导的最后一页显示生成的类以及任何错误。该页面还提供链接以查看成功生成的代码。
    生成的Apex类包括用于调用由WSDL文档表示的第三方Web服务的存根类和类类。这些类允许您从Apex调用外部Web服务。对于每个生成的类,使用相同的名称和前缀Async创建第二个类。 calculatorServices类用于同步标注。 AsyncCalculatorServices类用于异步标注。

执行标注

先决条件

在运行此示例之前,请使用“授权端点地址”部分中的步骤来授权Web服务标注的端点URL https://th-apex-soap-service.herokuapp.com

现在你可以执行标注,看看它是否正确添加两个数字。有一个计算器,方便检查结果。

  1. 从设置档(打开设备齿轮图标Setup gear icon)打开开发者控制台。
  2. 在开发者控制台中,选择 Debug | Open Execute Anonymous Window.
  3. 删除所有现有的代码,并插入下面的代码片段。
    calculatorServices.CalculatorImplPort calculator = new  calculatorServices.CalculatorImplPort();
    Double x = 1.0;
    Double y = 2.0;
    Double result = calculator.doAdd(x,y);
    System.debug(result);
  4. 选择 Open Log, 然后单击 Execute.
  5. 调试日志打开后,单击调试只查看System.debug语句的输出。日志应该显示3.0。

测试Web服务标注

所有有经验的Apex开发人员都知道,要部署或打包Apex代码,至少有75%的代码必须具有测试覆盖率。这个覆盖范围包括我们由WSDL2Apex生成的类。您以前可能听说过这个,但测试方法不支持Web服务标注,执行Web服务标注的测试失败。所以,我们有一点工作要做。为了防止测试失败并增加代码覆盖率,Apex提供了一个内置的WebServiceMock接口和Test.setMock方法。您可以使用此接口在测试方法中接收假响应,从而提供必要的测试覆盖率。

为标注指定模拟响应

当您从WSDL创建Apex类时,自动生成的类中的方法调用WebServiceCallout.invoke,该方法执行对外部服务的调用。在测试这些方法时,只要调用WebServiceCallout.invoke,就可以指示Apex运行时生成一个假响应。为此,请实现WebServiceMock接口并指定测试运行时发送的假响应。

指示Apex运行时通过在您的测试方法中调用Test.setMock来发送此假响应。对于第一个参数,传递WebServiceMock.class。对于第二个参数,传递一个WebServiceMock接口实现的新实例。

Test.setMock(WebServiceMock.class, new MyWebServiceMockImpl());
这很重要,所以让我们来看一个完整的示例代码。在这个例子中,你创建了一个名为callout的类,一个用于测试的模拟实现和一个测试类本身。
  1. 在开发者控制台中,选择 File | New | Apex Class.
  2. 对于类名称,输入AwesomeCalculator,然后单击 OK.
  3. 用下面的类定义替换自动生成的代码。
    public class AwesomeCalculator {
        public static Double add(Double x, Double y) {
            calculatorServices.CalculatorImplPort calculator = 
                new calculatorServices.CalculatorImplPort();
            return calculator.doAdd(x,y);
        }
    }
  4. 按下CTRL + S保存。

    在测试过程中创建您的模拟实现来伪造标注。您的WebServiceMock实现调用doInvoke方法,该方法返回您为测试指定的响应。这些代码大部分是样板。这个练习中最难的部分就是搞清楚Web服务如何返回一个响应,这样你就可以伪造一个值。

  5. 在开发者控制台中,选择 File | New | Apex Class.
  6. 对于类名称,输入CalculatorCalloutMock,然后单击 OK.
  7. 将自动生成的代码替换为以下类定义。
    @isTest
    global class CalculatorCalloutMock implements WebServiceMock {
       global void doInvoke(
               Object stub,
               Object request,
               Map<String, Object> response,
               String endpoint,
               String soapAction,
               String requestName,
               String responseNS,
               String responseName,
               String responseType) {
            // 开始 - 指定你想发送的响应
            calculatorServices.doAddResponse response_x = 
                new calculatorServices.doAddResponse();
            response_x.return_x = 3.0;
            // 结束
            response.put('response_x', response_x); 
       }
    }
  8. 按下CTRL + S保存。

    最后,您的测试方法需要通过调用Test.setMock来指示Apex运行时发送假响应,然后在AwesomeCalculator类中进行标注。像任何其他测试方法一样,我们断言我们的模拟响应得到了正确的结果。

  9. 在开发者控制台中,选择 File | New | Apex Class.
  10. 对于类名称,输入AwesomeCalculatorTest,然后单击 OK.
  11. 将自动生成的代码替换为以下类定义。
    @isTest
    private class AwesomeCalculatorTest {
        @isTest static void testCallout() {              
            // 这将导致生成一个假的响应
            Test.setMock(WebServiceMock.class, new CalculatorCalloutMock());
            // 调用调用标注的方法
            Double x = 1.0;
            Double y = 2.0;
            Double result = AwesomeCalculator.add(x, y);
            // 验证是否返回假结果
            System.assertEquals(3.0, result); 
        }
    }
  12. 按下CTRL + S保存。
  13. 要运行测试,请选择 Test | Run All.

AwesomeCalculator类现在应该显示100%的代码覆盖率!

Salesforce API(7)REST外调

学习目标

完成本单元后,您将能够:

  • 执行标注以接收来自外部服务的数据。
  • 执行标注将数据发送到外部服务。
  • 使用模拟标注测试标注。

HTTP和标注基础

REST标注基于HTTP。要了解标注如何工作,了解一些有关HTTP的内容很有帮助。每个标注请求都与HTTP方法和端点相关联。 HTTP方法指示需要什么类型的动作。
Apex callouts to an external service

最简单的请求是一个GET请求(GET是一个HTTP方法)。 GET请求意味着发送者想要从服务器获取关于资源的信息。当服务器接收并处理此请求时,它将请求信息返回给收件人。 GET请求与导航到浏览器中的地址相似。当您访问网页时,浏览器会在幕后执行GET请求。在浏览器中,导航的结果是显示的新HTML页面。用标注,结果是响应对象。

为了说明GET请求的工作方式,打开浏览器并导航到以下URI: https://th-apex-http-callout.herokuapp.com/animals. 您的浏览器以奇怪的格式显示动物列表,因为服务以JSON格式返回响应。有时GET响应也是用XML格式化的。

以下是常用HTTP方法的说明。

表1.一些常用的HTTP方法
HTTP方法 描述
GET 检索由URL标识的数据。
POST 创建资源或发布数据到服务器。
DELETE 删除由URL标识的资源。
PUT 创建或替换请求正文中发送的资源。

如果您有空闲时间,请在参考资料部分浏览所有HTTP方法的详尽列表。

除了HTTP方法之外,每个请求都会设置一个URI,这是服务所在的端点地址。例如,一个端点可以是http://www.example.com/api/resource。在“HTTP和标注基础”单元中的示例中,端点是https://th-apex-http-callout.herokuapp.com/animals。

当服务器处理请求时,它在响应中发送一个状态码。状态码指示请求是否成功处理或是否遇到错误。如果请求成功,服务器会发送一个200的状态码。您可能已经看到一些其他的状态码,例如404没有找到文件,500没有找到内部服务器错误。

如果在浏览HTTP方法列表后仍然有空闲时间,请查看参考资料部分的所有响应状态代码列表。如果你晚上睡得很困难,这两个资源可以帮助你。

注意

除了端点和HTTP方法之外,还可以为请求设置其他属性。例如,请求可以包含提供有关请求的更多信息的标题,例如内容类型。请求还可以包含要发送到服务的数据,例如POST请求。您将在稍后的步骤中看到POST请求的示例。 POST请求类似于单击网页上的按钮来提交表单数据。使用标注,您可以将数据作为请求正文的一部分发送,而不是在网页上手动输入数据。

从服务获取数据

现在是时候把你的新的HTTP知识与一些Apex标注一起使用了。本示例向Web服务发送GET请求以获取林地生物列表。该服务以JSON格式发送响应。 JSON本质上是一个字符串,所以内置的JSONParser类将它转换为一个对象。然后,我们可以使用该对象将每个动物的名称写入调试日志。
在本机运行示例之前,您需要使用“授权端点地址”部分中的步骤来授权标注的端点URL https://th-apex-http-callout.herokuapp.com。
  1. 从设置档(打开设备齿轮图标Setup gear icon)打开开发者控制台。 
  2. 在开发者控制台中,选择 Debug | Open Execute Anonymous Window.
  3. 删除现有的代码并插入下面的代码片段。
    Http http = new Http();
    HttpRequest request = new HttpRequest();
    request.setEndpoint('https://th-apex-http-callout.herokuapp.com/animals');
    request.setMethod('GET');
    HttpResponse response = http.send(request);
    // 如果请求成功,则解析JSON响应。
    if (response.getStatusCode() == 200) {
        // 将JSON字符串反序列化为原始数据类型的集合。
        Map<String, Object> results = (Map<String, Object>) JSON.deserializeUntyped(response.getBody());
        // 将“动物”键中的值作为列表进行投射
        List<Object> animals = (List<Object>) results.get('animals');
        System.debug('Received the following animals:');
        for (Object animal: animals) {
            System.debug(animal);
        }
    }
  4. 选择 Open Log,然后单击 Execute.
  5. 调试日志打开后,选择Debug Only以查看System.debug语句的输出。
    显示动物的名字。

我们例子中的JSON相当简单并且易于解析。对于更复杂的JSON结构,可以使用JSON2Apex。该工具生成用于解析JSON结构的强类型的Apex代码。您只需粘贴JSON,该工具就会为您生成必要的Apex代码。辉煌!

发送数据到服务

HTTP标注的另一个常见用例是将数据发送到服务。例如,当您购买最新的贾斯汀·比伯(Justin Bieber)专辑或评论您最喜欢的“鲨鱼服装中的猫在骑着Roomba的同时追逐鸭子”视频时,您的浏览器正在提交POST请求以提交数据。我们来看看我们如何在Apex中发送数据。
本示例向Web服务发送POST请求以添加动物名称。新名称作为JSON字符串添加到请求正文中。请求Content-Type头设置为让服务知道发送的数据是JSON格式,以便它可以适当地处理数据。该服务通过发送状态代码和所有动物列表(包括您添加的动物)作出响应。如果请求已成功处理,则状态码将返回201,因为已创建资源。如果返回201以外的任何内容,则将响应发送到调试日志。
  1. 从设置档(打开设备齿轮图标Setup gear icon)打开开发者控制台。
  2. 在开发者控制台中,选择 Debug | Open Execute Anonymous Window.
  3. 删除任何现有的代码并插入以下片段。
    Http http = new Http();
    HttpRequest request = new HttpRequest();
    request.setEndpoint('https://th-apex-http-callout.herokuapp.com/animals');
    request.setMethod('POST');
    request.setHeader('Content-Type', 'application/json;charset=UTF-8');
    // 将主体设置为JSON对象
    request.setBody('{"name":"mighty moose"}');
    HttpResponse response = http.send(request);
    // 解析JSON响应
    if (response.getStatusCode() != 201) {
        System.debug('The status code returned was not expected: ' +
            response.getStatusCode() + ' ' + response.getStatus());
    } else {
        System.debug(response.getBody());
    }
  4. 选择 Open Log, 然后单击 Execute.
  5. 调试日志打开时,请选择仅调试以查看System.debug语句的输出。动物列表中的最后一项是“mighty moose”.

测试标注

标注测试有好消息和坏消息。坏消息是Apex测试方法不支持标注,执行标注的测试失败。好消息是测试运行时允许你“嘲笑”标注。模拟标注允许您指定在测试中返回的响应,而不是实际调用Web服务。你实际上在告诉运行时,“我知道这个web服务将会返回什么,所以不要在测试过程中调用它,而是返回这个数据。”在你的测试中使用模拟标注有助于确保你获得足够的代码覆盖率,代码由于标注而被跳过。

先决条件

在编写测试之前,让我们创建一个类,其中包含我们在“将数据发送到服务”单元中匿名执行的GET和POST请求示例。这些示例稍有修改,以便请求在方法和返回值中,但它们与前面的示例基本相同。

  1. 在开发者控制台中,选择 File | New | Apex Class.
  2. 对于课程名称,请输入AnimalsCallouts,然后单击 OK.
  3. 将自动生成的代码替换为以下类定义。
    public class AnimalsCallouts {
    
        public static HttpResponse makeGetCallout() {
            Http http = new Http();
            HttpRequest request = new HttpRequest();
            request.setEndpoint('https://th-apex-http-callout.herokuapp.com/animals');
            request.setMethod('GET');
            HttpResponse response = http.send(request);
            // 如果请求成功,则解析JSON响应。
            if (response.getStatusCode() == 200) {
                // 将JSON字符串反序列化为原始数据类型的集合。
                Map<String, Object> results = (Map<String, Object>) JSON.deserializeUntyped(response.getBody());
                // 将“动物”键中的值作为列表进行投射
                List<Object> animals = (List<Object>) results.get('animals');
                System.debug('Received the following animals:');
                for (Object animal: animals) {
                    System.debug(animal);
                }
            }
            return response;
        }
    
        public static HttpResponse makePostCallout() {
            Http http = new Http();
            HttpRequest request = new HttpRequest();
            request.setEndpoint('https://th-apex-http-callout.herokuapp.com/animals');
            request.setMethod('POST');
            request.setHeader('Content-Type', 'application/json;charset=UTF-8');
            request.setBody('{"name":"mighty moose"}');
            HttpResponse response = http.send(request);
            // 解析JSON响应
            if (response.getStatusCode() != 201) {
                System.debug('The status code returned was not expected: ' +
                    response.getStatusCode() + ' ' + response.getStatus());
            } else {
                System.debug(response.getBody());
            }
            return response;
        }        
    
    }
  4. 按下CTRL + S保存。

使用StaticResourceCalloutMock测试标注

要测试您的标注,请通过实现接口或使用静态资源来使用模拟标注。在这个例子中,我们稍后使用静态资源和模拟接口。静态资源包含要返回的响应主体。同样,使用模拟标注时,请求不会发送到端点。相反,Apex运行时知道查找在静态资源中指定的响应,并返回它。 Test.setMock方法通知运行时在测试方法中使用模拟标注。让我们看看模拟标注在行动。首先,我们创建一个包含JSON格式字符串的静态资源,用于GET请求。

  1. 在开发者控制台中,选择 File | New | Static Resource.
  2. 对于名称,输入GetAnimalResource。
  3. 对于MIME类型,即使我们使用JSON,也请选择text / plain。
  4. 点击 Submit.
  5. 在为资源打开的选项卡中,插入以下内容。确保它全部在一行上,不会中断到下一行。这个内容是模拟标注返回的内容。这是三个林地生物阵列。
    {"animals": ["pesky porcupine", "hungry hippo", "squeaky squirrel"]}
  6. 按下CTRL + S保存。

您已成功创建您的静态资源!现在,让我们为使用此资源的标注添加一个测试。

  1. 在开发者控制台中,选择 File | New | Apex Class.
  2. 对于类名称,输入AnimalsCalloutsTest,然后单击 OK.
  3. 将自动生成的代码替换为以下测试类定义。
    @isTest
    private class AnimalsCalloutsTest {
    
        @isTest static  void testGetCallout() {
            // 基于静态资源创建模拟响应
            StaticResourceCalloutMock mock = new StaticResourceCalloutMock();
            mock.setStaticResource('GetAnimalResource');
            mock.setStatusCode(200);
            mock.setHeader('Content-Type', 'application/json;charset=UTF-8');
            // 将标注与模拟响应相关联
            Test.setMock(HttpCalloutMock.class, mock);
            // 调用方法来测试
            HttpResponse result = AnimalsCallouts.makeGetCallout();
            // 验证模拟响应不为空
            System.assertNotEquals(null,result,
                'The callout returned a null response.');
            // 验证状态码
            System.assertEquals(200,result.getStatusCode(),
              'The status code is not 200.');
            // 验证内容类型
            System.assertEquals('application/json;charset=UTF-8',
              result.getHeader('Content-Type'),
              'The content type value is not expected.');  
            // 验证数组包含3个项目 
            Map<String, Object> results = (Map<String, Object>) 
                JSON.deserializeUntyped(result.getBody());
            List<Object> animals = (List<Object>) results.get('animals');
            System.assertEquals(3, animals.size(),
              'The array should only contain 3 items.');          
        }   
    
    }
  4. 按下CTRL + S保存。
  5. 选择 Test | Always Run Asynchronously.如果不选择“始终运行异步”,则测试运行只包含一个同步运行的类。您只能从“测试”选项卡打开日志,以进行同步测试运行。
  6. 要运行测试,请选择 Test | New Run.
  7. 从Test Classes列表中选择 AnimalsCalloutsTest.
  8. 点击 Add Selected | Run.

测试结果显示在测试运行ID下的测试选项卡中。测试执行完成后,展开测试运行以查看详细信息。现在在“代码总体覆盖率”窗格中双击AnimalCallouts,查看测试覆盖了哪些行。

用HttpCalloutMock测试标注

为了测试你的POST标注,我们提供了一个HttpCalloutMock接口的实现。此接口使您能够指定在响应方法中发送的响应。您的测试类指示Apex运行时通过再次调用Test.setMock来发送此假响应。对于第一个参数,传递HttpCalloutMock.class。对于第二个参数,传递一个AnimalsHttpCalloutMock的新实例,它是您的HttpCalloutMock的接口实现。 (在这个例子之后的例子中,我们将写AnimalsHttpCalloutMock)

Test.setMock(HttpCalloutMock.class, new AnimalsHttpCalloutMock());
现在添加实现HttpCalloutMock接口的类来拦截标注。如果在测试上下文中调用HTTP标注,则不会进行标注。相反,您会收到您在AnimalsHttpCalloutMock中的响应方法实现中指定的模拟响应。
  1. 在开发者控制台中,选择 File | New | Apex Class.
  2. 对于类名,输入AnimalsHttpCalloutMock,然后单击 OK.
  3. 将自动生成的代码替换为以下类定义。
    @isTest
    global class AnimalsHttpCalloutMock implements HttpCalloutMock {
        // 实现这个接口方法
        global HTTPResponse respond(HTTPRequest request) {
            // 创建一个假的回应
            HttpResponse response = new HttpResponse();
            response.setHeader('Content-Type', 'application/json');
            response.setBody('{"animals": ["majestic badger", "fluffy bunny", "scary bear", "chicken", "mighty moose"]}');
            response.setStatusCode(200);
            return response; 
        }
    }
  4. 按下CTRL + S保存。

在您的测试类中,创建testPostCallout方法来设置模拟标注,如下例所示。 testPostCallout方法调用Test.setMock,然后调用AnimalsCallouts类中的makePostCallout方法。然后验证返回的响应是您在模拟实现的响应方法中指定的。

  1. 修改测试类AnimalsCalloutsTest添加第二个测试方法。单击类选项卡,然后在右括号之前添加以下方法。
    @isTest static void testPostCallout() {
        // 设置模拟标注类
        Test.setMock(HttpCalloutMock.class, new AnimalsHttpCalloutMock()); 
        //这会导致从实现HttpCalloutMock的类发送假响应。 
        HttpResponse response = AnimalsCallouts.makePostCallout();
        // Verify that the response received contains fake values
        String contentType = response.getHeader('Content-Type');
        System.assert(contentType == 'application/json');
        String actualValue = response.getBody();
        System.debug(response.getBody());
        String expectedValue = '{"animals": ["majestic badger", "fluffy bunny", "scary bear", "chicken", "mighty moose"]}';
        System.assertEquals(actualValue, expectedValue);
        System.assertEquals(200, response.getStatusCode());
    }
  2. 按下CTRL + S保存。
  3. 选择 Test | New Run.
  4. 从Test Classes列表中选择 AnimalsCalloutsTest.
  5. 点击 Add Selected | Run.

    测试结果显示在“测试”选项卡下的新测试运行ID下。当测试执行完成时,展开测试运行以查看有关这两个测试的详细信息。

告诉我更多…

了解如何在触发器和异步Apex中使用标注,以及如何制作异步标注。
当从一个方法进行标注时,该方法在执行后续代码行之前,等待外部服务发回标注响应。或者,您可以将标注代码放置在使用@future(callout = true)标注的异步方法中,或使用Queueable Apex。这样,标注在单独的线程上运行,调用方法的执行不会被阻止。

从触发器进行标注时,标注不得在等待响应时阻止触发过程。为了使触发器能够进行标注,包含标注代码的方法必须使用@future(callout = true)进行注释以在单独的线程中运行。