元数据 API 开发人员指南

Salesforce 元数据

元数据是描述其他数据的数据。要了解 Salesforce 如何定义元数据， 将业务数据与 Salesforce 元数据进行对比。业务数据包括以下记录： 直接对应于您公司的业务，例如地址、帐户或产品。 Salesforce 元数据描述了架构、流程、表示、授权和常规 Salesforce 组织的配置。

要将 Salesforce 元数据与业务数据进行对比，请首先检查架构元数据的 描述业务数据的属性。例如，Salesforce 标准对象 Address 具有架构元数据和业务数据。 地址字段（如 、 和 ）都是架构元数据。每个中的相应值 字段，例如邮寄地址、伊利诺伊州芝加哥和 60106，都是数据。 而个人 身份信息 （PII） 通常存在于业务数据中，元数据还可以包括 PII，例如自定义对象名称、报告名称等。Address TypeCityPostal Code

Salesforce 中的元数据还定义了组织的运作方式。例如，流程元数据 描述当用户按下“保存”按钮时发生的情况。演示文稿元数据问题 组织的布局和授权元数据决定了用户访问权限。Salesforce的 元数据还描述了组织的常规配置。例如，您可以配置 Chatter 阻止帖子中的表情符号。

元数据 API 适用于元数据类型和组件。元数据类型定义 应用程序元数据的结构。元数据组件是元数据类型的实例。 元数据类型的字段和值都是元数据。例如，元数据类型 CustomTab 表示显示内容的自定义选项卡。这 CustomTab 字段指示选项卡是否位于侧边栏面板上， 这是元数据确定表示的一个示例。元数据类型，如 CustomTab 构建元数据模型，描述组织的结构、显示或功能。 使用元数据 API 开发自定义项并构建用于管理元数据模型的工具， 而不是数据本身。hasSidebar

元数据 API 功能

元数据 API 的主要目的是在 Salesforce 组织在开发过程中。使用元数据 API 进行部署、检索、 创建、更新或删除自定义信息，例如自定义对象定义和 页面布局。元数据 API 不直接处理业务数据。要创建， 检索、更新或删除记录，例如客户或潜在客户，使用 SOAP API 或 REST API。

您可以使用以下两种方式之一移动元数据。第一种方法是使用元数据 API 和调用。管理员通常使用 and 调用来移动完整的元数据模型。这些调用 最适合开发的最后阶段，例如将经过测试的自定义项部署到 生产组织。deploy()retrieve()deploy()retrieve()

第二种方法是源推送和拉取命令，这些命令仅移动元数据中的更改。 这些命令使用源跟踪，这使得它们对开发人员更友好，也更好 用于中间开发阶段。

元数据 API 的用例

在开发过程中，使用元数据 API 在组织之间移动元数据 周期。元数据 API 还用于从 发展。

要了解如何使用元数据 API，假设您是 Zephyrus 的 Salesforce 开发人员 搬迁服务。Zephyrus 是一家人才流动公司，帮助公司开发流程 用于国内和国际员工搬迁。Zephyrus 正在向亚洲和南部扩张 美国，并希望为这两个地区增加定向服务。迎新服务包括 在住房和学校搜索、地区旅游和交通方面提供国内援助 信息。

您的开发团队必须将这些新的定向服务添加到其现有组织中。产品 例如，国内方向是可以在 Salesforce 中自定义的对象。当您添加 对象并自定义您的组织，您可以更改其元数据。创建 自定义产品是元数据 API 可以提供帮助的地方。

在开发过程中使用元数据 API

目前，Zephyrus 拥有为其他 国家。若要开始构建新产品自定义项，需要现有的 Zephyrus 生产 Salesforce 组织中的配置位于单独的存储库中。这 生产组织的配置都是元数据。要将生产元数据保存在 存储库，将元数据从 Zephyrus 生产组织移动到本地文件系统。

将元数据从生产环境移动到本地文件系统

在不进行开发更改的情况下进行开发更改 影响现有配置，请使用元数据 API 将元数据移动到本地文件 系统。接下来，将元数据从本地文件系统推送到可共享的存储库，以便 发展。

