文档AEM用户指南

[AEM Forms]{class="badge positive" title="适用于AEM Forms)。"}

使用表单数据模型 (FDM) work-with-form-data-model

最近更新： 2026年9月25日
  • 适用对象：
  • Experience Manager as a Cloud Service

创建对象：

  • Beginner
  • Intermediate
  • Admin
  • User
版本
文章链接
AEM 6.5
单击此处
AEM as a Cloud Service
本文

表单数据模型(FDM)编辑器​提供了一个直观的用户界面和集成工具，用于在Adobe Experience Manager (AEM) Forms中创建、编辑和配置​表单数据模型(FDM)。 使用该编辑器，您可以直接从表单数据模型(FDM)中的关联数据源添加和配置​数据模型对象、属性​和​服务。

表单数据模型编辑器的功能

数据集成

表单数据模型编辑器支持以下关键任务：

  • 将关联数据源中的数据模型对象、属性和服务​添加并配置到FDM中。
  • 创建没有数据源的数据模型对象和属性。 您可以先定义这些对象，然后再将它们与相应的数据模型对象和属性绑定，这会使设计与源配置分离。
  • 生成并编辑数据模型对象属性的示例数据。 此示例数据在预览期间预填充自适应Forms，因此作者和测试者在部署之前使用现实值验证表单行为。
  • 测试在FDM中配置的数据模型对象和服务，以确认它们与基础数据源正确集成。

先决条件

如果您是初次使用Forms数据集成，并且尚未配置数据源或创建表单数据模型(FDM)，请参阅以下主题：

有关您可以使用表单数据模型编辑器执行的各种任务和配置的详细信息，请参阅。

NOTE
您必须是​ fdm-author ​和​ forms-user ​组的成员才能创建和使用表单数据模型(FDM)。 请与您的Experience Manager管理员联系以成为这些组的成员。

添加数据模型对象和服务 add-data-model-objects-and-services

如果您使用数据源创建了表单数据模型(FDM)，则可以使用表单数据模型编辑器来添加数据模型对象和服务，配置其属性，在数据模型对象之间构建关联，以及测试表单数据模型(FDM)和服务。 这样，您就可以在单个编辑环境中直接从连接的数据源汇编完整、功能齐全的数据模型。

您可以在表单数据模型(FDM)中添加来自可用数据源的数据模型对象和服务。 您添加的数据模型对象显示在“模型”选项卡中，而您添加的服务显示在“服务”选项卡中，这两个对象类型保持明确的分离，以便于配置和测试。

要添加数据模型对象和服务，请执行以下操作：

  1. 登录Experience Manager创作实例，导航到​Forms >数据集成，然后打开要向其中添加数据模型对象的表单数据模型(FDM)。

  2. 在数据源窗格中，展开数据源以查看可用的数据模型对象和服务。

  3. 选择要添加到表单数据模型(FDM)的数据模型对象和服务，然后选择​添加选定项。 这会将所选对象和服务添加到FDM中，以便您可以配置其属性并建立它们之间的关联。

    选定对象

    选定的数据模型对象和服务

    模型​选项卡以图形方式显示所有数据模型对象及其添加到表单数据模型(FDM)的属性。 每个数据模型对象在表单数据模型(FDM)中用一个框来表示，从而使模型的结构易于直观地扫描。

    模型选项卡

    模型​选项卡显示添加的数据模型对象

    note
    NOTE
    您可以按住并拖动数据模型对象框，以便在内容区域中组织它们。 在表单数据模型(FDM)中添加的所有数据模型对象在“数据源”窗格中都显示为灰色，表示这些对象已添加并防止出现重复条目。

    服务​选项卡列出了已添加的服务。

    services-tab

    服务​选项卡显示数据模型服务

    note
    NOTE
    除了数据模型对象和服务之外，OData（开放数据协议）服务元数据文档还包括导航属性，其定义两个数据模型对象之间的关联并允许遍历相关数据。 有关详细信息，请参阅使用OData服务的导航属性。

  4. 选择​ 保存 ​以保存表单模型对象。

    note
    NOTE
    您在表单数据模型(FDM)的“服务”选项卡中配置的服务可以直接使用自适应表单规则调用，从而允许表单作者触发数据操作，例如在运行时获取或写入数据。 配置的服务可在规则编辑器的Invoke services操作中使用。 有关在自适应表单规则中使用这些服务的更多信息，请参阅规则编辑器中的“调用服务和设置规则值”。

创建数据模型对象和子属性 create-data-model-objects-and-child-properties

数据模型​将信息组织为称为​ 对象 ​的结构化、可重用的单元，每个对象都可以包含描述对象各个属性的​子属性。 创建定义良好的对象并在其下嵌套子属性是构建任何数据模型的基础步骤，因为它可为应用程序将存储、验证和交换的信息建立清晰、分层的表示形式。

