Salesforce Apex （基础3）操作记录

学习目标

完成本单元后，您将能够：

使用DML插入，更新和删除记录。
批量执行DML语句。
使用upsert来插入或更新记录。
捕获一个DML异常。
使用数据库方法插入具有部分成功选项的新记录并处理结果。
知道何时使用DML语句以及何时使用数据库方法。
对相关记录执行DML操作

用DML操作记录

使用数据操作语言（简称DML）在Salesforce中创建和修改记录。 DML通过提供简单的语句来插入，更新，合并，删除和恢复记录，提供了一种直接管理记录的方法。
由于Apex是一种以数据为中心的语言，并保存在Force.com平台上，因此可直接访问Salesforce中的数据。与其他需要额外设置以连接数据源的编程语言不同，使用Apex DML，管理记录变得非常简单！通过调用DML语句，您可以快速对Salesforce记录执行操作。

此示例将Acme客户添加到Salesforce。首先创建一个客户sObject，然后将其作为参数传递给insert语句，该语句在Salesforce中保留该记录。

// 创建客户sObject
Account acct = new Account(Name='Acme', Phone='(415)555-1212', NumberOfEmployees=100);
// 通过使用DML插入客户
insert acct;

DML语句

以下DML语句可用。

insert
update
upsert
delete
undelete
merge

每个DML语句接受一个单独的sObject或一个sObject的列表（或数组）。在sObjects列表上操作是处理记录的更有效的方法。

除了一对，所有这些陈述都是熟悉的数据库操作。 upsert和merge语句是Salesforce特有的，可以非常方便。

upsert DML操作创建新记录，并在单个语句中更新sObject记录，使用指定的字段确定现有对象的存在，或者在没有指定字段的情况下使用ID字段。

合并语句将最多三个相同sObject类型的记录合并到其中一个记录中，删除其他记录，并将所有相关记录重新归类。

ID字段自动分配到新记录

插入记录时，系统为每个记录分配一个ID。除了在数据库中保存ID值之外，还可以在用作DML调用中的参数的sObject变量上自动填充ID值。

这个例子展示了如何获得对应于插入客户的sObject的ID。

// 创建客户sObject
Account acct = new Account(Name='Acme', Phone='(415)555-1212', NumberOfEmployees=100);
// 通过使用DML插入客户
insert acct;

// 获取插入的sObject参数的新ID
ID acctID = acct.Id;
// 在调试日志中显示此ID
System.debug('ID = ' + acctID);

// 调试日志结果（在您的情况下ID将不同）
// DEBUG|ID = 001D000000JmKkeIAF

超越基础

由于示例中的sObject变量包含DML调用后的ID，因此您可以重新使用此sObject变量来执行进一步的DML操作（如更新），因为系统可以通过匹配ID来将sObject变量映射到其对应的记录。

您可以从数据库检索记录以获取其字段，包括ID字段，但这不能用DML完成。您需要使用SOQL编写查询。您将在另一个单元学习SOQL。

批量 DML

您可以在单个sObject上执行DML操作，也可以在sObjects列表上批量执行DML操作。执行批量DML操作是推荐的方法，因为它有助于避免触及限额，例如每个Apex交易的DML限制为150条语句。这个限制是为了确保公平地访问Force.com多租户平台中的共享资源。在sObjects列表上执行DML操作会计算为列表中所有sObjects的一个DML语句，而不是每个sObject的一个语句。

此示例通过在一次调用中插入联系人列表来批量插入联系人。该示例然后批量更新这些联系人。

在开发者控制台中使用Anonymous Apex执行此代码段。

// 创建联系人列表
List<Contact> conList = new List<Contact> {
    new Contact(FirstName='Joe',LastName='Smith',Department='Finance'),
        new Contact(FirstName='Kathy',LastName='Smith',Department='Technology'),
        new Contact(FirstName='Caroline',LastName='Roth',Department='Finance'),
        new Contact(FirstName='Kim',LastName='Shain',Department='Education')};
            
// 用一个DML调用批量插入所有联系人
insert conList;

// List来保存新的联系人进行更新
List<Contact> listToUpdate = new List<Contact>();