检索到所有 Zephyrus 元数据后，您可以在本地或临时组织中进行开发。抓 组织是没有数据的一次性 Salesforce 环境。许多开发人员同时使用这两种工具 一起。在本地加载文件和进行更改比在临时执行要快得多 组织。开发人员通常在其本地文件系统上构建自定义项，并在临时运行测试 组织。在测试和开发时，在本地文件系统和临时组织之间移动更改。

将元数据更改移入和移出临时组织

您可以使用临时组织 使用本地文件系统来开发和测试对元数据的更改。要移动更改，请执行以下操作 在本地与 scratch 组织进行本地创建，使用元数据 API。

Zephyrus 开发团队的其他成员都有自己的自定义项。在开发和 您可以自行测试，现在是团队集成更改并在沙盒中运行测试的时候了。 沙盒是用于开发和测试集成的开发环境。

将元数据移动到集成点的沙盒

在开发过程中，使用元数据 用于将元数据移动到沙盒的 API，用于集成更改、测试和协作 团队。

在团队构建定向服务自定义并完成测试后，部署 这些组件使用元数据 API 进行生产。

将元数据部署到生产环境

在最后一步 开发周期，将自定义项从源代码管理系统（如 Git）移动到生产环境 使用元数据 API。

其他用例

您可以使用元数据 API 在 Salesforce 中进行较大的更改，例如拆分和合并 生产组织。

例如，Zephyrus 希望将公司拆分为两个部门，一个部门专门从事 国内搬迁和另一个国际搬迁。在这种情况下，您拆分了 Zephyrus 的 Salesforce 组织并决定哪些元数据属于哪个组织。元数据 API 可以将元数据移动到 新组织。

然后，假设 Zephyrus 收购了 Apollo Global Relocation，两家公司都使用 Salesforce。 要整合信息，您可以使用元数据 API 将 Apollo 组织合并到 Zephyrus 中 组织。

移动生产级更改的元数据

使用元数据 API 移动元数据 在大型更改期间，例如合并或拆分 Salesforce 组织。

您可以使用元数据 API 在开发过程中进行配置更改，这些更改是 对于其他 API 调用来说太大。例如，Zephyrus 支持多种语言，因为它们 全球客户。要为对象翻译不同的语言，请包含一个对象 每种语言的翻译文件。

进行大型元数据配置更改

元数据更适合 用于向组织部署大型更改的其他 API。

将元数据从生产环境移动到本地文件系统

在不影响现有 配置，请使用元数据 API 将元数据移动到本地文件系统。接下来，推送 元数据从本地文件系统传输到可共享的存储库，用于 发展。

在 Salesforce 上构建自定义项时，必须保留 开发周期中的现有组织。若要在不影响自定义项的情况下构建自定义项，请执行以下操作 生产组织，将生产元数据保存在版本控制系统中。Git 集成最好 使用 SFDX 工具。

首先，将所需的元数据从生产组织移动到本地文件系统。移动 元数据到本地计算机，请使用检索调用而不是源拉取。接下来，推动你的 文件复制到团队成员可通过 Git 命令访问的存储库中。这 存储库现在是团队开发的生产元数据的原始来源 周期。

现在，您的生产元数据已存储在存储库中，请将必要的元数据移回 到本地文件系统以开始开发工作。

将元数据更改移入和移出临时组织

使用临时组织来开发和测试对元数据的更改。您可以 使用 Salesforce CLI 或 Salesforce 在临时组织内部或外部执行开发 VS Code 的扩展，利用元数据 API 的强大功能。

临时组织是空的，以便开发人员可以指定确切的元数据和数据 从源代码管理系统中包含。临时组织的生命周期在 创建，1-30 天。它们是短暂的，以确保真相的来源始终是来源 控制系统，而不是组织本身。

您可以使用 Salesforce 将元数据从源代码管理系统或临时组织移动到临时组织 由于临时组织使用源跟踪来识别更改，因此 CLI 是最 在本地存储库和临时组织之间移动元数据的有效方法。继续 遍历在本地文件系统和 暂存组织，直到开发完成。

将元数据移动到集成点的沙盒

在开发过程中，使用元数据 API 将元数据移动到沙盒 集成更改、测试并与您的团队协作。

在临时组织或本地文件系统中自行开发后，将 团队在沙盒中的集成点。沙盒是您可以使用的开发环境 集成和测试来自多个开发人员的更改。管理员通常会创建和分配沙盒。 要在 Salesforce UI 上创建沙盒，请导航到设置。接下来，在“快速查找”框中，搜索 用于沙盒。

