Apex-Metadata API归档

学习目标

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

列举Apex元数据API强制执行安全性的几种方式。
解释负责任地使用Apex元数据API的注意事项。

为什么要信任Apex元数据API？

正如您所看到的，Apex元数据API使您能够自动更改组织的配置。但是改变一个组织的结构会对该组织中的数据产生安全影响。如果未经授权的应用修改您的组织，该怎么办？我们不会让你们陷入悬念 – 那不可能发生！信任是Salesforce的头号价值，Apex元数据API的构建是一个值得信赖的接口。

Apex Metadata API的三项功能可以保护您的组织和数据。

对可以创建或修改的元数据类型的限制。
对可以部署更改的应用程序的限制。
跟踪元数据更改的详细审计历史记录。

通过这些功能，您可以“信任但可以验证”。前两个功能让您信任使用Apex Metadata API的应用程序的功能。第三个功能可以让你验证应用程序的行为。让我们看看这些功能是如何工作的。

信任安全的元数据类型

为了确保安全性，Salesforce限制了可以使用Apex Metadata API创建或修改的元数据类型。 Apex元数据API的初始版本允许您使用两种元数据类型：页面布局和自定义元数据类型的记录。尽管我们打算在将来支持更多的元数据类型，但我们不会在Apex中公开整个Metadata API。这种谨慎的支持元数据的方法可以确保已安装的软件包只能使用安全的元数据类型，可以以可预见的方式进行修改。

Salesforce也不允许通过Apex创建Apex类，Visualforce页面或Lightning组件。正如您可以想象的那样，如果托管包可以在订户组织中编写代码，Salesforce将难以强制执行包的安全性。另外，为了确保已安装的应用程序仅以可预测的方式修改元数据类型，Salesforce不支持自动生成代码。

保护您的组织免受未知应用程序的侵害

除了限制可以创建或修改的元数据类型外，Salesforce还限制哪些软件包可以通过Apex部署元数据。 Apex元数据API只能在三种情况下执行部署：

从由已知的，已注册的独立软件供应商提供的认证管理软件包。
从未经认证的托管软件包，但只有订户组织启用特定的Apex设置时，我们将在稍后讨论。
来自非托管包，这意味着代码由执行它的组织拥有。

感觉更好？这些限制可确保部署来自可信实体。

注意

AppExchange中的合作伙伴应用程序可以在订阅者组织中进行元数据更改，以通知订阅者。 Salesforce在AppExchange安全审查期间验证此通知。

Salesforce提供Apex设置，允许未经认证的托管包（Salesforce尚未通过安全审核批准）执行元数据部署。它来自非认证软件包版本通过Apex部署元数据的易用名称，它位于“设置”|“Apex设置。未经认证的包中的Apex类不能访问元数据（公共或受保护的），除非启用此设置。

通过启用此设置，ISV可以测试尚未认证的托管软件包，企业可以使用托管软件包来测试或更新其应用程序。但只要您的组织关闭，您可以放心，没有未经认证的软件包可以修改您的组织。

下表显示了此设置如何控制不同软件包类型的部署。

	认证	未认证	非托管
Deploy Metadata Apex设置 on	Yes	Yes	Yes
Deploy Metadata Apex设置 off	Yes	No	Yes

Audit包行为

您可以在安装程序审计跟踪日志中验证受管软件包的行为。在日志中跟踪使用Apex元数据API的所有元数据操作。记录执行部署的代码的名称空间，这意味着您始终知道哪个名称空间进行了更改以及何时进行了更改。安装程序审计跟踪日志位于 Setup | View Setup Audit Trail.

负责任地使用你的大力量

我们已经看到Salesforce如何通过以下方式确保Apex元数据API是可信的界面：

限制可以修改的元数据的类型。
控制有权访问元数据的包的类型。

但是在这些约束条件下运行的托管包可以在其自己的名称空间外修改元数据。所以，作为一名开发人员，还有一些需要了解的事情，以便您可以负责任地修改元数据。

托管Apex以与非托管Apex相同的方式操作订户组织中的元数据，但有两个例外：

安装程序审计跟踪日志包括托管包的名称空间，因此您可以跟踪这些更改。
托管包中受保护的元数据可以通过相同名称空间中的Apex代码访问，但是对于订户组织或其他名称空间不可见。

由托管包的Apex创建的所有元数据都是在订户名称空间中创建的。您可以将托管包视为在订户组织上创建元数据。下表显示了托管包，订阅者组织或其他托管包的名称空间如何访问元数据。

	我的名字空间	订阅者命名空间	一个不同的托管包
开发者控制的公共元数据	读取	创建，读取，更新	读取
开发人员控制的受保护元数	读取	无权访问	无权访问
用户控制的公共元数据	创建，读取，更新	创建，读取，更新	创建，读取，更新
用户控制的受保护的元数据	创建，读取，更新	无权访问	无权访问

在处理Apex中的元数据时请记住以下几点。托管软件包的Apex可以：