什么是数据模型对象和子属性？

  • 数据模型对象​是一个命名容器，用于将相关字段分组到单个逻辑实体中。 对象表示真实世界或概念性项目（如客户、订单或产品），并充当其他元素所附加的顶层结构。
  • 子属性​是嵌套在对象中的各个字段。 每个子属性定义父对象的一个属性，以及诸如其名称、数据类型以及值是否必需的属性。 在父对象下嵌套属性可将相关数据分组在一起，从而提高清晰度并使模型更易于维护。

这种父子关系赋予数据模型其层次结构。 对象充当父项，而子属性会从中继承其上下文，从而确保每个属性都明确与它所描述的实体相关联。

如何创建数据模型对象

按照以下步骤在数据模型中定义新对象：

  1. 命名对象。 选择用于标识对象所代表的实体的清晰描述性名称。 一致的命名使模型更易于以后读取和引用。
  2. 将对象定义为容器。 将对象建立为将保存其关联子属性的顶级元素。
  3. 添加子属性。 附加描述对象属性的各个字段，依次定义每个字段。
  4. 为每个属性分配数据类型。 指定每个子属性接受的值的类型（如文本、数字或布尔值），以便正确验证数据。
  5. 设置要求规则。 指明哪些子属性是必需的，哪些是可选的，确保模型强制实施应用程序所依赖的约束。

添加子属性

将子属性添加到对象时，请使用以下详细信息定义每个属性：

  • 属性名称 — 父对象中属性的唯一描述性标签。
  • 数据类型 — 属性存储的值的类型，它控制如何验证和处理该值。
  • 必需或可选状态 — 属性是否必须始终有值。
  • 嵌套结构（如果适用） — 子属性本身可以是具有自己的子属性的对象，从而允许您对复杂的多级别数据进行建模。 这种嵌套使得数据模型能够表示深度结构化的信息。

实际应用和优势

使用对象和子属性结构化数据模型可提供几个实际优势：

  • 一致性 — 将共享对象下的相关字段分组，以确保在应用程序中统一存储和解释数据。
  • 可重用性 — 可在多个位置引用定义良好的对象，从而减少重复。
  • 验证 — 为子属性分配数据类型和要求规则可让系统自动捕获无效或不完整的数据。
  • 可伸缩性 — 由于对象支持嵌套的子属性，因此模型可以增长以表示日益复杂的关系，而不会变得杂乱无章。

最佳做法

  • 为对象及其子属性使用清楚的描述性名称来保持模型自记录。
  • 将相关属性分组到同一父对象下，而不是将其分散到不相关的结构中。
  • 尽早定义数据类型和需求规则，因为这样做可以从一开始就建立可靠的验证。
  • 有意义地保持嵌套 — 仅在附加层次有效地反映数据的结构时才嵌套子属性。

通过仔细定义对象及其子属性，您可以创建一个数据模型，该模型可以有条理地组织、可维护并能够准确地表示应用程序所使用的实体。

创建数据模型对象 create-data-model-objects

虽然可以从配置的数据源添加数据模型对象，但也可以创建没有数据源的数据模型对象（也称为实体）。 数据模型对象​是表单数据模型(FDM)中的结构化实体，它表示属性的逻辑分组，以后可以绑定到数据源字段或单独使用。 当您尚未在表单数据模型(FDM)中配置数据源时，此功能特别有用，因为它允许您在构建任何后端集成之前开始设计数据结构。

创建没有数据源的数据模型对象的步骤

要创建没有数据源的数据模型对象，请执行以下操作：

  1. 登录Experience Manager创作实例，导航到​Forms >数据集成，然后打开要在其中创建数据模型对象或实体的表单数据模型(FDM)。

  2. 选择​创建实体。

  3. 在创建数据模型对话框中，指定数据模型对象的名称并选择​添加。 数据模型对象将添加到表单数据模型(FDM)。 新添加的数据模型对象未绑定到数据源，并且不具有任何属性，如下图所示。 由于此对象未绑定，因此它仅作为结构占位符存在，直到您定义其属性或将其连接到数据源为止。

    new-entity

后续步骤 next-steps-data-model-object

创建未绑定数据模型对象后，添加子属性以定义其结构。 这些子属性允许您指定对象包含的字段和属性，并且可在配置数据集成后将其绑定到数据源。 这可确保数据模型对象具有完全功能并可在表单中使用。

添加子属性 child-properties

表单数据模型(FDM)编辑器允许您在数据模型对象中创建子属性。 默认情况下，新创建的子属性未绑定到数据源中的任何属性。 您稍后可以将子属性绑定到包含数据模型对象中的另一个属性。