// 遍历列表并仅添加标题
//  如果部门是财务部门
for(Contact con : conList) {
    if (con.Department == 'Finance') {
        con.Title = 'Financial analyst';
        // Add updated contact sObject to the list.
        listToUpdate.add(con);
    }
}

// 将更新的联系人sObject添加到列表中。
update listToUpdate;

检查最近在您的组织中创建的联系人。
两位在财务部门的联系人应该有他们的头衔，财务分析师。

插入记录

如果您有一个包含新记录和现有记录混合的列表，则可以使用upsert语句来处理对列表中所有记录的插入和更新。 Upsert有助于避免重复记录的创建，并且可以节省时间，因为您不必先确定哪些记录存在。

upsert语句通过比较一个字段的值来将sObjects与现有记录进行匹配。如果调用此语句时未指定字段，则upsert语句将使用sObject的ID将sObject与Salesforce中的现有记录进行匹配。或者，您可以指定一个字段用于匹配。对于自定义对象，请指定标记为外部标识的自定义字段。对于标准对象，可以指定任何idLookup属性设置为true的字段。例如，联系人或用户的电子邮件字段设置了idLookup属性。要检查字段的属性，请参阅Salesforce和Force.com的对象参考。

Upsert语法

upsert sObject | sObject[]

upsert sObject | sObject[] field

可选字段是字段标记。例如，要指定MyExternalID字段，该语句是：

upsert sObjectList Account.Fields.MyExternalId;

Upsert使用sObject记录的主键（ID），idLookup字段或外部ID字段来确定是否应该创建新记录或更新现有记录：

如果密钥不匹配，则创建一个新的对象记录。
如果密钥匹配一次，则更新现有对象记录。
如果密钥匹配多次，则会生成错误，并且不会插入或更新对象记录。

这个例子显示了upsert如何更新一个现有的联系人记录，并在一个呼叫中插入一个新的联系人。这个upsert调用更新现有的Josh联系人并插入一个新的联系人Kathy。

注意

upsert调用使用该ID来匹配第一个联系人。 josh变量正被重新用于upsert调用。这个变量已经被填充了上一次插入调用的记录ID，所以在这个例子中不需要显式地设置ID。

在开发者控制台的“执行匿名”窗口中执行此代码段。

//插入Josh联系人
Contact josh = new Contact(FirstName='Josh',LastName='Kaplan',Department='Finance');       
insert josh;

// Josh's 的记录已被插入
//   所以变量josh现在有一个ID
//   将用于通过upsert匹配记录
josh.Description = 'Josh\'s record has been updated by the upsert operation.';

// 创建Kathy联系人，但不要将其保存在数据库中
Contact kathy = new Contact(FirstName='Kathy',LastName='Brown',Department='Technology');

// 列举以保持新联系人upsert
List<Contact> contacts = new List<Contact> { josh, kathy };

// 调用upsert
upsert contacts;

// 结果：Josh被更新，Kathy被创建。

检查组织中的所有联系人。
您的组织只有一个Josh Kaplan记录，而不是两个，因为upsert操作找到了现有记录并进行了更新，而不是创建新的联系人记录。凯西·布朗的一个联系记录也将在那里。或者，您可以指定一个字段用于匹配记录。此示例使用Contact上的电子邮件字段，因为它具有idLookup属性集。该示例插入Jane Smith联系人，并创建第二个Contact sObject，使用相同的电子邮件填充它，然后使用电子邮件字段进行匹配以调用upsert以更新联系人。

注意

如果在这个例子中使用了插入而不是upsert，那么将会插入一个重复的Jane Smith联系人。

在开发者控制台的“执行匿名”窗口中执行此代码段。

Contact jane = new Contact(FirstName='Jane',
                         LastName='Smith',
                         Email='jane.smith@example.com',
                         Description='Contact of the day');
insert jane;

// 1.使用idLookup字段的Upsert
// 创建第二个sObject变量。
// 这个变量没有任何ID设置。
Contact jane2 = new Contact(FirstName='Jane',
                         LastName='Smith',  
                         Email='jane.smith@example.com',
                         Description='Prefers to be contacted by email.');