您有多个级别的沙盒可供选择，其中包含不同的数据量。这 Developer Sandbox 和 Developer Pro Sandbox 是用于构建的开发环境 对虚构数据进行自定义和测试更改。“部分复制”沙箱和“完整”沙箱是 加载了生产数据副本的测试环境。将元数据移动到不同的沙盒 使用元数据 API 部署命令，具体取决于您的开发和测试需求。

在元数据 API 之外，管理员通常使用更改集从一个 沙盒到另一个。与元数据 API 调用不同，您必须手动构建更改集。要添加 组件到持续集成系统中更容易，您可以自动执行元数据 API 调用 Salesforce 命令行界面。

将元数据部署到生产环境

在开发周期的最后一步中，将自定义项从 源代码控制系统（如 Git）使用元数据 API 投入生产。

当您的团队完成集成测试并准备好部署到生产环境时，请将 完成从本地环境到存储库的自定义。对于版本，请移动 通过将更新的存储库拉回本地，将元数据从存储库拉回生产环境 环境。接下来，使用元数据 API deploy 将元数据部署到生产环境 叫。

将元数据移动到生产环境需要部署调用而不是推送命令，因为 deploy 调用部署整个元数据模型，而不仅仅是元数据中的更改。

部署最近的验证

常规部署调用会执行可能需要很长时间才能完成的自动化 Apex 测试。自 跳过已验证组件的测试并快速将组件部署到生产环境，使用 Deploy 最近的验证选项。

移动生产级更改的元数据

使用元数据 API 在大型更改期间移动元数据，例如 合并或拆分 Salesforce 组织。

要拆分组织，请先检索要移动的元数据。然后，使用 deploy 调用 将这些配置推送到新组织。同样，要合并两个组织，请检索 来自一个组织的现有元数据。接下来，使用 deploy 调用将元数据从 一个组织到另一个组织。

进行大型元数据配置更改

元数据 API 比其他 API 更适合部署大型 对 Salesforce 组织的更改。

元数据 API 和调用是基于文件的，因此 异步。使用同步命令时，大型配置更改需要 加载时间过长。相反，部署和检索调用会以异步方式开始 完成时通知您的流程。由于基于文件的调用是异步的， 元数据 API 还可以处理部署请求队列。deploy()retrieve()

元数据 API 发行说明

使用 Salesforce 发行说明了解 元数据 API。

有关影响 Salesforce Platform 的更新和更改，包括元数据 API，请参阅 API 发行说明。

有关新的、已更改的和已弃用的元数据类型以及特定于元数据 API 的其他更改，请参阅 Salesforce 发行说明中的元数据 API。

元数据 API 开发人员工具

在 Salesforce CLI 上使用适用于 Visual Studio Code 的 Salesforce 扩展访问元数据 API 命令。Salesforce CLI 和 Salesforce Extensions for Visual Studio Code 简化了 使用元数据 API 的过程。访问元数据中功能的最简单方法 API 是使用 Salesforce Extensions for Visual Studio Code 或 Salesforce 这两个工具都建立在元数据 API 之上，并使用标准工具来 简化元数据 API 的使用。

  • 适用于 Visual Studio Code 的 Salesforce 扩展包括以下工具： 在 Salesforce 平台上使用轻量级、可扩展的 VS Code 进行开发 编辑 器。这些工具提供了与开发组织合作的功能 （临时组织、沙盒和 DE 组织）、Apex、Aura 组件和 视觉力。
  • 如果您使用脚本或命令行，Salesforce CLI 是理想的选择 在本地目录和 Salesforce 之间移动元数据 组织。

有关 Salesforce Extensions for Visual 的更多信息 Studio Code 或 Salesforce CLI，请参阅 Salesforce 工具和工具包。

如果您更喜欢构建自己的客户端应用程序，则 Metadata API 的基础调用 已公开供您直接使用。本指南为您提供有关工作的更多信息 直接使用元数据 API。

您可以使用元数据 API 来管理设置和自定义信息（元数据） Salesforce的。例如：

  • 将自定义项导出为 XML 元数据文件。请参阅使用 Zip 文件和 retrieve（）。
  • 在组织之间迁移配置更改。参见 deploy（） 和 retrieve（）。
  • 使用 XML 元数据文件修改现有自定义项。参见 deploy（） 和 retrieve（）。
  • 以编程方式管理自定义项。请参阅基于 CRUD 的元数据开发。

