操作定义

ABAP RESTful 应用程序编程模型 › 学习 › 业务对象 › RAP 业务对象供应 › RAP 业务对象行为 › 操作 › 非标准工序 › 操作 › 操作定义

在行为定义中为实体定义操作。

定义操作的语法

操作在行为定义中指定为非标准操作,并在 ABAP 行为池中实施。

有关语法的详细信息,请参阅 CDS BDL - 操作(ABAP 关键字文档)。

输入参数

有关操作输入参数的详细信息,请参阅 CDS -BDL - 输入参数(ABAP 关键字文档)。

有关在 RAP 中建模参数的详细信息,请参阅非标准操作的建模参数。

有关操作建模的详细信息,请参阅具有草稿功能的事务应用开发指南中的操作 deductDiscount。

如果输入参数实体与操作分配到的抽象实体相同,则可以指定 $self。具有 $self 的输入参数仅允许用于静态操作。原因是实例绑定操作始终导入对其执行操作的实例的密钥。如果导入相同的实体实例作为输入参数,则键值将导入两次,这将导致运行时出现短转储。有关导入参数的详细信息,请参阅导入参数。

对于 OData 服务,您可以使用默认值函数设置操作的输入参数默认值。通过计算缺省值并提供缺省值作为相应操作的结果,可将缺省值功能用作 Fiori UI 上输入参数的输入助手。然后,计算的值将显示在输入参数的弹出窗口中,该输入参数在最终用户触发操作时打开。有关操作的缺省输入参数的概念信息,请参见操作缺省设置。

输出参数

有关输出参数的详细信息,请参阅 CDS BDL - 输出参数(ABAP 关键字文档)。

有关在 RAP 中建模参数的详细信息,请参阅非标准操作的建模参数。

操作和函数的输出参数使用关键字 result 定义。结果参数是可选的。但是,如果在操作定义中声明结果参数,则必须在实施中填充。如果未填充,则即使使用大于 0 的结果基数声明操作,该操作也不会返回任何内容。在这种情况下,OData 服务返回初始值。

工厂操作通过将键值映射到使用者提供的 %cid 在 mapped 响应参数中返回其结果。

通过将操作结果声明为 selective,可以定义操作使用者可以决定是完全返回结果还是仅返回部分结果,例如仅返回键值。这有助于提高性能,因为可以从结果中排除使用已计算字段的性能。有关使用选择性结果参数实施的详细信息,请参阅操作导入参数。执行具有选择性结果的操作时,Fiori UI 仅请求结果的键值。

操作和函数的 result cardinality 确定输出的多样性。通过这种方式,它指示该操作是生成 0..1、1、0..n 还是 1..n 个输出实例。因此,基数的可能值为:[0..1]、[1]、[0..*] 或 [1..*]

您可以返回结果实体或结果结构:

  • *结果实体:*通过使用 result entity MyBOEntity 声明操作,操作将返回一个或多个实例 MyBOEntity。result $self 返回操作所分配到的实体的一个或多个实例。

    在 UI 服务中通过 $self 返回结果实体时,当前 UI 行为是它保留在执行操作的同一页面上。对于工厂操作,Fiori 元素 UI 当前导航到新创建实例的对象页面。

    备注

    在服务中,仅公开具有服务定义中包含的输出实体的操作和函数。

    在映射行为定义中,必须使用投影结果实体重新定义 $self 以外的结果实体。有关详细信息,请参阅投影行为定义中的操作。

  • *结果结构:*如果操作结果是抽象实体,则必须定义没有关键字 entity 的结果,因为抽象实体通常视为 ABAP 中的结构。

操作类型

内部操作

缺省情况下,操作可由 OData 请求以及来自其他业务对象或同一业务对象的 EML 执行。要仅为同一业务对象提供操作,可在操作名称之前设置选项 internal,例如,在执行内部状态更新时。内部操作只能从业务对象实施内的业务逻辑访问,例如通过确定或其他操作。

静态操作

缺省情况下,操作与业务对象实体的实例相关。选项 static 允许您定义未绑定到任何实例但与完整实体相关的静态操作

可重复操作

附加项 repeatable 允许您定义可在同一 EML 请求或 OData 更改集中的同一实例上多次执行的实例操作。可以使用内容标识 %CID 区分此类操作的不同执行。内容标识包含在可重复操作的派生类型中,需要在每次调用可重复操作时提供。

备注