更新任何公共订户控制的元数据，不管它在同一个包，订户组织还是不同的托管包中。
更新受保护的用户控制的元数据在其自己的名称空间。这种访问受保护元数据的功能使得Apex Metadata API成为保护更多应用程序的绝佳工具。您可以将您的应用程序配置隐藏为受保护的元数据，并仍然使用Apex操纵它们。
只有在订阅者组织的名称空间中更新开发人员控制的元数据。例如，如果托管包中的Apex创建自定义元数据类型的记录，则该记录位于订户名称空间中。托管软件包中的代码可以更新任何字段。

托管包的Apex无法更新包含在其自己的包中的开发人员控制的记录字段，即使它们位于相同的名称空间中。该元数据只能通过软件包升级进行更新。

还是和我们一起？别担心，不会有测验。哦，等等，这是Trailhead，会有一个测验！

什么是元数据API权限？

元数据API本身增加了一层信任。 Apex元数据API部署始终尊重元数据API权限。虽然您可以编写允许最终用户排入部署的Apex代码，但如果用户没有正确的Metadata API权限，则该部署将失败。

相比之下，从Apex元数据API检索调用可以让您的应用程序已经授权访问的任何用户。随着更多的元数据类型在Apex中公开，检索调用可以方便地提供对请求中不可用信息的读取访问。

对于独立软件供应商：准备您的安全审查

如果您是ISV的开发人员，则在使用Apex元数据API时，请记住以下几点：

要通过安全审查，您必须包含通知，让客户知道应用程序可以修改其元数据。
测试未经认证的托管软件包时，必须在订户组织中启用“Apex部署元数据”设置。
只支持页面布局和自定义元数据类型的记录。
删除不受支持。

结论

您现在了解了Apex元数据API如何使您能够为多种类型的元数据更改构建自动化。您可以使用Apex的强大功能创建脚本并设置更新元数据的体验。我们只是抓住了Apex元数据API可以做的事情的表面，我们希望用Apex元数据API来构建伟大的事物。请访问我们的Trailblazer社区的Apex Metadata API Chatter小组。

学习目标

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

列举Apex元数据API强制执行安全性的几种方式。
解释负责任地使用Apex元数据API的注意事项。

为什么要信任Apex元数据API？

Apex Metadata API的三项功能可以保护您的组织和数据。

对可以创建或修改的元数据类型的限制。
对可以部署更改的应用程序的限制。
跟踪元数据更改的详细审计历史记录。

信任安全的元数据类型

保护您的组织免受未知应用程序的侵害

除了限制可以创建或修改的元数据类型外，Salesforce还限制哪些软件包可以通过Apex部署元数据。 Apex元数据API只能在三种情况下执行部署：

从由已知的，已注册的独立软件供应商提供的认证管理软件包。
从未经认证的托管软件包，但只有订户组织启用特定的Apex设置时，我们将在稍后讨论。
来自非托管包，这意味着代码由执行它的组织拥有。

感觉更好？这些限制可确保部署来自可信实体。

注意

AppExchange中的合作伙伴应用程序可以在订阅者组织中进行元数据更改，以通知订阅者。 Salesforce在AppExchange安全审查期间验证此通知。

下表显示了此设置如何控制不同软件包类型的部署。

	认证	未认证	非托管
Deploy Metadata Apex设置 on	Yes	Yes	Yes
Deploy Metadata Apex设置 off	Yes	No	Yes

Audit包行为

负责任地使用你的大力量

我们已经看到Salesforce如何通过以下方式确保Apex元数据API是可信的界面：

限制可以修改的元数据的类型。
控制有权访问元数据的包的类型。

托管Apex以与非托管Apex相同的方式操作订户组织中的元数据，但有两个例外：

安装程序审计跟踪日志包括托管包的名称空间，因此您可以跟踪这些更改。
托管包中受保护的元数据可以通过相同名称空间中的Apex代码访问，但是对于订户组织或其他名称空间不可见。

	我的名字空间	订阅者命名空间	一个不同的托管包
开发者控制的公共元数据	读取	创建，读取，更新	读取
开发人员控制的受保护元数	读取	无权访问	无权访问
用户控制的公共元数据	创建，读取，更新	创建，读取，更新	创建，读取，更新
用户控制的受保护的元数据	创建，读取，更新	无权访问	无权访问

在处理Apex中的元数据时请记住以下几点。托管软件包的Apex可以：

更新任何公共订户控制的元数据，不管它在同一个包，订户组织还是不同的托管包中。
更新受保护的用户控制的元数据在其自己的名称空间。这种访问受保护元数据的功能使得Apex Metadata API成为保护更多应用程序的绝佳工具。您可以将您的应用程序配置隐藏为受保护的元数据，并仍然使用Apex操纵它们。
只有在订阅者组织的名称空间中更新开发人员控制的元数据。例如，如果托管包中的Apex创建自定义元数据类型的记录，则该记录位于订户名称空间中。托管软件包中的代码可以更新任何字段。

托管包的Apex无法更新包含在其自己的包中的开发人员控制的记录字段，即使它们位于相同的名称空间中。该元数据只能通过软件包升级进行更新。

还是和我们一起？别担心，不会有测验。哦，等等，这是Trailhead，会有一个测验！

什么是元数据API权限？