您可以在 Developer Edition 或沙箱中修改测试组织中的元数据，然后进行部署 测试了对 Enterprise、Unlimited 或 Performance Edition 中生产组织的更改。您可以 此外，还可以创建脚本，以使用自定义对象、自定义字段和其他对象填充新组织 组件。

支持的 Salesforce 版本

若要使用元数据 API，您的组织必须使用 Enterprise Edition， Unlimited Edition、Performance Edition 或 Developer Edition。如果您是现有 想要升级到 Enterprise、Unlimited 或 Performance Edition 的 Salesforce 客户， 请联系您的客户代表。

我们强烈建议您使用沙盒，它是 生产组织。企业版、无限制版和性能版随附 免费的开发者沙盒。有关详细信息，请参阅 http://www.salesforce.com/platform/cloud-infrastructure/sandbox.jsp。

或者，您可以使用 Developer Edition （DE） 组织。DE 组织提供对 Enterprise Edition 提供的所有功能，但受用户数量限制 以及存储空间的大小。DE 组织不是生产组织的副本/它提供了一个 您可以在其中构建和测试解决方案而不会影响 组织的数据。Developer Edition 帐户可在 https://developer.salesforce.com/signup 免费获得。

注意

元数据组件必须在组织中可见，元数据 API 才能对其执行操作。此外，一个 用户必须具有 API Enabled 权限才能访问元数据组件。

专业版元数据 API 访问

ISV 合作伙伴可以请求对 Professional Edition 组织的元数据 API 访问权限，这些应用程序具有以下特点 已通过 AppExchange 安全审核。访问权限是通过 API 令牌（客户端 ID）授予的。 此特殊密钥使应用程序能够向客户的 Professional 进行元数据 API 调用 版本组织。

作为 ISV 合作伙伴，可以按照以下步骤请求元数据 API 访问权限。

  1. 提交您的应用进行安全审核。请参阅安全性中的步骤 在 ISVForce 中查看 指南。
  2. 在您的应用程序获得批准后，在合作伙伴社区中的 AppExchange 和功能请求 |API 令牌请求，并为令牌类型指定 SOAP。

若要调用元数据 API，请在调用中将 API 令牌追加到 CallOptions SOAP 标头。

元数据 API 编辑访问权限

要使用元数据 API，用户必须具备以下条件。

  • 以下版本之一：企业版、无限制版或开发人员版
  • “通过元数据 API 函数修改元数据”或“修改所有数据”权限
  • 允许使用他们想要的元数据所支持的功能的权限 修改
  • 启用其部署工具（例如 Salesforce CLI、更改集或 蚂蚁迁移工具

通过元数据 API 函数修改元数据权限，用户可以访问和编辑 元数据通过元数据 API，只要用户具有访问所需的任何其他权限 某些元数据类型。此附加权限信息列在元数据中 每种元数据类型的 API 开发人员指南。具有“修改所有数据”权限的用户 可以访问和编辑所有数据。

“通过元数据 API 函数修改元数据”权限不影响直接 使用设置 UI 页面自定义元数据，因为这些页面不使用元数据 API 更新。

某些元数据（如 Apex）在系统上下文中执行，因此请注意如何委派 通过元数据 API 函数权限修改元数据。通过元数据修改元数据 API 函数权限允许部署 Apex 元数据，但不允许某些 Apex 仍需要“修改所有数据”权限的开发和调试功能。

在以下情况下，将自动启用“通过元数据 API 函数修改元数据”权限 选择“部署更改集”或“创作 Apex”权限。

当“管理提示”用户权限和“通过元数据修改元数据”API 函数时 权限组合在一起，用户可以在 Lightning Experience 中管理应用程序内指导。

开发平台

元数据 API 支持基于文件和基于 CRUD 的开发。

基于文件的开发

声明性或基于文件的异步元数据 API deploy（） 和 retrieve（） 操作 部署或检索包含组件的文件 一组文件夹和一个名为 package.xml 的清单文件。查看更多 信息，请参阅部署和检索 元数据。访问基于文件的功能的最简单方法是使用 适用于 Visual Studio Code 的 Salesforce 扩展或 Ant 迁移工具。.zip