如果在同一实例上执行绑定的非工厂操作或函数(但可能有不同的参数),则对于使用者和提供者,操作结果到请求操作的分配不明确。这是由于缺少工序标识造成的。对于此类操作序列的 OData 使用,这可能会导致运行时错误。对此用例使用可重复操作以避免这些错误。

工厂操作

通过工厂操作,您可以通过执行操作创建实体实例。工厂操作可以是绑定实例的,也可以是静态的。如果要复制实例的特定值,则实例工厂操作非常有用。静态工厂操作可用于创建具有预填充缺省值的实例。

与非工厂操作相反,工厂操作的处理器方法为结果实例提供 %cid 处理。结果通过响应参数 mapped 确定。没有 result 参数。与非工厂操作相反,使用者在执行工厂操作时提供的 %cid 将映射到最终键值。这有助于使用者识别新创建的实例。

您还可以定义缺省工厂操作,在由使用框架评估时替换特定场景中的标准操作,请参阅缺省工厂操作(ABAP 关键字文档)。

保存操作

保存操作是只能在 FINALIZE 或 ADJUST_NUMBERS 期间专门在 RAP 保存序列期间触发的操作。在交互阶段调用定义为 save(finalize) 的保存操作(例如从 determination on modify 调用)会导致短转储。

有关 RAP 保存序列运行时的概览,请参阅保存序列运行时。

使用附加项 save (finalize| adjustnumbers),您可以定义调用保存时操作的处理器方法。

操作添加

外部操作名称

通过使用语法 external 'ExternalActionName',可以重命名外部使用的操作。这意味着,新名称在 OData 元数据中公开。此外部名称可以比实际操作名称长得多,但 ABAP 并不知道。

如果要为具有外部名称的操作定义操作按钮,则必须在 @UI 注释中使用外部名称。有关详细信息,请参阅操作的 UI 使用。

实例功能控制

操作的实例功能控制根据业务对象中的前提条件启用或禁用操作。例如,您可能希望仅在尚未拒绝状态时提供操作 accept_travel。

操作的动态实例功能控制使用语法 features: instance 定义。

有关详细信息,请参阅功能控制。

全局功能控制

操作的全局功能控制根据业务对象外部前提条件启用或禁用操作。例如,您可能只想在一年的特定时间内提供操作。

操作的动态全局功能控制使用语法 features: global 定义。

有关详细信息,请参阅全局功能控制。

权限控制

可以检查操作以防止未经授权的执行。如果没有为操作指定权限控制,则将权限主数据(global 或 instance 或两者)的权限模式用于操作。

您可以通过将操作定义为全局权限或实例权限或两者来替换每个操作的权限主数据中指定的权限控制:( authorization: global| authorization: instance| authorization: global, authoarization: instance )。

要从权限检查中排除操作,可以使用语法 authorization: none。

您还可以将操作权限委派给 update 的权限。

有关详细信息,请参阅权限定义。

非锁定操作

缺省情况下,实例操作会锁定执行它们的实例。为防止在执行操作时触发锁定机制,可以使用语法 lock: none 将实例操作定义为非锁定。

复制操作是此操作的用例。您可能想要复制现有实例的数据而不锁定模板实例。由于静态操作与特定实例无关,因此根据定义它们处于非锁定状态,并且此语法元素不适用。

备注

锁定机制仅受制于操作本身。操作实施中可能的修改调用不受操作定义中非锁定说明的影响。因此,如果实例被操作修改,即使该操作被定义为非锁定,也会将其锁定。

投影行为定义中的操作和函数

您可以在投影级别添加新操作和函数,例如,如果操作仅与一个特定用例相关。对于定义,适用与在基本 RAP 业务对象上定义的操作和函数相同的规则。但是,如果需要权限概念,则必须为每个业务对象节点定义权限概念,且映射 BDEF 必须定义为 strict。有关详细信息,请参阅权限定义。添加到投影 BDEF 的操作和函数自动通过 OData 服务公开,不需要单独公开。

如果要为 OData 服务公开基本行为定义中定义的操作和函数,则必须将其包含在映射行为定义中。使用以下语法:

projection; ...
define behavior for CDSEntity [alias AliasedEntityName]
{...
  use action ActionName [result entity ProjResultEntity] [as ActionAlias] [external ExtActName];
  use function FunctionName [result entity ProjResultEntity] [as FunctionAlias] [external ExtFuncName];
}

有关投影 BDEF 中的操作和函数的详细信息,请参阅 CDS BDL - 实体行为定义(ABAP 关键字文档)。