对于独立软件供应商：准备您的安全审查

如果您是ISV的开发人员，则在使用Apex元数据API时，请记住以下几点：

要通过安全审查，您必须包含通知，让客户知道应用程序可以修改其元数据。
测试未经认证的托管软件包时，必须在订户组织中启用“Apex部署元数据”设置。
只支持页面布局和自定义元数据类型的记录。
删除不受支持。

结论

学习目标

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

描述你可以做什么，不能测试元数据部署。
解释如何测试元数据容器。
解释如何测试元数据回调。

测试您的元数据部署

没有测试覆盖率，没有Apex代码是完整的。因此，您使用Apex元数据API编写的任何代码都必须经过适当的测试。让我们看看你可以测试什么（以及你不能）。

测试元数据部署的主要重点是部署请求的设置和部署结果的处理。要验证请求，可以测试部署容器是否设置正确。要测试部署结果，可以测试您的部署回调按预期运行。

实际上，您无法测试部署后组织的外观。但是测试容器和回调是确保一切正常工作的好方法。

测试您的部署容器

要测试您的部署请求代码，您可以验证所创建的元数据组件和组件值。使用assert语句来确保部署容器包含您所期望的。

下面的代码为您提供了关于我们在单元2中创建的DeployMetadata类的测试类的外观。testDeployment方法创建一个部署请求，并检索我们创建的布局元数据。然后，您可以浏览元数据以确保它包含我们创建的自定义字段。

点击设置装置，然后点击开发者控制台，打开 Developer Console.
在开发者控制台中，点击 File | New | Apex Class.
命名类DeploymentTest并单击 OK.
摆脱任何现有的代码，并复制并粘贴下面的示例代码。

@IsTest
public class DeploymentTest {
    @IsTest
    static void testDeployment() {
        DeployMetadata deployMd = new DeployMetadata();
        
        Metadata.DeployContainer container = deployMd.constructDeploymentRequest();
        List<Metadata.Metadata> contents = container.getMetadata();
        System.assertEquals(1, contents.size());
        Metadata.Layout md = (Metadata.Layout) contents.get(0);
       
        // 执行布局元数据的各种断言。
        System.assertEquals('Account-Account Layout', md.fullName);
    }
}

要测试您的部署结果，请验证回调是否处理预期的和意外的结果。您的回调通常由Salesforce作为异步部署过程的一部分调用。因此，要在部署过程之外测试回调，请直接创建使用回调类的测试。

以下是我们在单元2中创建的PostInstallCallback类的测试类的样子。代码实例化回调，并创建DeployResults和DeployCallbackContext对象的测试实例。它使用这些测试实例来验证DeployCallback.handleResults方法。

从开发人员控制台中，使用名称MyDeploymentCallbackTest和以下代码创建一个Apex类。

@IsTest
public class MyDeploymentCallbackTest {
    @IsTest
    static void testMyCallback() {
        
        // 实例化回调。
        Metadata.DeployCallback callback = new PostInstallCallback();
       
        // 创建测试结果和上下文对象。
        Metadata.DeployResult result = new Metadata.DeployResult();
        result.numberComponentErrors = 1;
        Metadata.DeployCallbackContext context = new Metadata.DeployCallbackContext();
        
        // 调用回调的handleResult方法。
        callback.handleResult(result, context);
    }
}

// 用于测试的DeployCallbackContext子类返回myJobId。
public class TestingDeployCallbackContext extends Metadata.DeployCallbackContext {
    private Id myJobId = null; //设置为一个固定的ID，你可以用来测试。
    public override Id getCallbackJobId() {
        return myJobId;
    }
}

Apex Metadata API不是为测试其他代码而构建的。使用Apex元数据API为单元测试打开和关闭功能是很诱人的。但是，由于Apex元数据API依赖于异步部署，因此与Apex的同步测试不兼容。

学习目标

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

描述你可以做什么，不能测试元数据部署。
解释如何测试元数据容器。
解释如何测试元数据回调。

测试您的元数据部署

实际上，您无法测试部署后组织的外观。但是测试容器和回调是确保一切正常工作的好方法。

测试您的部署容器

要测试您的部署请求代码，您可以验证所创建的元数据组件和组件值。使用assert语句来确保部署容器包含您所期望的。

点击设置装置，然后点击开发者控制台，打开 Developer Console.
在开发者控制台中，点击 File | New | Apex Class.
命名类DeploymentTest并单击 OK.
摆脱任何现有的代码，并复制并粘贴下面的示例代码。

@IsTest
public class DeploymentTest {
    @IsTest
    static void testDeployment() {
        DeployMetadata deployMd = new DeployMetadata();
        
        Metadata.DeployContainer container = deployMd.constructDeploymentRequest();
        List<Metadata.Metadata> contents = container.getMetadata();
        System.assertEquals(1, contents.size());
        Metadata.Layout md = (Metadata.Layout) contents.get(0);
       
        // 执行布局元数据的各种断言。
        System.assertEquals('Account-Account Layout', md.fullName);
    }
}

从开发人员控制台中，使用名称MyDeploymentCallbackTest和以下代码创建一个Apex类。