要创建子属性，请执行以下操作：

  1. 在表单数据模型中，选择一个数据模型对象，然后选择​创建子属性。

  2. 在​ 创建子属性 ​对话框中，在​ 名称 ​和​ 类型 ​字段中分别指定属性的名称和数据类型。 您可以选择为属性指定标题和描述。

  3. 如果属性是​计算属性，则启用​Computed，该属性的值是根据​ 规则或表达式 ​计算的，而不是直接输入的。 有关详细信息，请参阅编辑属性。

  4. 如果数据模型对象绑定到数据源，则添加的子属性将自动绑定到具有相同名称和数据类型的父数据模型对象的属性。 此自动绑定在名称和数据类型上均匹配，确保子属性与其父属性保持一致，而无需其他手动步骤。

    要手动绑定子属性与数据模型对象属性，请选择​ 绑定引用 ​字段旁边的浏览图标。 选择对象​对话框列出了父数据模型对象的所有属性。 选择要绑定的属性，然后选择勾号图标。 您只能选择与子属性具有相同数据类型的属性，因为有效绑定需要数据类型匹配。

  5. 选择​ 完成 ​保存子属性，选择​ 保存 ​保存表单数据模型(FDM)。 现在，子属性已添加到数据模型对象中。

创建数据模型对象和属性后，您可以继续基于表单数据模型(FDM)创建自适应Forms。 之后，当您具有可用数据源并配置好数据源时，可以将表单数据模型(FDM)与数据源绑定。 因此，绑定会在所有关联的自适应Forms中自动更新，因此更改无需手动重新配置即可传播。 有关使用表单数据模型(FDM)创建自适应Forms的更多信息，请参阅使用表单数据模型。

绑定数据模型对象和属性 bind-data-model-objects-and-properties

当要与表单数据模型(FDM)集成的数据源可用时，可将其添加到表单数据模型(FDM)，如更新数据源中所述。 未绑定的数据模型对象或属性​存在于表单数据模型(FDM)中，但尚未映射到连接的数据源中的字段，因此在建立绑定之前，无法读取或写入数据。 然后，执行以下操作以绑定未绑定的数据模型对象和属性：

  1. 在表单数据模型中，选择要与数据源绑定的未绑定数据源。

  2. 选择​编辑属性。

  3. 在​ 编辑属性 ​窗格中，选择​ 绑定 ​字段旁边的浏览图标。 浏览图标会打开​ 选择对象 ​对话框，其中列出了在表单数据模型(FDM)中添加的数据源。

    select-object

  4. 展开数据源树并选择要绑定的数据模型对象，然后选择勾号图标。

  5. 选择​ 完成 ​以保存属性，然后选择​ 保存 ​以保存表单数据模型。 数据模型对象现在与数据源绑定。 这可确保对象在运行时能够读取和写入连接的数据源。 保存后，数据模型对象不再标记为“未绑定”，从而确认绑定已完成。

    绑定模型对象

配置服务 configure-services

通过配置读写服务，数据模型对象可以读写表单数据模型(FDM)中的数据。 要为数据模型对象配置读写服务，请完成以下步骤：

  1. 选中数据模型对象顶部的复选框以将其选中，然后选择​编辑属性。

    编辑 — 属性

    编辑属性以配置数据模型对象的读写服务

    将打开编辑属性对话框。

    edit-properties-2

    “编辑属性”对话框

    note
    NOTE
    除了数据模型对象和服务之外，OData（开放数据协议）服务元数据文档还包括定义两个数据模型对象之间关联的​导航属性。 在将OData服务数据源添加到表单数据模型(FDM)时，表单数据模型(FDM)中会提供一个可用于数据模型对象中所有导航属性的服务。 您可以使用此服务读取相应数据模型对象的导航属性。
    有关使用该服务的详细信息，请参阅使用OData服务的导航属性。

  2. 切换​ 顶级对象 ​以指定数据模型对象是否为顶级模型对象。

    在表单数据模型(FDM)中配置的数据模型对象可用于基于表单数据模型(FDM)的自适应表单内容浏览器中的“数据模型对象”选项卡。 在两个数据模型对象之间添加关联时，与关联的数据模型对象嵌套在​ 数据模型对象 ​选项卡中的关联数据模型对象下。 如果嵌套数据模型是顶级对象，则它还会单独出现在​ 数据模型对象 ​选项卡中。 因此，对象出现两次（一个条目在嵌套层次结构内，另一个条目在嵌套层次结构外），这会使表单作者感到困惑。 若要使关联的数据模型对象仅显示在嵌套层次结构中，请禁用​ 顶级对象 ​属性。 这可确保表单作者看到单个明确条目，从而减少表单创作期间的混淆。

  3. 为所选数据模型对象选择​ 读取 ​和​ 写入 ​服务。 随后将显示所选服务的参数以进行配置。

    读写服务

    为员工数据源配置的读写服务

  4. 为读取服务参数选择 aem63edit 以将参数绑定到用户配置文件属性、请求属性或文本值🔗，并指定绑定值。

  5. 选择​ 完成 ​以保存参数，选择​ 完成 ​以保存属性，选择​ 保存 ​以保存表单数据模型(FDM)。

