OData 4.0 三种标准词汇的使用场合介绍

发布时间 2023-12-02 18:16:14作者: JerryWang_汪子熙

OData 4.0 定义了三个标准词汇(vocabularies):Core, Capabilities 和 Measures.

我们看个实际的例子:

<Property Name=“OrderedQuantity” Type=“Edm.Int16”>
  <Annotation Term=“Measures.Unit” Path=“OrderedUnit” />
</Property>

<Property Name=“OrderedUnit” Type=“Edm.String” />

<Property Name=“Price” Type=“Edm.Decimal” Scale=“variable”>
  <Annotation Term=“Measures.ISOCurrency” Path=“Currency” />
  <Annotation Term=“Measures.Scale” Path=“DisplayScale” />
</Property>

<Property Name=“DisplayScale” Type=“Edm.Byte” />

    <Property Name=“Currency” Type=“Edm.String” MaxLength=“3”>
      <Annotation Term=“SAP.Text” Path=“CurrencyText” />
    </Property>

<Property Name=“CurrencyText” Type=“Edm.String”>
  <Annotation Term=“Core.IsLanguageDependent” />
</Property>

上面的示例使用了 Measure 词汇表中的三个术语、Core 词汇表中的一个术语以及三个标准词汇表中不存在的概念的 SAP 特定术语。

第一个重要事实是:标准化术语和自定义术语的 Annotations 看起来相同。

第二个重要事实是:标准术语和自定义术语的定义也使用相同的语言结构。

OData 4.0 中的 Vocabulary 是一种极其重要的语义扩展机制,它可以为 OData 协议赋予更丰富的元数据信息。在 OData 中,我们主要有 Core, Capabilities 和 Measures 这三种 Vocabulary。

Core Vocabulary 旨在提供一种方式来描述通用的概念或属性。例如,您可能希望标记某个属性为只读,或者指出某个实体是一个抽象实体。这是一种通用的 Vocabulary,可用于各种场景,包括但不限于描述实体的生命周期、关联、权限等。例如,我们可以使用 Core Vocabulary 来标记一个属性为只读:

<Property Name="ID" Type="Edm.String" Nullable="false">
  <Annotation Term="Core.Computed" Bool="true"/>
</Property>

在这个例子中,我们对 "ID" 属性使用了 Core.Computed 这个注解,表示这个属性是计算出来的,也就是说,它是只读的。

Capabilities Vocabulary 主要用于描述服务的能力。这种 Vocabulary 主要用于向客户端声明服务端所支持的操作,例如是否支持排序、筛选、分页等。例如,我们可以声明我们的服务不支持过滤操作:

<EntityContainer Name="Container">
  <Annotation Term="Capabilities.FilterRestrictions">
    <Record>
      <PropertyValue Property="Filterable" Bool="false"/>
    </Record>
  </Annotation>
</EntityContainer>

在这个例子中,我们使用了 Capabilities.FilterRestrictions 这个注解,表示我们的服务不支持过滤操作。

Measures Vocabulary 主要用于描述度量单位。它允许我们为数值属性定义度量单位,例如货币、长度、重量等。例如,我们可以为一个属性定义货币单位:

<Property Name="Price" Type="Edm.Decimal" Nullable="false">
  <Annotation Term="Measures.ISOCurrency" String="USD"/>
</Property>

在这个例子中,我们使用了 Measures.ISOCurrency 这个注解,表示 "Price" 这个属性的单位是美元。

总的来说,OData 4.0 的 Vocabulary 提供了一种强大的元数据扩展机制,使得我们可以为 OData 服务添加更丰富的语义信息。Core Vocabulary 提供了描述通用概念的能力,Capabilities Vocabulary 允许我们声明服务的能力,而 Measures Vocabulary 则为我们提供了描述度量单位的能力。这三种 Vocabulary 在不同的场景下都有其独特的用途,使得 OData 服务能够更好的满足各种各样的需求。