@IsTest
public class MyDeploymentCallbackTest {
    @IsTest
    static void testMyCallback() {
        
        // 实例化回调。
        Metadata.DeployCallback callback = new PostInstallCallback();
       
        // 创建测试结果和上下文对象。
        Metadata.DeployResult result = new Metadata.DeployResult();
        result.numberComponentErrors = 1;
        Metadata.DeployCallbackContext context = new Metadata.DeployCallbackContext();
        
        // 调用回调的handleResult方法。
        callback.handleResult(result, context);
    }
}

// 用于测试的DeployCallbackContext子类返回myJobId。
public class TestingDeployCallbackContext extends Metadata.DeployCallbackContext {
    private Id myJobId = null; //设置为一个固定的ID，你可以用来测试。
    public override Id getCallbackJobId() {
        return myJobId;
    }
}

学习目标

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

描述Apex元数据API如何简化配置过程。
使用Apex元数据API自动执行配置更改。

为管理员自动执行重复性任务

我们已经看到了如何使用Apex元数据API来使用后期安装脚本将自定义字段添加到我们所有组织中的页面布局。现在让我们考虑一下不同的情况。假设您已经创建了一个必须配置并部署到您的组织中的自定义元数据类型。 Apex Metadata API允许您使用Apex内的自定义元数据类型的记录。您可以轻松构建自定义设置UI，使管理员可以使用Apex配置和部署新的自定义元数据类型。

例如，假设您已经创建了代表增值税（VAT）税率的自定义元数据类型。您需要为您所支持的每个国家/地区配置不同的税率。借助Apex Metadata API，您可以创建自己的设置UI，以简化管理员的配置过程。一个可能的解决方案是创建一个Visualforce页面，让管理员在一个地方配置值。该页面使用Apex元数据API将您的自定义元数据类型记录部署到您的组织中。让我们深入细节。

注意

注意：这个例子是故意简单的，所以我们可以把重点放在流程的基础上。在更现实的例子中，我们创建的Visualforce页面可以成为设置向导的一部分。向导可以通过一系列页面引导管理员进行更复杂的配置。但通过了解更简单的情况，您已准备好处理更复杂的情况。

添加一个新的自定义元数据类型

第一步是创建我们的自定义元数据类型。我们在安装程序中创建类型，但正如您在上一个单元中所看到的那样，您也可以使用Apex元数据API以编程方式执行此操作。

从设置中，输入自定义元数据类型，然后单击 Custom Metadata Types.
点击新建自定义元数据类型。
输入标签的增值税税率，带有多个VAT税率标签，然后点击 Save.

保存之后，您将登录增值税详情页面，您可以在其中添加自定义字段。对于我们的自定义元数据类型，我们需要两个自定义字段：单击“新建”以创建类型为“百分比”和标签“速率”的字段，以及类型为“复选框”和标签为“默认”的字段。您可以保留其余的默认选项。

创建增值税率记录

现在让我们创建一些新的自定义元数据类型的记录。

在增值税详情页面中，点击 Manage VAT Rates,，然后点击New.
输入US作为标签，然后点击 Save & New 为以下国家/地区添加VAT税率：
1. UK
2. SE
3. IT
4. RO

这些记录的自定义字段的值在这一点上并不重要。管理员从Visualforce页面配置值，并通过Apex以编程方式更新记录。

构建一个Visualforce页面和控制器

接下来，创建一个使用Apex元数据API的Apex控制器类。该类的构造函数创建一个VAT Rate值列表，我们通过Visualforce页面收集这些值。 save方法为我们的记录检索相应的元数据，并用我们收集的值更新值。最后，新的元数据值被添加到我们的部署容器中，并排队等待部署到组织中。

在开发者控制台中，点击 File | New | Apex Class.
命名类VATController，然后单击 OK.
摆脱任何现有的代码，并复制并粘贴下面的示例代码。

public class VATController {
    
    public final List<VAT_Rate__mdt> VATs {get;set;}
    final Map<String, VAT_Rate__mdt> VATsByApiName {get; set;}
    
    public VATController() { 
        VATs = new List<VAT_Rate__mdt>();
        VATsByApiName = new Map<String, Vat_Rate__mdt>();
        for (VAT_Rate__mdt v : [SELECT QualifiedApiName, MasterLabel, Default__c, Rate__c
                                FROM VAT_Rate__mdt]) { 
                                    VATs.add(v);
                                    VATsByApiName.put(v.QualifiedApiName, v);
                                }
    }
    
    public PageReference save() {        
        
        // 创建一个元数据容器
        Metadata.DeployContainer container = new Metadata.DeployContainer();
        List<String> vatFullNames = new List<String>();
        for (String recordName : VATsByApiName.keySet()) {
            vatFullNames.add('VAT_Rate.' + recordName);
        }
        
        List<Metadata.Metadata> records = 
            Metadata.Operations.retrieve(Metadata.MetadataType.CustomMetadata, 
                                         vatFullNames);
        
        for (Metadata.Metadata record : records) {
            Metadata.CustomMetadata vatRecord = (Metadata.CustomMetadata) record;
            String vatRecordName = vatRecord.fullName.substringAfter('.');
            VAT_Rate__mdt vatToCopy = VATsByApiName.get(vatRecordName);
            
            for (Metadata.CustomMetadataValue vatRecValue : vatRecord.values) {
                vatRecValue.value = vatToCopy.get(vatRecValue.field);
            }
            
            // 将记录添加到容器。
            container.addMetadata(vatRecord);
        }   
        
        // 使用新组件部署容器。
        Id asyncResultId = Metadata.Operations.enqueueDeployment(container, null);
        
        return null;
    }
}