绑定读取服务参数 bindargument

基于绑定值，将Read服务参数绑定到三种绑定类型之一 — 用户配置文件属性、请求属性​或​文本值。 读取服务使用此值作为参数，从数据源获取与指定值关联的详细信息。 每个绑定类型都确定参数值的来源：固定输入、登录用户的配置文件或传入请求。

文本值 literal-value

从​ 绑定到 ​下拉菜单中选择​文本，然后在​ 绑定值 ​字段中输入值。 从数据源中检索与值关联的详细信息。 使用此选项可检索与静态值关联的详细信息，因为文本绑定提供不依赖于用户或请求的固定且未更改的输入。

在此示例中，与​ 4367655678 ​关联的详细信息作为​ mobilenum ​参数的值从数据源中检索。 在传递手机号码参数的值时返回的相关详细信息可以包括客户名称、客户地址和城市等属性。

文本值

用户配置文件属性 user-profile-attribute

从​ 绑定到 ​下拉菜单中选择​用户配置文件属性，然后在​ 绑定值 ​字段中输入属性名称。 基于属性名称，从数据源检索登录Experience Manager实例的用户详细信息。

在​ 绑定值 ​字段中指定的属性名称必须包含完整的绑定路径，直到用户的属性名称为止。 打开以下URL以访问CRXDE上的用户详细信息：

https://[server-name]:[port]/crx/de/index.jsp#/home/users/

用户轮廓

在此示例中，在grios用户的​ 绑定值 ​字段中指定​profile.empid。

编辑参数

id参数从用户配置文件中获取​ empid ​属性的值，并将其作为参数传递给读取服务。 然后，读取服务从与登录用户关联的empid的员工数据模型对象中读取并返回关联属性的值。

请求属性 request-attribute

使用请求属性绑定，根据传入请求中提供的值从数据源检索关联的属性。

  1. 从​ 绑定到 ​下拉菜单中选择​请求属性，然后在​ 绑定值 ​字段中输入属性名称。

  2. 为head.jsp创建一个叠加。 要创建叠加，请打开CRX DE并将https://<server-name>:<port number>/crx/de/index.jsp#/libs/fd/af/components/page2/afStaticTemplatePage/head.jsp文件复制到https://<server-name>:<port number>/crx/de/index.jsp#/apps/fd/af/components/page2/afStaticTemplatePage/head.jsp

    note
    NOTE
    • 如果使用静态模板，请将head.jsp覆盖在：
      /libs/fd/af/components/page2/afStaticTemplatePage/head.jsp
    • 如果您使用可编辑的模板，请在以下位置叠加aftemplatedpage.jsp：
      /libs/fd/af/components/page2/aftemplatedpage/aftemplatedpage.jsp

  3. 为请求属性设置paramMap。 例如，将以下代码加入apps文件夹中的.jsp文件中：

    code language-javascript 
    <%Map paraMap = new HashMap();
 paraMap.put("<request_attribute>",request.getParameter("<request_attribute>"));
 request.setAttribute("paramMap",paraMap);

    例如，使用以下代码从数据源检索petId的值：

    code language-javascript 
    <%Map paraMap = new HashMap();
paraMap.put("petId",request.getParameter("petId"));
request.setAttribute("paramMap",paraMap);%>

因此，读取服务会根据请求中指定的属性名称从数据源检索详细信息。

例如，在请求中将属性指定为petid=100将从数据源检索与该属性值关联的属性。

添加关联 add-associations

通常在数据源中的数据模型对象之间建立关联，当对象被引入表单数据模型(FDM)中时，这些关联将保留。 关联定义了两个数据模型对象之间的关系，可以是​ 一对一 ​或​一对多。

当单个记录与多个记录相关联时，存在​ 一对多 ​关联。 例如，员工可以有多个与员工记录关联的家属。 此关系称为一对多关联，由1:n在连接关联的数据模型对象的行上描述。 当关系只返回一个匹配记录时，存在​ 一对一 ​关联 — 例如，当关联返回给定员工ID的唯一员工名称时，它是一对一关联。

将关联的数据模型对象从数据源添加到表单数据模型(FDM)时，会保留它们的关联并将其显示为用箭头线连接。 您还可以在单个表单数据模型(FDM)中跨不同的数据源添加数据模型对象之间的关联，这允许您组合来自不同后端系统的相关数据。

