使用单例实体

学习目标

解释如何在你的应用中创建和使用单例实体。

单例实体

单例是 OData V4 中引入的一种特殊的单元素实体。可以从服务根通过其名称引用它，而无需知道其键，也不需要实体集。

在 CAP 项目中，你可以使用 @odata.singleton 或 @odata.singleton.nullable 注释实体，以将其用作服务中的单例。

service myService {
@odata.singleton entity MySingleton {
key id : String; // can be omitted
prop1 : String;
prop2 : Boolean;
}
}

在你的 CAP CDS 注释中，你可以使用 $edmjson 内联机制引用单例实体中的属性。

让我们考虑自助服务应用中单例的一个典型用例。在这里，你可能想要加载描述用户授权和默认设置的用户上下文。在这种情况下，后端可以简单地使用用户的登录 ID，通过相应的单例发送相关数据，从而公开用户上下文。

请查看 OData V4 的 SAP Fiori elements 应用中单例实体用例的另一个示例“Using Singletons to influence the visibility of the Create, Delete and Edit Buttons”。有关更多信息，请参阅 Actions。

注意

$edmJson 仅在 CDS 编译器 2.3.0 或更高版本中受支持。

有关在 CAP CDS 注释中使用 $edmjson 内联机制的更多信息，请参阅 Serving OData APIs. 中的 Dynamic Expressions 一节

将单例实体用于子弹微图的常量值

使用场景

在本练习中，你将看到在 OData V4 的 SAP Fiori elements 应用中使用单例实体的一个用例。与上一个练习中为子弹微图分配常量值不同，你将引用单例实体中的值。因此，你将修改上一个练习，在其中的子对象页标题中添加了子弹微图。

接下来，你将把静态 boolean 值放入单例实体对应的 CSV 文件中。通过使用单例，你可以减少元数据量，并将所有常量值放在一个单例文件中。

任务流程

在本课中，你将在 CAP 数据模型中定义一个新实体 SupplementScope。注释 @odata.singleton 将使其成为单例实体。

接下来，你将创建 SupplementScope 实体对应的 CSV 文件，并为该实体的属性添加值。然后，你将使用内联 $edmjson 机制在注释中引用单例属性。

前提条件

你已完成单元 Shaping the Header Area of the Object Page（课程：Enriching the Object Page Header with Micro Charts）中的练习 Add the Bullet Micro Chart and the Progress Indicator to the Header Area。或者，你可以签出其解决方案分支：solution/add-bullet-micro-chart-and-progress-indicator-to-op。

观看模拟并执行步骤

本练习包含一个模拟，它会引导你完成下面描述的所有步骤。你可以跟随该模拟，并使用你自己的试用账户执行这些步骤。

Exercise：Start Exercise（SAP 官方交互式练习）

步骤

在 SAP Business Application Studio 中打开你的 CAP 项目。
定义新实体 SupplementScope 并使用 @odata.singleton 对其进行注释。
要打开 Search files by names，请在键盘上按 Ctrl+P。
选择 schema.cds fiori-elements-v4-cap-advanced/db。schema.cds 文件会打开。
将以下代码片段添加到 schema.cds 文件：

@odata.singleton
entity SupplementScope {
MinimumValue : Integer @Common.Label: 'Minimum Value';
MaximumValue : Integer @Common.Label: 'Maximum Value';
TargetValue : Integer @Common.Label: 'Target Value';
DeviationRangeLowValue : Integer @Common.Label: 'Deviation Range Threshold';
ToleranceRangeLowValue : Integer @Common.Label: 'Tolerance Range Threshold';
}

为单例实体创建对应的 .csv 文件并为其填充数据。
在 Explorer 视图中，选择 *Projects\db\data*。
展开 data。
右键单击 data。
选择 New File...。
输入新实体的名称 sap.fe.cap.travel-SupplementScope.csv。
将以下属性和相应的值添加到该文件：

DeviationRangeLowValue;ToleranceRangeLowValue;MinimumValue;MaximumValue;TargetValue
20;75;0;120;100

将单例实体 SupplementScope 添加到服务定义中。
要打开 Search files by names，请在键盘上按 Ctrl+P。
选择 travel-service.cds。travel-service.cds 文件会打开。
将以下代码片段添加到 travel-service.cds 文件。

entity SupplementScope as projection on my.SupplementScope;

将 @UI.DataPoint 注释中的常量值替换为指向单例属性的相应路径。
在 Explorer 视图中，选择 *Projects\app\travel_processor\webapp*。
在 Explorer 视图中，选择 *Projects\app\travel_processor\webapp*。
右键单击 webapp。
选择 Show Page Map。Travel 应用程序的 Page Map 会出现。
选择子对象页的 Edit 图标。BookingObjectPage 的 Page Map 会出现。
展开 Header Sections。
选择 Total Supplements。
在右侧窗格中，选择 Edit in source file。layout.cds 文件会出现。
要用指向单例实体的相应路径替换现有的常量值，请在 @UI.DataPoint 注释中添加以下代码片段：

annotate TravelService.Booking with @(
UI.DataPoint #TotalSupplPrice1: {
Value : TotalSupplPrice,
MinimumValue : {$edmJson: {$Path: '/SupplementScope/MinimumValue'}},
MaximumValue : {$edmJson: {$Path: '/SupplementScope/MaximumValue'}},
TargetValue : {$edmJson: {$Path: '/SupplementScope/TargetValue'}},
Visualization : #BulletChart,
// Criticality : TotalSupplPrice, // it has precedence over criticalityCalculation => in order to have the   criticality       color do not use it
CriticalityCalculation: {
$Type : 'UI.CriticalityCalculationType',
ImprovementDirection : #Maximize,
DeviationRangeLowValue: {$edmJson: {$Path: '/SupplementScope/DeviationRangeLowValue'}},
ToleranceRangeLowValue: {$edmJson: {$Path: '/SupplementScope/ToleranceRangeLowValue'}}
}
},

在 $metadata 文件中检查新创建的单例实体。
打开 Welcome to @sap/cds Server 页面。
选择 /processor/$metadata。

结果

在 $metadata 文档中，你可以看到新的单例实体 SupplementScope 已添加到 EntityContainer。你还可以看到 XML 格式的 @UI.DataPoint 注释。 7. 查看标题区域上的子弹微图。

在浏览器中打开 Manage Travels 应用。
在 Bookings 下，选择第一行。

结果

你可以在对象页标题上看到子弹微图。

结果

在本课中，你已学会在 OData V4 的 SAP Fiori elements 应用中使用单例实体。

注意

你可以在 GitHub 上找到本练习的解决方案。

解决方案分支是 solution/use-singleton-for-bullet-micro-chart-on-op 。

你可以在 GitHub 上查看与上一个分支相比的代码更改。

后续步骤

有关更多信息，请参阅

Singletons
Actions