点击设置装置，然后点击开发者控制台，打开 Developer Console.
在开发者控制台中，点击 File | New | Visualforce Page.
命名页面VATRateForm并单击 OK.
摆脱任何现有的代码，并复制并粘贴下面的示例代码。

<apex:page controller="VATController">
    <apex:form >
        <apex:pageBlock title="VAT Rates" mode="edit">
            <apex:pageMessages />
            
            <apex:pageBlockButtons >
                <apex:commandButton action="{!save}" value="Save"/>
            </apex:pageBlockButtons>
            
            <apex:pageBlockTable value="{!VATs}" var="v">
                <apex:column value="{!v.MasterLabel}"/>
                <apex:column headerValue="Rate">
                    <apex:inputText value="{!v.Rate__c}"/>
                </apex:column>
                <apex:column headerValue="Default">
                    <apex:inputCheckbox value="{!v.Default__c}"/>
                </apex:column>
            </apex:pageBlockTable>
        </apex:pageBlock>
    </apex:form>
</apex:page>

学习目标

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

描述Apex元数据API如何简化配置过程。
使用Apex元数据API自动执行配置更改。

为管理员自动执行重复性任务

注意

添加一个新的自定义元数据类型

从设置中，输入自定义元数据类型，然后单击 Custom Metadata Types.
点击新建自定义元数据类型。
输入标签的增值税税率，带有多个VAT税率标签，然后点击 Save.

创建增值税率记录

现在让我们创建一些新的自定义元数据类型的记录。

在增值税详情页面中，点击 Manage VAT Rates,，然后点击New.
输入US作为标签，然后点击 Save & New 为以下国家/地区添加VAT税率：
1. UK
2. SE
3. IT
4. RO

这些记录的自定义字段的值在这一点上并不重要。管理员从Visualforce页面配置值，并通过Apex以编程方式更新记录。

构建一个Visualforce页面和控制器

在开发者控制台中，点击 File | New | Apex Class.
命名类VATController，然后单击 OK.
摆脱任何现有的代码，并复制并粘贴下面的示例代码。

public class VATController {
    
    public final List<VAT_Rate__mdt> VATs {get;set;}
    final Map<String, VAT_Rate__mdt> VATsByApiName {get; set;}
    
    public VATController() { 
        VATs = new List<VAT_Rate__mdt>();
        VATsByApiName = new Map<String, Vat_Rate__mdt>();
        for (VAT_Rate__mdt v : [SELECT QualifiedApiName, MasterLabel, Default__c, Rate__c
                                FROM VAT_Rate__mdt]) { 
                                    VATs.add(v);
                                    VATsByApiName.put(v.QualifiedApiName, v);
                                }
    }
    
    public PageReference save() {        
        
        // 创建一个元数据容器
        Metadata.DeployContainer container = new Metadata.DeployContainer();
        List<String> vatFullNames = new List<String>();
        for (String recordName : VATsByApiName.keySet()) {
            vatFullNames.add('VAT_Rate.' + recordName);
        }
        
        List<Metadata.Metadata> records = 
            Metadata.Operations.retrieve(Metadata.MetadataType.CustomMetadata, 
                                         vatFullNames);
        
        for (Metadata.Metadata record : records) {
            Metadata.CustomMetadata vatRecord = (Metadata.CustomMetadata) record;
            String vatRecordName = vatRecord.fullName.substringAfter('.');
            VAT_Rate__mdt vatToCopy = VATsByApiName.get(vatRecordName);
            
            for (Metadata.CustomMetadataValue vatRecValue : vatRecord.values) {
                vatRecValue.value = vatToCopy.get(vatRecValue.field);
            }
            
            // 将记录添加到容器。
            container.addMetadata(vatRecord);
        }   
        
        // 使用新组件部署容器。
        Id asyncResultId = Metadata.Operations.enqueueDeployment(container, null);
        
        return null;
    }
}

点击设置装置，然后点击开发者控制台，打开 Developer Console.
在开发者控制台中，点击 File | New | Visualforce Page.
命名页面VATRateForm并单击 OK.
摆脱任何现有的代码，并复制并粘贴下面的示例代码。

<apex:page controller="VATController">
    <apex:form >
        <apex:pageBlock title="VAT Rates" mode="edit">
            <apex:pageMessages />
            
            <apex:pageBlockButtons >
                <apex:commandButton action="{!save}" value="Save"/>
            </apex:pageBlockButtons>
            
            <apex:pageBlockTable value="{!VATs}" var="v">
                <apex:column value="{!v.MasterLabel}"/>
                <apex:column headerValue="Rate">
                    <apex:inputText value="{!v.Rate__c}"/>
                </apex:column>
                <apex:column headerValue="Default">
                    <apex:inputCheckbox value="{!v.Default__c}"/>
                </apex:column>
            </apex:pageBlockTable>
        </apex:pageBlock>
    </apex:form>