NOTE
Java数据库连接(JDBC)数据源中的预定义关联不会保留在表单数据模型(FDM)中，因为这些关系不会自动转移。 您必须手动创建它们。

要添加关联，请执行以下操作：

  1. 选中数据模型对象顶部的复选框以将其选中，然后选择​添加关联。 将打开“添加关联”对话框。

    添加关联

    note
    NOTE
    除了数据模型对象和服务之外，开放数据协议(OData)服务元数据文档包括定义两个数据模型对象之间的关联的导航属性。 在表单数据模型(FDM)中添加关联时，可以使用这些导航属性。 有关详细信息，请参阅使用OData服务的导航属性。

    将打开添加关联对话框。

    add-association-2

    “添加关联”对话框

  2. 在“添加关联”窗格中：

    • 指定关联的标题。
    • 选择关联类型 — 一对一​或​一对多。
    • 选择要关联的数据模型对象。
    • 选择读取服务以从选定的模型对象中读取数据。 此时将显示读取服务参数。 编辑参数以根据需要对其进行更改，并将其绑定到要关联的数据模型对象的属性。

    在以下示例中， Dependents数据模型对象的读取服务的默认参数是dependentid。

    add-association-example

    依赖项读取服务的默认参数是依赖的

    但是，参数必须是关联数据模型对象之间共享的公用属性，在本例中为Employeeid。 因此，由于关联依赖于匹配的键，因此Employeeid参数必须绑定到Employee数据模型对象的id属性。 此绑定使系统能够从“依存对象”数据模型对象获取关联的依存对象详细信息。

    add-association-example-2

    已更新参数和绑定

    选择​ 完成 ​以保存参数。

  3. 选择​ 完成 ​保存关联，然后选择​ 保存 ​保存表单数据模型(FDM)。

  4. 根据需要重复这些步骤以创建其他关联。

NOTE
所添加的关联将显示在数据模型对象框中，其中包含指定的标题和连接关联的数据模型对象的线。
通过选中关联对应的复选框并选择​编辑关联，可以编辑关联。

已添加关联

编辑属性 properties

通过编辑属性，您可以配置数据模型对象、其属性和服务在​ 表单数据模型(FDM) ​中的行为方式。 通过​ 编辑属性 ​窗格，您可以定义用于确定FDM如何读取、写入和返回数据的服务、数据类型、键和参数。

要编辑属性，请执行以下操作：

  1. 选中​ 表单数据模型(FDM) ​中数据模型对象、属性或服务旁边的复选框。

  2. 选择​编辑属性。 将打开选定模型对象、属性或服务的​ 编辑属性 ​窗格。

    • 数据模型对象：指定​ 读取和写入服务 ​并编辑参数。 这些服务确定如何从对象的基础数据源检索数据并将其保留到该数据源。

    • 属性：为属性指定​类型、子类型​和​格式。 您还可以将选定的属性指定为数据模型对象的​主键，该主键唯一标识每个记录。

    • 服务：指定服务的输入模型对象、输出类型和参数。 对于​Get服务，您可以指示它是否返回数组，以确保该服务正确处理多个记录。

      edit-properties-service

    获取服务的“编辑属性”对话框

  3. 选择​ 完成 ​保存属性配置，然后选择​ 保存 ​保存​表单数据模型(FDM)。 此最终保存将所有属性更改提交到FDM。

创建计算属性 computed

计算属性​自动从规则或表达式派生其值。 通过使用规则，您可以将计算属性的值设置为​ 表单数据模型(FDM) ​中的文字字符串、数字、数学表达式的结果或其他属性的值。 由于此值是计算值，而不是手动输入，因此计算属性可减少数据输入错误，并在基础数据更改时保持相关字段一致。

示例：构建FullName计算属性

例如，您可以创建一个计算属性​FullName，其值是连接现有​ FirstName ​和​ LastName ​属性的结果。 为此，请执行以下步骤：

  1. 创建名为FullName且数据类型为​ String ​的新属性。

  2. 启用​ Computed ​并选择​ Done ​以创建该属性。

    已计算

    已创建​ FullName ​计算属性。 该属性旁边会显示一个图标，指示它是计算属性。

    计算属性

  3. 选择​ 全名 ​属性，然后选择​编辑规则。 此时将打开规则编辑器窗口。

  4. 在规则编辑器窗口中，选择​创建。 将打开​ 设置值 ​规则窗口。

    从​ 选择选项 ​下拉列表中选择​数学表达式。 其他可用选项为​ 表单数据模型对象 ​和​字符串。

  5. 在数学表达式中，选择​ FirstName ​作为第一个对象，选择​ LastName ​作为第二个对象。 选择​ 加 ​作为运算符。

    选择​完成，然后选择​ 关闭 ​以关闭规则编辑器窗口。 完成的规则类似于以下内容。

    规则

  6. 在​ 表单数据模型(FDM) ​上，选择​保存。 已配置计算属性。 这样可以确保每当​ FirstName ​或​ LastName ​更改时，FullName​值都会自动更新，因此串联的全名始终与源字段保持同步。