// 通过使用idLookup字段进行匹配来提升联系人。
upsert jane2 Contact.fields.Email;

// 确认联系人已更新
System.assertEquals('Prefers to be contacted by email.',
                   [SELECT Description FROM Contact WHERE Id=:jane.Id].Description);

检查组织中的所有联系人。
您的组织将只有一个Jane Smith联系更新后的描述。

删除记录

您可以使用delete语句删除持久记录。删除的记录不会从Force.com永久删除，但是它们可以从恢复位置放置在回收站中15天。

此示例显示如何删除姓氏为Smith的所有联系人。如果您已经为批量DML运行了样本，那么您的组织应该与Smith的姓氏有两个联系。在开发人员控制台中使用匿名Apex执行此代码段，然后验证是否没有与姓氏Smith的联系人。

Contact[] contactsDel = [SELECT Id FROM Contact WHERE LastName='Smith']; 
delete contactsDel;

注意

这个片段包含一个查询来检索联系人（一个SOQL查询）。你会在另一个单元学到更多关于SOQL的知识。

DML语句异常

如果DML操作失败，则返回DmlException类型的异常。您可以在代码中捕获异常以处理错误情况。

这个例子产生了一个DmlException，因为它试图插入一个没有必需的Name字段的客户。 catch块中捕获到异常。

try {
    // 这会导致异常
    //   不提供必需的名称字段。
    Account acct = new Account();
    // 插入客户
    insert acct;
} catch (DmlException e) {
    System.debug('A DML exception has occurred: ' +
                e.getMessage());
}

数据库方法

Apex包含内置的Database类，它提供执行DML操作和镜像DML语句对应的方法。
这些数据库方法是静态的，并在类名称上调用。

Database.insert()
Database.update()
Database.upsert()
Database.delete()
Database.undelete()
Database.merge()

与DML语句不同，数据库方法有一个可选的allOrNone参数，允许您指定操作是否应该部分成功。当此参数设置为false时，如果在部分记录集上发生错误，则成功的记录将被提交，并且将为失败的记录返回错误。另外，部分成功选项也不会引发异常。

这是你如何调用allOrNone设置为false的插入方法。

Database.insert(recordList, false);

Database.SaveResult[] results = Database.insert(recordList, false);

注意

Upsert返回Database.UpsertResult对象，并删除返回的Database.DeleteResult对象。

默认情况下，allOrNone参数为true，这意味着Database方法的行为与其DML语句相对应，如果遇到故障，则会引发异常。

以下两条语句相当于insert recordList;声明。

Database.insert(recordList);

Database.insert(recordList, true);

超越基础

除了这些方法外，Database类还包含不作为DML语句提供的方法。例如，用于事务控制和回滚的方法，用于清空回收站以及与SOQL查询相关的方法。您将在另一个单元学习SOQL。

示例：以部分成功插入记录

我们来看看使用数据库方法的例子。此示例基于批量DML示例，但是用Database方法替换了DML语句。用部分成功选项调用Database.insert（）方法。列表中的一个联系人没有任何有意使用的字段，并且会导致错误，因为如果没有所需的姓氏字段，则无法保存联系人。三个联系人被提交，没有任何字段的联系人会产生错误。本示例的最后一部分遍历返回的结果并将调试消息写入调试日志。

在开发者控制台的“执行匿名”窗口中执行此示例。

// 创建联系人列表
List<Contact> conList = new List<Contact> {
        new Contact(FirstName='Joe',LastName='Smith',Department='Finance'),
        new Contact(FirstName='Kathy',LastName='Smith',Department='Technology'),
        new Contact(FirstName='Caroline',LastName='Roth',Department='Finance'),
        new Contact()};
            
// 用一个DML调用批量插入所有联系人
Database.SaveResult[] srList = Database.insert(conList, false);

// 遍历每个返回的结果
for (Database.SaveResult sr : srList) {
    if (sr.isSuccess()) {
        // 操作成功，所以得到处理记录的ID
        System.debug('Successfully inserted contact. Contact ID: ' + sr.getId());
    } else {
        // 操作失败，所以得到所有的错误
        for(Database.Error err : sr.getErrors()) {
            System.debug('The following error has occurred.');
            System.debug(err.getStatusCode() + ': ' + err.getMessage());
            System.debug('Contact fields that affected this error: ' + err.getFields());
	 }
    }
}

