老猿学5G：3GPP 5G规范中的URI资源概念

☞ ░ 前往老猿Python博文目录 ░

说明：

本文参考3GPP29.501《Principles and Guidelines for Services Definition》结合笔者的理解写成，主要用于解释5GC系统中普遍使用的URI资源概念，由于笔者对REST本身理解不透彻，难免有表述不对的地方，欢迎大家指正。

一、概述

5GC SBI API服务化接口是基于http2.0的rest风格的接口，REST是一个http应用开发标准和规范，遵循REST风格可以使开发的接口通用，便于调用者理解接口的作用。不了解的可以参考《REST，以及RESTful的讲解》。

REST中资源URI是非常重要的概念，所有服务访问可以概括为CRUD操作，即增加(Create)、读取(Retrieve)、更新(Update)和删除(Delete)，对应http的POST、GET、PUT、DELETE等方法，本文所说的API都是指http 2.0的服务化接口。

3GPP规范中5G系统中使用资源的要求在29.501文档中描述，资源可以是单个资源或者包含了子资源的资源结构体。

二、资源建模及四类原型

在设计API时，首先要考虑定义API所消耗的资源集。资源表示通过标准HTTP方法修改的对象，这些对象可以用下面详述的4个原型之一建模。资源原型有助于API设计者构造资源。在这个过程中，当资源定义与原型之一完全匹配时，设计者应该引用适当的原型。引用原型可以立即定义资源支持哪些操作和HTTP方法。提供原型以后不排除出现不同的资源类型。

2.1、Document文档原型

文档原型是其他原型的基础概念原型。任何未与其他资源原型匹配识别的资源都是文档。文档可以有表示其特定从属概念的子资源。当原型为文档原型时，不会限制任何HTTP方法的操作。通过向资源的URI发送HTTP请求，仅可以直接在文档资源上执行CRUD操作。自定义方法不能直接在资源上执行，而是通过发送一个HTTP请求到一个URI，该URI关联一个约定资源的URI。

2.2、Collection集合原型

集合原型可用于对作为资源目录的资源进行建模。集合是管理的NF服务提供者（NF Service Provider-managed），因此NF服务提供者决定在集合中创建的每个资源的URI。

创建和读取操作直接在集合上执行。

注意：

即使集合资源通常包含子资源，也允许特定集合资源在特定时间点不包含任何子资源（“空集合”）。

特别说明：

集合的子资源通过集合认可的发送带集合URI的http post创建
通过发送带有集合URI的GET来读取集合
不允许使用集合URI的PUT和PATCH方法
仅在集合资源是基于NF服务使用者的请求动态创建的情况下才允许使用带集合URI的DELETE 方法
对集合子资源的授权操作依赖于该资源的原型。

2.3、Store存储原型

存储原型可以用于对作为资源目录但存储由NF服务使用者管理的资源进行建模。NF服务消费者完全决定应该向存储中添加/删除什么资源。NF服务使用者决定所添加资源的URI是什么。

注意：即使存储资源通常包含子资源，也允许特定存储资源在特定时间点不包含任何子资源（“空存储”）。

对存储资源来说：

读取操作直接在存储上执行，而创建操作则在存储子资源上执行。

更具体地说：

存储子资源是通过发送带有要创建的子资源的URI的PUT来创建的
通过发送带有存储URI的GET来读取存储；
不允许使用存储URI的POST、PUT和PATCH方法；
只有在根据NF服务使用者的请求动态创建存储资源时，才允许使用存储URI的DELETE方法。
除了Create（PUT），对存储子资源的授权操作依赖于该资源的原型。

2.4、Custom operation自定义操作原型

自定义操作原型可用于建模一个不安全和非幂等的操作，但该操作不能是集合上的一个Create操作。自定义操作不直接对由自定义操作URI标识的资源进行操作。相反，当自定义操作与资源关联时，该操作将在此关联的资源上执行。例如，自定义操作可以以特殊方式修改相关联的资源，该关联资源通过自定义操作URI模板中剥离后缀字符串“/{custOpName}”来标识。

当自定义操作不与任何资源关联，而是与服务关联时，它充当带有输入参数的可执行函数，并在响应正文中返回已执行函数的结果，而不修改任何资源。

POST是唯一允许使用自定义操作URI的方法。

三、5GC SBI API的资源

资源可以是单个资源，也可以是可以包含子资源的结构化资源。建议按照上面资源建模及四类原型中提供的一种原型设计每个资源。

3.1、资源URI结构

URI唯一地标识资源，在5GC SBI API中，当资源URI是绝对URI时，其结构应按如下方式指定：

{apiRoot}/{apiName}/{apiVersion}/{apiSpecificResourceUriPart}

apiRoot应为以下部分顺序组成：

服务模式（“http” 或"https"）
固定字符串"://"
IETF RFC 3986[9]中定义的权限（authority ，指主机和可选端口）
以“/”字符开头的可选部署特定字符串（API前缀）

apiName为API服务的名字
apiVersion表示API版本的第一个字段（主版本）

虽然“apiRoot”、“apiName”和“apiVersion”一起定义API的基本URI，但每个“apiSpecificResourceUriPart”都定义API相对于基本URI的资源URI，也即表明apiSpecificResourceUriPart是资源的URI。

3.2、自定义操作的URI结构

与资源关联的自定义操作的URI应具有以下结构：

{apiRoot}/{apiName}/{apiVersion}/{apiSpecificResourceUriPart}/{custOpName}

自定义操作也可以与服务关联，而不是与资源关联。与资源无关的自定义操作的URI应具有以下结构：

{apiRoot}/{apiName}/{apiVersion}/{custOpName}

3.3、回调URI结构

回调URI应为IETF RFC 3986[9]第4.3条定义的绝对URI形式，包括权限，不包括任何查询组件、任何片段组件和任何userinfo子组件。

四、资源的表示

资源表示是特定内容格式中资源状态的序列化。它包含在HTTP/2请求或响应的数据帧中。表示头字段提供有关表示的元数据。当一条消息包含一个数据帧时，该数据帧中包含表示的数据。HTTP/2将表示头的定义重用了 IETF RFC 7231 [6]中的http1.1。HTTP/2 header中的Content-type字段作为表示头字段执行，描述数据帧中本来应该包含的表示数据，例如，如果Content-type为application/json，则数据框中的资源表示以json格式序列化。

跟老猿学Python、学5G!

☞ ░ 前往老猿Python博文目录 ░