使用OData服务的导航属性 work-with-navigation-properties-of-odata-services

OData服务中的​ 导航属性 ​定义两个数据模型对象之间的关联，从而确定一个实体如何与另一个实体关联并可遍历到另一个实体。 这些属性是在​ 实体类型 ​或​ 复杂类型 ​上定义的，它们允许客户端从一个记录移动到其相关记录。 例如，在从示例TripPin OData示例服务的元数据文件中提取的以下内容中，人员​实体包含三个导航属性：Friends、BestFriend​和​Trips。

有关导航属性的详细信息，请参阅OData文档。

<edmx:Edmx xmlns:edmx="https://docs.oasis-open.org/odata/ns/edmx" Version="4.0">
<script/>
<edmx:DataServices>
<Schema xmlns="https://docs.oasis-open.org/odata/ns/edm" Namespace="Microsoft.OData.Service.Sample.TrippinInMemory.Models">
<EntityType Name="Person">
<Key>
<PropertyRef Name="UserName"/>
</Key>
<Property Name="UserName" Type="Edm.String" Nullable="false"/>
<Property Name="FirstName" Type="Edm.String" Nullable="false"/>
<Property Name="LastName" Type="Edm.String"/>
<Property Name="MiddleName" Type="Edm.String"/>
<Property Name="Gender" Type="Microsoft.OData.Service.Sample.TrippinInMemory.Models.PersonGender" Nullable="false"/>
<Property Name="Age" Type="Edm.Int64"/>
<Property Name="Emails" Type="Collection(Edm.String)"/>
<Property Name="AddressInfo" Type="Collection(Microsoft.OData.Service.Sample.TrippinInMemory.Models.Location)"/>
<Property Name="HomeAddress" Type="Microsoft.OData.Service.Sample.TrippinInMemory.Models.Location"/>
<Property Name="FavoriteFeature" Type="Microsoft.OData.Service.Sample.TrippinInMemory.Models.Feature" Nullable="false"/>
<Property Name="Features" Type="Collection(Microsoft.OData.Service.Sample.TrippinInMemory.Models.Feature)" Nullable="false"/>
<NavigationProperty Name="Friends" Type="Collection(Microsoft.OData.Service.Sample.TrippinInMemory.Models.Person)"/>
<NavigationProperty Name="BestFriend" Type="Microsoft.OData.Service.Sample.TrippinInMemory.Models.Person"/>
<NavigationProperty Name="Trips" Type="Collection(Microsoft.OData.Service.Sample.TrippinInMemory.Models.Trip)"/>
</EntityType>

导航属性在表单数据模型中的显示方式

在​ 表单数据模型(FDM) ​中配置OData服务时，实体容器中的所有导航属性将自动通过FDM中的单个服务变为可用。 此合并意味着您不需要为每个关联分别使用服务，因为FDM会将它们显示在一起。 在TripPin OData服务的此示例中，Person实体容器中的三个导航属性都可以使用FDM中的一个​ GET LINK ​服务读取。

下面重点介绍了FDM中的​ GET LINK of Person /People ​服务，它是TripPin OData服务Person实体中的三个导航属性 — Friends、BestFriend​和​Trips — 的组合服务。

nav-prop-service

配置GET LINK服务

将​ GET LINK ​服务添加到FDM中的​ 服务 ​选项卡后，可以编辑其属性以选择要在服务中使用的输出模型对象和导航属性。 例如，以下​ GET LINK of Person /People ​服务使用​ Trip ​作为输出模型对象，使用​ Trips ​作为导航属性。

edit-prop-nav-prop

NOTE
NavigationPropertyName​参数的​ 默认值 ​字段中可用的值取决于​ 返回数组？ ​的状态 切换按钮。 启用后，该字段将显示​ 收藏集 ​类型的导航属性。

在此示例中，您还可以选择​ Person ​作为输出模型对象，并将导航属性参数设置为​ Friends ​或​BestFriend，具体取决于​返回数组？ 启用或禁用。

edit-prop-nav-prop2

在关联中使用导航属性

同样，在FDM中添加关联时，您可以选择一个​ GET LINK ​服务并配置其导航属性。 但是，只有当​ 绑定到字段 ​设置为​ 文本 ​时，才能选择导航属性；由于此要求，在正确配置该绑定之前，导航属性选项不可选。

add-association-nav-prop

生成和编辑示例数据 sample