</apex:page>

学习目标

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

使用Apex元数据API从组织中检索元数据。
使用Apex元数据API更新元数据并部署到组织中。

解决常见的多组织安装问题

好的，有时间解决您在多组织环境中工作时可能遇到的常见问题。假设你有10个组织，每个在你做生意的国家之一。您使用托管软件包来更新组织。您已经为“帐户”创建了一个自定义字段，并且希望它显示在所有组织的页面布局中。

理想情况下，您希望进行这些更新，而无需在管理员的设置UI中创建重复的工作。我们来看看如何使用Apex元数据API自动化流程。

我们通过Apex代码来检索帐户页面布局的现有元数据，并使用新字段进行更新。然后我们创建一个部署元数据更新的Apex post安装脚本。我们不必将我们的区域添加到我们每个组织的帐户页面布局中，而只需升级我们的组织中的托管软件包。 Apex负责所有的工作，在幕后添加新的区域。

检索元数据并将自定义字段添加到布局

以下是检索帐户页面布局的当前元数据的一些示例代码。然后它使用元数据来定位页面布局的帐户信息部分。最后，它为自定义字段创建一个元数据布局项目，并将其添加到本节中的元数据布局项目列表中。

点击设置装置，然后点击开发者控制台，打开 Developer Console.
在开发者控制台中，点击 File | New | Apex Class.
命名类UpdatePageLayout并单击 OK.
摆脱任何现有的代码，并复制并粘贴下面的示例代码。

public class UpdatePageLayout {
    // 将自定义字段添加到页面布局
    
    public Metadata.Layout buildLayout() {
        
        // 检索帐户布局和部分
        List<Metadata.Metadata> layouts = 
            Metadata.Operations.retrieve(Metadata.MetadataType.Layout, 
            new List<String> {'Account-Account Layout'});
        Metadata.Layout layoutMd = (Metadata.Layout) layouts.get(0);
        Metadata.LayoutSection layoutSectionToEdit = null;
        List<Metadata.LayoutSection> layoutSections = layoutMd.layoutSections;
        for (Metadata.LayoutSection section : layoutSections) {
            
            if (System.equals(section.label, 'Account Information')) {
                layoutSectionToEdit = section;
                break;
            }
        }
        
        // 添加左栏中“帐户信息”部分下的字段
        List<Metadata.LayoutColumn> layoutColumns = layoutSectionToEdit.layoutColumns;     
        List<Metadata.LayoutItem> layoutItems = layoutColumns.get(0).layoutItems;
        
        // 为自定义字段创建一个新的布局项目
        Metadata.LayoutItem item = new Metadata.LayoutItem();
        item.behavior = Metadata.UiBehavior.Edit;
        item.field = 'AMAPI__Apex_MD_API_sample_field__c';
        layoutItems.add(item);
        
        return layoutMd;
    }
}

注意

要使用这个类，请用您的名称空间和字段名称替换 ‘AMAPI__Apex_MD_API_sample_field__c’ .

有关Metadata名称空间中的类的更多信息，请参阅Apex开发人员指南。

提供一个回调类

现在我们已经创建了布局字段元数据，我们准备将元数据部署到我们的组织。由于部署是异步的，因此我们提供回调，以便在排队的部署完成时通知我们。回调类必须实现Metadata.DeployCallback接口。

注意

由于回调是在部署之后异步调用的，因此可能会有一个短暂的部署完成时间，但回调尚未调用。

在开发者控制台中，使用名称PostInstallCallback和下面的代码创建一个Apex类。

public class PostInstallCallback implements Metadata.DeployCallback {
  
    public void handleResult(Metadata.DeployResult result,
        Metadata.DeployCallbackContext context) {
        
        if (result.status == Metadata.DeployStatus.Succeeded) {
            // 部署成功，采取适当的行动。
            System.debug('Deployment Succeeded!');
        } else {
            // 部署不成功，采取适当的行动。
	    System.debug('Deployment Failed!');
        }
    }
}

Apex元数据API提供了Metadata.Operations.enqueueDeployment方法来将元数据部署到当前组织。当调用此方法时，部署请求将排队进行异步处理。

注意

部署元数据时，您可以创建和更新组件，但不能删除它们。

使用以下代码创建名称为DeployMetadata的Apex类。这个类创建一个部署容器，并将新的布局元数据添加到它。它实例化我们的回调类，当部署完成时调用它。然后调用Metadata.Operations.enqueueDeployment方法将新的元数据部署到组织中。

public class DeployMetadata {
 
    // 创建元数据容器
    public Metadata.DeployContainer constructDeploymentRequest() {
        
        Metadata.DeployContainer container = new Metadata.DeployContainer();
        
        // 添加组件到容器 
        Metadata.Layout layoutMetadata = new UpdatePageLayout().buildLayout();
        container.addMetadata(layoutMetadata);
        return container;
    }
    