基于 CRUD 的开发

CRUD 元数据 API 调用作用于元数据组件 其方式类似于企业 WSDL 中同步 API 调用的行为方式 在对象上。有关企业 WSDL 的更多信息，请参见《SOAP API 开发人员指南》。

标准符合性

元数据 API 的实现符合以下规范：

标准名称网站
简单对象访问协议 （SOAP） 1.1http://www.w3.org/TR/2000/NOTE-SOAP-20000508/
Web 服务描述语言 （WSDL） 1.1http://www.w3.org/TR/2001/NOTE-wsdl-20010315
WS-I 基本概要文件 1.1http://www.ws-i.org/Profiles/BasicProfile-1.1-2004-08-24.html

元数据 API 支持策略

Salesforce 支持以前版本的元数据 API。但是，您的新客户端应用程序 应使用最新版本的 Lightning 平台元数据 API WSDL 文件，以完全 利用更丰富的功能和更高的效率。

向后兼容性

Salesforce 努力使使用 Lightning 平台时的向后兼容性变得容易。

每个新的 Salesforce 版本都由两个组件组成：

  • 驻留在 Salesforce 系统上的平台软件的新版本
  • API 的新版本

例如，Spring ’07 版本包括 API 版本 9.0 和 Summer ’07 版本 包括 API 版本 10.0。

我们维护对平台软件各个版本的每个 API 版本的支持。该 API 是 向后兼容，因为为使用给定 API 版本而创建的应用程序将 在将来的平台软件版本中继续使用相同的 API 版本。

Salesforce 不保证针对一个 API 版本编写的应用程序能够正常工作 对于未来的 API 版本：方法签名和数据表示形式的更改通常是 当我们继续增强 API 时，需要。但是，我们努力使 API 保持一致，以免 版本到版本，将应用程序移植到较新的 API 所需的更改（如果有）最少 版本。

例如，使用 Spring 附带的 API 版本 9.0 编写的应用程序 ’07 版本，将继续在 Summer ’07 版本上使用 API 版本 9.0， 以及以后的版本。但是，同一应用程序可能无法与 API 一起使用 版本 10.0，无需对应用程序进行修改。

API 生命周期终止政策

查看支持、不支持的元数据 REST 和 SOAP API 版本，或者 不能利用的。

Salesforce 承诺支持每个 API 版本至少 3 个 自首次发布之日起的年。为了提高质量和性能 API，有时不再支持超过 3 年的版本。

Salesforce 通知使用计划的 API 版本的客户 为 折旧 至少 1 年后，对版本的支持将结束。

Salesforce API 版本版本支持状态版本停用信息
版本 31.0 至 59.0支持。
版本 21.0 至 30.0截至 22 年夏季，这些版本已被弃用，并且没有 Salesforce 支持的时间更长。从 25 年夏季开始，这些 版本将停用且不可用。Salesforce Platform API 版本 21.0 到 30.0 停用
版本 7.0 至 20.0自 22 年夏季起，这些版本已停用，并且 不能利用的。Salesforce Platform API 版本 7.0 到 20.0 停用

如果你 请求任何资源或使用已停用的 API 版本 REST API 中的操作 返回错误代码。410:GONE

如果您要求任何 资源或使用已停用的 API 版本中的操作，SOAP API 将返回错误代码。500:UNSUPPORTED_API_VERSION

识别 从旧的或不受支持的 API 版本发出的请求，请使用 API 总使用量事件类型。

相关资源

Salesforce 开发人员网站提供一整套开发人员工具包、示例代码、示例 SOAP 消息、基于社区的支持和其他资源可帮助您进行开发 项目。请务必访问 https://developer.salesforce.com/page/Getting_Started 了解更多信息 信息，或访问 https://developer.salesforce.com/signup 注册一个免费的 Developer Edition 帐户。

您可以访问以下网站以了解有关 Salesforce 应用程序的更多信息：

  • Salesforce 开发人员提供有用的信息 开发 人员。
  • Salesforce 用于 有关 Salesforce 应用程序的信息。
  • 闪电平台 AppExchange，用于访问为 Salesforce 创建的应用程序。
  • 开拓者 社区提供服务，以确保 Salesforce 客户取得成功。