表单数据模型(FDM)编辑器​为表单数据模型中的所有数据模型对象属性（包括​计算属性）生成​示例数据。 此示例数据包含一组符合为每个属性配置的​ 数据类型 ​的随机值，为您提供了实际的测试值，而无需实时数据源连接。

关于示例数据

示例数据用作现成的测试输入，允许您在将表单数据模型捆绑到生产数据之前预览和验证表单数据模型的行为方式。 由于每个生成的值都遵循其属性的配置数据类型，因此示例集反映了实际记录的预期结构和格式，这有助于在开发早期验证绑定、计算逻辑和表单行为。

您还可以编辑生成的值并保存更改。 即使重新生成示例数据，保存的数据也会保留，因此手动策划的测试用例会在重新生成之间保留。 这使得构建稳定、可重用的测试场景变得可行，而不是在每次产生新的随机值时丢失编辑。

生成和编辑示例数据的步骤

  1. 打开​ 表单数据模型(FDM) ​并选择​编辑示例数据。 FDM编辑器在​ 编辑示例数据 ​窗口中生成并显示示例数据。

    生成示例数据

  2. 在​ 编辑示例数据 ​窗口中，根据需要编辑数据，然后选择​保存。 编辑的示例数据将被保存并保留，即使在重新生成示例数据之后仍然可用。

测试数据模型对象和服务 test-data-model-objects-and-services

配置表单数据模型(FDM)后，请先测试配置的数据模型对象和服务，然后再以实时表单部署FDM，以确认它们按预期运行。 部署前测试可验证每个对象和服务是否返回了正确的数据，从而减少将表单投入生产时出现运行时错误的风险。

要测试数据模型对象和服务，请执行以下操作：

  1. 在表单数据模型(FDM)中选择数据模型对象或服务，然后分别选择​ 测试模型对象 ​或​测试服务。

    测试表单数据模型​窗口打开。

    test-data-model

  2. 在​ 测试表单数据模型 ​窗口中，从​ 输入 ​窗格中选择要测试的数据模型对象或服务。 这会标识要验证的特定对象或服务。

  3. 在测试代码中指定一个参数值，然后选择​测试。 成功的测试会在​ 输出 ​窗格中返回输出，确认所选对象或服务已正确配置，并能够按预期检索或处理数据。

    测试结果

按照相同的过程，您可以在表单数据模型(FDM)中验证其他数据模型对象和服务，以确保整个模型在使用之前可靠执行。

自动验证输入数据 automated-validation-of-input-data

每当调用​ DermisBridge API ​时，表单数据模型(FDM)​就会应用表单数据模型中定义的验证条件，自动验证作为输入接收的数据。 此验证由用于调用API的查询对象中设置的​ ValidationOptions ​标志控制。 默认情况下，当没有为ValidationOptions标志设置值时，FDM将对输入数据执行​ BASIC ​验证。

ValidationOptions标志级别

ValidationOptions标记接受以下三个值中的任意一个，每个值都定义了FDM验证输入的严格程度：

  • FULL： FDM根据​ 所有定义的约束 ​验证输入。 使用此级别在处理数据之前强制实施每个数据类型和业务规则约束。
  • 禁用： FDM执行​无验证。 输入数据无需任何约束检查即可通过。
  • BASIC： FDM仅验证​ required ​和​ nullable ​约束。 这样可以确保存在必填字段，并且不评估完整约束集就遵循null处理规则。

如果未为ValidationOptions标志设置任何值，则FDM默认应用​ BASIC ​验证。

设置验证标志

以下示例将验证标志设置为​FULL，从而启用对所有约束的验证：

operationOptions.setValidationOptions(ValidationOptions.FULL);
NOTE
为输入数据中的属性提供的值必须与元数据文档中为该属性定义的数据类型匹配。
由于数据类型检查是独立于验证级别强制执行的，因此如果提供的值与定义的数据类型不匹配，则无论ValidationOptions标志​的值如何， DermisBridge API 都会返回异常。 当日志级别设置为​ Debug ​时，API将相应错误记录到​ error.log ​文件。

按数据源的数据类型约束

表单数据模型(FDM)​根据定义的数据类型约束列表验证输入数据。 此约束列表可能因基础​ 数据源 ​而异，因此在验证期间强制使用的确切约束由与表单数据模型关联的数据源确定。

下表列出了应用于每个受支持数据源的输入数据的数据类型约束：