    // 部署元数据
    public void deploy(Metadata.DeployContainer container) {
        // 创建回调
        PostInstallCallback callback = new PostInstallCallback();
        
        // 使用新组件部署容器。 
        Id asyncResultId = Metadata.Operations.enqueueDeployment(container, callback);
    }
}

异步部署元数据

现在我们已经编写了我们需要的Apex类，我们可以部署我们的自定义元数据。我们从后安装脚本启动部署，后者是一个实现InstallHandler接口的Apex类。如果软件包包含安装后脚本，则在安装或升级软件包后脚本将自动运行。在Developer Console中，创建PostInstallScript Apex类。

public class PostInstallScript implements InstallHandler {
    
    // 部署安装后的元数据
    public void onInstall(InstallContext context) {
        DeployMetadata deployUtil = new DeployMetadata();
        Metadata.DeployContainer container = deployUtil.constructDeploymentRequest();
        deployUtil.deploy(container);
    }
}

您可以在安装后脚本中检索和部署元数据。但是，在卸载脚本中，您可以从Apex代码中检索元数据，但不能部署元数据。

而已！当您在每个组织中升级软件包时，此脚本会将您的新字段添加到所有页面布局。您（和您的管理员）不必在安装界面中进行单一更改。在下一个单元中，我们看一个不同的场景。当你创建一个需要配置并部署到多个组织的自定义元数据类型时会发生什么？

但首先，试试看。完成以下挑战来测试你的知识。

学习目标

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

使用Apex元数据API从组织中检索元数据。
使用Apex元数据API更新元数据并部署到组织中。

解决常见的多组织安装问题

理想情况下，您希望进行这些更新，而无需在管理员的设置UI中创建重复的工作。我们来看看如何使用Apex元数据API自动化流程。

检索元数据并将自定义字段添加到布局

点击设置装置，然后点击开发者控制台，打开 Developer Console.
在开发者控制台中，点击 File | New | Apex Class.
命名类UpdatePageLayout并单击 OK.
摆脱任何现有的代码，并复制并粘贴下面的示例代码。

public class UpdatePageLayout {
    // 将自定义字段添加到页面布局
    
    public Metadata.Layout buildLayout() {
        
        // 检索帐户布局和部分
        List<Metadata.Metadata> layouts = 
            Metadata.Operations.retrieve(Metadata.MetadataType.Layout, 
            new List<String> {'Account-Account Layout'});
        Metadata.Layout layoutMd = (Metadata.Layout) layouts.get(0);
        Metadata.LayoutSection layoutSectionToEdit = null;
        List<Metadata.LayoutSection> layoutSections = layoutMd.layoutSections;
        for (Metadata.LayoutSection section : layoutSections) {
            
            if (System.equals(section.label, 'Account Information')) {
                layoutSectionToEdit = section;
                break;
            }
        }
        
        // 添加左栏中“帐户信息”部分下的字段
        List<Metadata.LayoutColumn> layoutColumns = layoutSectionToEdit.layoutColumns;     
        List<Metadata.LayoutItem> layoutItems = layoutColumns.get(0).layoutItems;
        
        // 为自定义字段创建一个新的布局项目
        Metadata.LayoutItem item = new Metadata.LayoutItem();
        item.behavior = Metadata.UiBehavior.Edit;
        item.field = 'AMAPI__Apex_MD_API_sample_field__c';
        layoutItems.add(item);
        
        return layoutMd;
    }
}

注意

要使用这个类，请用您的名称空间和字段名称替换 ‘AMAPI__Apex_MD_API_sample_field__c’ .

有关Metadata名称空间中的类的更多信息，请参阅Apex开发人员指南。

提供一个回调类

注意

由于回调是在部署之后异步调用的，因此可能会有一个短暂的部署完成时间，但回调尚未调用。

在开发者控制台中，使用名称PostInstallCallback和下面的代码创建一个Apex类。

public class PostInstallCallback implements Metadata.DeployCallback {
  
    public void handleResult(Metadata.DeployResult result,
        Metadata.DeployCallbackContext context) {
        
        if (result.status == Metadata.DeployStatus.Succeeded) {
            // 部署成功，采取适当的行动。
            System.debug('Deployment Succeeded!');
        } else {
            // 部署不成功，采取适当的行动。
	    System.debug('Deployment Failed!');
        }
    }
}

Apex元数据API提供了Metadata.Operations.enqueueDeployment方法来将元数据部署到当前组织。当调用此方法时，部署请求将排队进行异步处理。

注意

部署元数据时，您可以创建和更新组件，但不能删除它们。

public class DeployMetadata {
 
    // 创建元数据容器
    public Metadata.DeployContainer constructDeploymentRequest() {
        
        Metadata.DeployContainer container = new Metadata.DeployContainer();
        
        // 添加组件到容器 
        Metadata.Layout layoutMetadata = new UpdatePageLayout().buildLayout();
        container.addMetadata(layoutMetadata);
        return container;
    }
    