验证调试消息（使用过滤器的DEBUG关键字）。
应该报告一个故障，应该插入三个联系人。

你应该使用DML语句还是数据库方法？

如果希望在批量DML处理期间发生的任何错误作为立即中断控制流的Apex异常（通过使用try。。catch块）引发，请使用DML语句。这种行为类似于大多数数据库过程语言中处理异常的方式。
如果要允许批量DML操作的部分成功，请使用Database类方法 – 如果记录失败，则DML操作的其余部分仍可能成功。然后您的应用程序可以检查被拒绝的记录，并可能重试该操作。使用此表单时，您可以编写不会抛出DML异常错误的代码。相反，您的代码可以使用适当的结果数组来判断成功或失败。请注意，数据库方法还包括一个支持抛出异常的语法，类似于DML语句。

使用相关记录

通过关系创建和管理彼此相关的记录。

插入相关记录

如果已经在两个对象之间定义了关系（例如查找或主从关系），则可以插入与现有记录相关的记录。记录通过外键ID与相关记录相关联。例如，如果插入新联系人，则可以通过设置AccountId字段的值来指定联系人的相关客户记录。

此示例显示如何通过在联系人上设置AccountId字段来将联系人添加到客户（相关记录）。联系人和客户通过查找关系链接。

在Developer Console的Anonymous Apex窗口中执行此代码段。

Account acct = new Account(Name='SFDC Account');
insert acct;

// 一旦插入客户，sObject将填充一个ID。
// 得到这个ID。
ID acctID = acct.ID;

// 添加一个联系人到这个客户。
Contact mario = new Contact(
    FirstName='Mario',
    LastName='Ruiz',
    Phone='415.555.1212',
    AccountId=acctID);
insert mario;

检查组织中的联系人。
新客户（SFDC客户）已创建，并在客户的“联系人”相关列表中包含Mario Ruiz联系人。

更新相关记录

相关记录上的字段不能用与DML操作相同的调用进行更新，并且需要单独的DML调用。例如，如果插入新联系人，则可以通过设置AccountId字段的值来指定联系人的相关客户记录。但是，如果不通过单独的DML调用更新客户本身，则无法更改客户名称。同样，更新联系人时，如果您还想更新联系人的相关客户，则必须进行两个DML调用。以下示例使用两个更新语句更新联系人及其相关客户。

// 查询与客户关联的联系人。
Contact queriedContact = [SELECT Account.Name 
                          FROM Contact 
                          WHERE FirstName = 'Mario' AND LastName='Ruiz'
                          LIMIT 1];

// 更新联系人的电话号码
queriedContact.Phone = '(415)555-1213';

// 更新相关的客户行业
queriedContact.Account.Industry = 'Technology';

// 拨打两个不同的电话
// 1. 此通话是更新联系人的电话。更新queriedContact;
// 2. 这个电话是更新相关客户的行业领域。
update queriedContact.Account;

删除相关记录

删除操作支持级联删除。如果删除父对象，则只要每个子记录可以被删除，就会自动删除它的子对象。

例如，删除先前创建的客户（SFDC客户）也会删除其相关联系人。

在Developer Console的Anonymous Apex窗口中执行此代码段。

Account[] queriedAccounts = [SELECT Id FROM Account WHERE Name='SFDC Account'];
delete queriedAccounts;

检查您的组织中的客户和联系人。
您会看到客户及其相关联系人都被删除了。

关于事物

DML操作在事务中执行。事务中的所有DML操作都可以成功完成，或者如果在一个操作中发生错误，则整个事务将回滚，并且不会向数据库提交任何数据。事务的边界可以是触发器，类方法，匿名代码块，Apex页面或自定义Web服务方法。例如，如果触发器或类创建两个客户并更新一个联系人，并且联系人更新由于验证规则失败而失败，则整个事务将回滚，并且Salesforce中的所有客户都不会持久化。