约束
描述
输入数据源
必填
如果为true，则参数必须包含在输入数据中。
Swagger、WSDL和数据库
可空
如果为true，则可将输入数据中的参数值设置为Null。
WSDL、Odata和数据库
最大值
指定数值的上限。 指定为上限的最大值也可以分配给输入数据中的参数。
Swagger和WSDL
最小值
指定数字值的下限。 指定为下限的最小值也可以分配给输入数据中的参数。
Swagger和WSDL
exclusiveMaximum
指定数值的上限。 指定为上限的最大值不得分配给输入数据中的参数。
Swagger和WSDL
exclusiveMinimum
指定数字值的下限。 不得将指定为下限的最小值分配给输入数据中的参数。
Swagger和WSDL
minLength
指定字符串中包含的字符数的下限。 指定为下限的最小值也可以分配给输入数据中的参数。
Swagger和WSDL
maxLength
指定字符串中包含的字符数的上限。 指定为上限的最大值也可以分配给输入数据中的参数。
Swagger、WSDL、Odata和数据库
模式
指定固定字符序列。 仅当字符符合指定的模式时，才能成功验证输入字符串。
Swagger
minItems
指定数组中的最小项数。 指定为下限的最小值也可以分配给输入数据中的参数。
Swagger和WSDL
maxItems
指定数组中的最大项数。 指定为上限的最大值也可以分配给输入数据中的参数。
Swagger和WSDL
uniqueItems
如果为true，则数组的所有元素在输入数据中必须是唯一的。
Swagger
枚举（字符串）
将输入数据中的参数值限制为一组固定的字符串值。 它必须是一个数组，其中至少有一个元素，每个元素都是唯一的。
Swagger、WSDL和Odata
枚举（数字）
将输入数据中的参数值限制为一组固定的数值。 它必须是一个数组，其中至少有一个元素，每个元素都是唯一的。
WSDL

使用Swagger约束进行输入数据验证

仅当存在​ 订单ID ​且其值在​ 1-10 ​范围内时，输入数据才通过验证。 在此示例中，输入数据根据​ Swagger (OpenAPI) ​文件中定义的​最大、最小​和​ 必需 ​约束进行验证。 这三种约束类型管理接受的输入，如下所示：

  • 必需 — 必须提供参数；缺少的orderId验证失败。
  • 最小值 — 该值不能小于​1。
  • maximum — 该值不能超过​10。

由于约束直接在API定义中声明，因此在执行操作之前，会在架构级别自动执行验证。 这可确保只有格式正确的请求才能访问底层服务。

   parameters: [
   {
   name: "orderId",
   in: "path",
   description: "ID of pet that must be fetched",
   required: true,
   type: "integer",
   maximum: 10,
   minimum: 1,
   format: "int64"
   }
   ]

验证失败行为和错误日志记录

当输入数据不符合这些标准时，系统会引发验证异常。 由于此失败，并且日志级别设置为​ Debug ​时，错误将写入​ error.log ​文件。 此日志记录行为可帮助开发人员准确诊断违反了哪个约束，因为日志条目标识了失败参数、违反了的约束以及违规值。

例如，提交​ 16 ​的orderId超过了声明的​最大值10，从而生成以下日志条目：

21.01.2019 17:26:37.411 *ERROR* com.adobe.aem.dermis.core.validation.JsonSchemaValidator {"errorCode":"AEM-FDM-001-044","errorMessage":"Input validations failed during operation execution.","violations":{"/orderId":["numeric instance is greater than the required maximum (maximum: 10, found: 16)"]}}

该错误条目捕获错误代码​AEM-FDM-001-044、消息"Input validations failed during operation execution."和指明/orderId字段的violations块、所需的最大值​ 10 ​以及找到的值(16)。 这种结构化的细节使得识别和更正超出范围的输入变得简单明了。

后续步骤 next-steps

您有一个有效的​表单数据模型(FDM)，现在可以在自适应Forms工作流中使用。 表单数据模型表示表单捕获的数据以及与连接的数据源交换的数据的结构和关系，提供一个可重用的统一架构，自适应Forms可以直接绑定到该架构。 由于该模型将底层数据服务抽象为单一的一致层，因此它允许表单从这些源读取和写入这些源，而无需为每个新表单重新构建集成逻辑。

准备好模型后，您现在可以将其应用于表单构建任务。 常见的后续步骤包括：

  • 将表单字段绑定到模型，以便自适应表单组件直接映射到FDM中定义的数据属性，确保一致的数据捕获和提交。
  • 使用通过模型检索到的现有数据预填表单，通过减少手动数据输入来改善用户体验。
  • 配置表单提交​以通过模型将捕获的数据写回连接的数据源，并保持记录同步。
  • 跨多个表单重用模型​以保持一致性并减少重复的配置工作。

跨工作流重用单个表单数据模型可以提高一致性并降低日常维护成本，因为对模型的更新会传播到依赖它的每个表单中。 有关在自适应Forms中应用模型的详细指导，请参阅使用表单数据模型(FDM)。

recommendation-more-help
experience-manager-cloud-service-help-main-toc