    // 部署元数据
    public void deploy(Metadata.DeployContainer container) {
        // 创建回调
        PostInstallCallback callback = new PostInstallCallback();
        
        // 使用新组件部署容器。 
        Id asyncResultId = Metadata.Operations.enqueueDeployment(container, callback);
    }
}

异步部署元数据

public class PostInstallScript implements InstallHandler {
    
    // 部署安装后的元数据
    public void onInstall(InstallContext context) {
        DeployMetadata deployUtil = new DeployMetadata();
        Metadata.DeployContainer container = deployUtil.constructDeploymentRequest();
        deployUtil.deploy(container);
    }
}

您可以在安装后脚本中检索和部署元数据。但是，在卸载脚本中，您可以从Apex代码中检索元数据，但不能部署元数据。

但首先，试试看。完成以下挑战来测试你的知识。

学习目标

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

确定Apex元数据API的用例。
列出Apex Metadata API的主要功能和局限性。

Apex Metadata API入门

假设您是Salesforce开发人员或ISV，并且为您的应用程序创建了一个很酷的新自定义功能，其中包含一些元数据更改。要将此功能部署到支持的组织中，请为管理员编写一组说明，以便他们可以进行更新。这些指令将引导他们完成Salesforce Setup UI中各个位置的更改。这听起来太熟悉了吗？除非你真的喜欢技术写作（就像我们在Salesforce做的那样），如果有一个更简单的方法来做你的更新不是很好吗？

好消息是，您可以使用Apex Metadata API来改进此过程。 API允许您直接从Apex进行元数据更改。因此，您可以使用Apex的所有便利功能来构建自定义设置UI，以在幕后更新元数据。您也可以通过这种方式自动进行配置更改。让我们来深入看一些使用Apex元数据API的例子。

这个API能为我做什么？

假设您支持多个组织，并且您已经创建了自定义字段。你想把你的新字段添加到所有组织的页面布局中。这种类型的配置信息存储在组织中的元数据类型和组件中。

您可以创建一个使用Apex元数据API的脚本，将您的新字段直接从Apex添加到您所有组织中的页面布局。组织中的元数据在幕后更新，以便您的管理员不必在每个组织中进行手动更改。

Image showing change in one org being rolled out to other orgs.

Apex元数据API还使您能够为您的功能建立自定义安装体验。例如，假设您已经创建了自定义元数据类型来支持新功能。您的自定义元数据类型的记录必须针对不同的国家进行不同的配置。您可以使用Apex Metadata API构建一个设置向导，通过一系列步骤来指导管理员配置记录。这种自动化功能可以让您的管理员不必在设置界面中进行手动更改。

直接从Apex处理元数据

要使用Apex代码中的元数据，请使用Metadata命名空间中的类。您可以访问两种顶级元数据类型：页面布局和自定义元数据类型的记录，这使您能够处理组织的大部分自定义和配置。

那么，您可以使用Apex元数据API来做些什么？您可以从组织中同步检索元数据。然后，您可以检查此元数据并进行更新，也可以创建元数据。使用异步部署将更新后的元数据部署到组织中非常简单。要在部署完成时得到通知，可以实现回调。

让我们先看一下Apex代码，看看Apex元数据API可以做什么。以下片段使用Metadata.CustomMetadata类创建自定义元数据类型的记录。我们可以直接从Apex将这个新记录部署到一个组织中，就像我们在本章后面看到的那样。

Metadata.CustomMetadata customMetadata =  new Metadata.CustomMetadata();
customMetadata.fullName = 'MyNamespace__MetadataTypeName.MetadataRecordName';
Metadata.CustomMetadataValue customField = new Metadata.CustomMetadataValue();
customField.field = 'customField__c';
customField.value = 'New value';
customMetadata.values.add(customField);

在当前版本中，我们只支持两种元数据类型：页面布局和自定义元数据类型的记录。
支持读取，创建和更新元数据，但不支持删除元数据。
我们没有可让您跟踪部署状态的API。但是，您可以设置在部署完成时调用的回调。

安全性如何？

元数据是强大的东西。所以也许你担心安全问题。别担心！信任是Salesforce的头号价值，Apex Metadata API的构建是一个值得信赖的界面。安装的软件包必须通过Apex认证，或者订户组织必须启用设置才能部署Apex元数据。您可以跟踪安装程序审计跟踪中启动部署的名称空间。

在您有机会了解Apex元数据API可以做什么之后，我们会在即将到来的单元中更详细地讨论安全性。

对ISV的一个注意

虽然本模块中的示例以企业为重点，但如果您是ISV的开发人员，Apex元数据API也可能很有用。创建特定于您的应用的设置UI并自动进行配置更改可以提高您的业务。使用Apex元数据API，您可以：

为非专业人士提供更快更轻松的设置体验，为您和您的客户节省资金。
完全通过自动化完成一些设置步骤。
通过向管理员提供他们可以使用的工具而无需专业服务专业知识，为管理员提供动态更改配置的功能。
通过降低客户尝试您的应用程序的障碍来提高产品的采用率。
保护你的知识产权。在应用程序中更新受保护元数据的能力意味着您可以隐藏更多来自客户的配置。
消除对远程站点设置的依赖，降低代码的复杂性并简化客户的设置。