51学通信

深度解析 3GPP TS 29.501：3 Definitions, abbreviations and symbols (定义、缩略语与符号)

22分钟阅读

深度解析 3GPP TS 29.501：3 Definitions, abbreviations and symbols (定义、缩略语与符号)

本文技术原理深度参考了3GPP TS 29.501 V18.7.0 (2024-12) Release 18规范中，关于“Chapter 3 Definitions, abbreviations and symbols”的核心章节，旨在为读者构建一套理解5G服务化接口（SBI）所必需的“通用语言”词典。

在完成了对TS 29.501的《全景概览》和对第1、2章的《范围与基石》的解读后，我们的老朋友，API设计师小王，已经为他的NIAF（网络智能分析功能）服务铺好了宏观蓝图。他清楚了自己工作的“立法依据”和“权力边界”。

现在，小王要进入一个看似基础却至关重要的阶段：学习并精通SBI的“官方语言”。第3章就是这门语言的“新华字典”，它精确定义了每一个核心术语、缩略语和符号。如果说SBA是一场全球性的技术对话，那么第3章就确保了所有参与者（无论是网络功能NF，还是开发者）都能在同一个频道上，使用同一套无歧可解的词汇进行交流。

对于小王而言，这份“字典”将直接影响他编写nniaf-analytics.yaml OpenAPI文件的每一个细节。任何一个术语的误用，都可能导致API契约的歧义，从而引发集成时的灾难。让我们跟随小王的脚步，逐一剖析这些奠定5G API大厦的基石。

1. 概念的基石：核心定义 (Clause 3.1 Definitions)

本章节定义了构建URI和理解API结构时最核心的一组术语。每一个定义都像法律条文中的名词解释，精确且不容混淆。小王拿出笔记本，将它们与自己Nniaf_Analytics服务的设计一一对应。

1.1 绝对URI (Absolute URI)

这是所有网络通信的起点，一个资源的完整、无歧义的全球唯一定位符。

规范原文引用 (Clause 3.1): Absolute URI: Absolute URI follows generic URI syntax and consists of a hierarchical sequence of the following components: the “scheme”, “authority”, “path” and “query”, i.e. excluding the “fragment” component. See clause 4.3 in IETF RFC 3986.

深度解析： 一个完整的URI通常包含五个部分：scheme:[//authority]path[?query][#fragment]。

  • scheme: 协议名，如 https。
  • authority: 授权方，通常是域名或IP地址，可包含端口号，如 example.com:8080。
  • path: 路径，定位服务器上的资源，如 /nniaf-analytics/v1/jobs。
  • query: 查询参数，提供额外的参数，如 ?status=active。
  • fragment: 片段，指向资源内部的一个锚点，如 #section-1。

规范在这里做了一个关键的排除：SBI中的绝对URI不包含fragment部分。这是因为fragment由客户端（浏览器）处理，服务器端通常不接收也无法处理。SBI是服务器到服务器的通信，因此只关注服务器能处理的部分。

小王的设计思考： 当AMF要创建一个分析任务时，它向NIAF发出的HTTP请求目标就是一个绝对URI。例如： https://niaf.operator.com/nniaf-analytics/v1/analytics-jobs?sourceNf=AMF 这个URI完整地告诉了网络，它要去niaf.operator.com这个主机，通过https协议，访问/nniaf-analytics/v1/analytics-jobs这个资源路径，并附带一个查询参数sourceNf=AMF。

1.2 API根 (apiRoot)

这是运营商网络中所有SBI API的“总门牌号”，是部署时最关键的配置项。

规范原文引用 (Clause 3.1): apiRoot: apiRoot follows an absolute URI syntax, but excludes the following absolute URI identifiers: the “query” and “fragment” components. The API root contains the “scheme” and the “authority” components and may also contain an API prefix subcomponent.

深度解析： apiRoot 是一个更基础的概念，它只包含scheme、authority和可选的API Prefix。它不包含具体的API名和版本，更不包含具体的资源路径和查询参数。

  • 结构: {scheme}://{authority}[/{apiPrefix}]
  • 作用: 它为运营商网络中的所有API提供了一个统一的、可配置的根。不同的运营商、甚至同一运营商的不同数据中心，都可以配置不同的apiRoot。

小王的设计思考： 小王在设计Nniaf_Analytics服务时，他不能硬编码https://niaf.operator.com。在他的OpenAPI文件中，他必须使用一个变量{apiRoot}来表示。

例如，在德国的运营商可能会将apiRoot配置为 https://core.de.operator.com/api/v1。 而在日本的运营商可能会配置为 https://5gc.jp.operator.com。

apiRoot的引入，使得API定义与实际网络部署完全解耦，极大地增强了API的可移植性。

1.3 API URI vs. 资源URI (API URI vs. Resource URI)

这两个概念是初学者最容易混淆的，但区分它们对于理解RESTful至关重要。

规范原文引用 (Clause 3.1): API URI: API URI has the following format: “{apiRoot}//“. Resource URI: Resource URI identifies an abstract or a physical resource. … Resource URI structure is defined in clause 4.4.1.

深度解析：

  • API URI: 代表一个**服务(Service)**的入口点。它告诉我们“这是哪个服务的哪个版本”。它不指向任何具体的数据资源，而是这个服务的“名片”。
  • Resource URI: 代表一个具体的资源(Resource)。它在API URI的基础上，进一步追加了具体的资源路径，告诉我们“我要操作这个服务里的这个东西”。

小王的设计思考： 我们用NIAF服务来清晰地展示这个区别：

概念结构示例含义
apiRoot{scheme}://{authority}https://niaf.operator.com所有API的部署根
API URI{apiRoot}/{apiName}/{apiVersion}https://niaf.operator.com/nniaf-analytics/v1**“NIAF分析服务V1版本”**这个服务的入口
Resource URI{API URI}/{resourcePath}https://niaf.operator.com/nniaf-analytics/v1/analytics-jobs/job123**“NIAF分析服务V1版本中的ID为job123的那个分析任务”**这个具体的资源

在OpenAPI文件中，servers字段定义的URL模板通常就是API URI。而paths字段下的每一个路径，都是相对于API URI的资源路径。

1.4 回调URI (Callback URI)

这是实现订阅/通知模式的关键，是服务生产者“反向”联系服务消费者的“电话号码”。

规范原文引用 (Clause 3.1): Callback URI: Callback URI follows an absolute URI syntax, but excludes the following absolute URI identifiers: “userinfo” subcomponent of the “authority” component and also the “query” component…

深度解析： 当一个消费者（如AMF）向生产者（如NIAF）订阅事件时，它必须提供一个Callback URI。当事件发生时，生产者会向这个URI发送一个HTTP POST请求。

规范对Callback URI做了两个关键的排除：

  1. 排除 userinfo: 即user:password@host这种形式。这是出于安全考虑，避免在网络中明文传输凭证。SBI的认证授权依赖于更安全的OAuth2.0机制。
  2. 排除 query: 即?param=value。这是为了简化生产者的回调逻辑。所有通知所需的信息都应该封装在POST请求的Body中，而不是通过查询参数传递。

小王的设计思考： 当AMF订阅job123的状态更新时，它提供的Callback URI必须是一个干净的、不带参数和用户信息的地址，例如：

  • 合法的Callback URI: https://amf.operator.com/niaf-notifications
  • 非法的Callback URI: https://user:[email protected]/niaf-notifications
  • 非法的Callback URI: https://amf.operator.com/niaf-notifications?token=xyz

NIAF在收到订阅请求时，需要验证Callback URI的合法性。当job123状态变为COMPLETED时，NIAF会向https://amf.operator.com/niaf-notifications这个地址POST一个通知消息体。

2. 沟通的简语：缩略语 (Clause 3.2 Abbreviations)

本章节提供了一份官方的缩略语列表，确保了在所有SBI相关的文档和讨论中，大家使用的都是标准化的简称。

规范原文引用 (Clause 3.2): For the purposes of the present document, the abbreviations given in 3GPP TR 21.905 and the following apply. An abbreviation defined in the present document takes precedence over the definition of the same abbreviation, if any, in 3GPP TR 21.905.

深度解析： 这张列表不仅是备忘录，更是对核心技术的强调。我们将其整理并附上通俗的解释：

缩略语全称中文解释及重要性
5GC5G Core Network5G核心网。明确了规范的作用域。
CNFConjunctive Normal Form合取范式。用于构建复杂查询，多个条件之间是“与”(AND)的关系。
CRUDCreate, Read, Update, Delete增删改查。RESTful API最基本的操作集合，分别对应HTTP的POST/PUT, GET, PUT/PATCH, DELETE。
DNFDisjunctive Normal Form析取范式。用于构建复杂查询，多个条件之间是“或”(OR)的关系。
HALHypertext Application Language超文本应用语言。一种简单的、用于在JSON中嵌入超媒体链接（如_links）的格式约定，是HATEOAS的一种实现方式。
HATEOASHypermedia as the Engine of Application State超媒体作为应用状态的引擎。REST架构成熟度的最高级（Level 3），响应中包含链接来驱动下一步操作。在5GC中是可选的。
RESTREpresentational State Transfer表述性状态转移。5G SBA所采纳的核心架构风格。
RPCRemote-Procedure-Call远程过程调用。一种传统的API交互模式，与REST的面向资源相对。在SBI中，自定义操作(Custom Operation)有时会体现出RPC的风格。
SBIService Based Interface服务化接口。5G核心网NF之间交互的标准接口。这是整本规范的核心主题。
YAMLYAML Ain’t Markup Language一种人性化的数据序列化语言，被选为编写OpenAPI文件的标准格式。

小王在团队内部的技术分享会上，特意强调了这些缩略语的精确含义，确保团队成员在讨论和设计时，口径完全一致。

3. 语法的规则：特殊字符与分隔符 (Clause 3.3 Special characters, operators and delimiters)

这一章节是为所有需要手动构造URI或编写解析器的开发者准备的“语法宝典”。它详细规定了各种特殊字符在SBI上下文中的确切含义。

3.1 URI中的保留字符 (Clause 3.3.3)

这些字符在URI中具有特殊的“语法含义”，不能随意作为普通字符使用。

规范原文引用 (Clause 3.3.3): Reserved character. The forward slash character is a delimiter, which precedes an URI path component and also separates a sequence of path segments.

深度解析与小王的应用： 小王将这些关键字符整理成了一张速查表：

字符名称在SBI URI中的作用示例
/正斜杠路径段(Path Segment)的分隔符。/nniaf-analytics/v1/analytics-jobs
?问号分隔路径和查询参数。.../analytics-jobs?status=COMPLETED
=等号在查询参数中，分隔键(key)和值(value)。status=COMPLETED
&和号在查询字符串中，分隔多个查询参数。?status=COMPLETED&maxRecords=10
{}大括号（SBI特定用法） 见下一节，用于包裹路径或查询中的变量名。.../analytics-jobs/{jobId}
:冒号分隔scheme和authority，或host和port。https://..., ...:8080
[]方括号仅用于包裹IPv6地址。https://[2001:db8::1]/...

小王特别提醒开发团队，如果一个路径变量（如jobId）本身可能包含这些保留字符（例如，jobId为job/extra），那么在将其放入URI之前，必须进行“百分号编码”（Percent-encoding），job/extra需要被编码为job%2Fextra。

3.2 SBI特定的分隔符用法 (Clause 3.3.4)

这里规范强调了在SBI中大括号{}的特殊且唯一的含义。

规范原文引用 (Clause 3.3.4): {} Delimiters. The braces (curly brackets) characters enclose a name of a variable in an URI path segment (see clause 5.1.3.2). Example: …/subscriber-data/{supi}. {} Delimiters. The braces (curly brackets) characters enclose a parameter value in a query (see clause 5.1.3.3). Example: ?nf-id={chooseAValue}

深度解析： 这是OpenAPI规范在3GPP中的具体应用。大括号{}的作用是标记变量占位符。

  1. 在路径中：{variableName}标记了一个路径参数。当客户端发起请求时，必须用实际值替换这部分。例如，AMF请求job123的信息，就会访问/nniaf-analytics/v1/analytics-jobs/job123，这里的job123替换了{jobId}。
  2. 在查询中：?param={variableName}。这种情况在规范文档中用于表示这个查询参数的值是一个需要被替换的变量，但在实际的HTTP请求中，查询参数的值就是其实际值，不会真的包含大括号。例如，文档中写?nf-id={nfInstanceId}，实际请求是?nf-id=amf-instance-01。

规范原文引用 (Clause 3.3.4 NOTE): In SBI specifications, ”<>” is a generic placeholder, while ”{}” enclose specifically a variable.

这个Note非常关键，它区分了两种占位符：

  • <> (尖括号): 在3GPP的文字描述中，用作通用占位符，表示一个概念。例如，“一个NF的地址格式为<NF FQDN>”。这是给人读的。
  • {} (大括号): 在OpenAPI定义和URI模板中，用作变量占位符。例如，path: /nfs/{nfId}。这是给机器解析和代码生成的。

小王的设计思考： 在编写nniaf-analytics.yaml时，小王必须严格使用{}来定义路径参数：

paths:
  /analytics-jobs/{jobId}:
    get:
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
      ...

而在编写设计文档（比如Word文档）向同事解释时，他可能会写：“每个任务的URI结构是/analytics-jobs/<job-identifier>”，这里的<job-identifier>就是一种给人看的通用占位符。

总结：精确是互操作性的前提

第3章虽然没有复杂的流程图和算法，但其重要性不亚于任何一个技术章节。它通过精确的定义、统一的缩略语和明确的符号规则，为整个5G SBI生态系统构建了沟通的基石。

对于小王和所有5G开发者来说，这份“字典”的意义在于：

  • 消除歧义：确保所有人对apiRoot、Resource URI等核心概念有完全一致的理解。
  • 提升效率：标准化的缩略语和符号使得技术文档更简洁，沟通更高效。
  • 保障自动化：对URI结构和变量标记的严格规定，是OpenAPI工具链能够正确解析API、自动生成代码和测试用例的根本保障。

可以说，没有第3章奠定的语言基础，SBA所追求的自动化、松耦合和互操作性都将是空中楼阁。

FAQ

Q1：apiRoot和Base URI有什么区别？ A1：apiRoot是运营商部署级的概念，定义了所有API的根入口点，它本身不包含任何API特定的信息。Base URI是IETF RFC 3986中定义的术语，用于解析相对URI引用。在SBI的实际应用中，API URI（即{apiRoot}/<apiName>/<apiVersion>）常常扮演Base URI的角色。例如，当一个POST请求的响应头Location中返回一个相对路径/analytics-jobs/job456时，客户端就需要用发起请求的API URI作为Base URI来拼接出完整的Resource URI。

Q2：为什么HATEOAS（超媒体作为应用状态的引擎）是可选的？它不是REST的最高级吗？ A2：虽然HATEOAS是REST理论上的最高境界，但在大规模的、性能要求高的M2M（机器对机器）通信系统中，它的优势并不总是能抵消其带来的复杂性。实现HATEOAS要求服务器在响应中动态生成各种链接，客户端也需要有能力解析这些链接来驱动状态机，这增加了双方的实现复杂度和响应包的大小。在5G核心网这种内部系统中，通信双方（NF）通常是预先约定好的，对API的结构非常了解，动态发现的需求不那么迫切。因此，3GPP将其设为可选，允许在需要高度动态和灵活性的场景下使用，但在大多数场景下，Level 2的REST API已经足够高效和实用。

Q3：我看到规范中提到了CNF和DNF，这在实际API调用中是如何体现的？ A3：CNF（合取范式）和DNF（析取范式）是用于构造复杂查询的逻辑表达式。在TS 29.501的后续章节（4.6.1.1.5.2）中定义了一个complex-query查询参数。当简单的key=value&key2=value2（默认为AND关系）无法满足查询需求时，客户端可以将一个JSON对象作为complex-query参数的值。这个JSON对象内部就可以用cnfUnits（AND关系）和dnfUnits（OR关系）来组织复杂的查询条件。例如，查询“状态为COMPLETED且类型为MOBILITY_ANALYSIS”或“状态为FAILED”的任务。

Q4：为什么Callback URI要禁止query参数？如果我想在回调时传递一些上下文信息怎么办？ A4：禁止query参数主要是为了保持回调机制的简洁、安全和标准化。通知的所有信息都应封装在一个结构化的、版本可控的JSON Body中。如果允许query参数，可能会导致：1) 参数格式不统一，难以管理；2) 重要的上下文信息暴露在URI中，存在安全风险；3) 生产者需要解析和处理各种自定义查询参数，增加了其实现的复杂性。消费者如果需要在收到通知时关联上下文，可以在订阅时生成一个唯一的subscriptionId，生产者在通知时会带上这个ID，消费者凭借此ID即可找到自己的上下文。

Q5：作为一名开发者，我需要完整实现一个URI解析器来处理这些特殊字符吗？ A5：通常不需要。几乎所有的现代编程语言都提供了成熟的、经过充分测试的URI/URL处理库。这些库已经完整实现了RFC 3986的规范，能够正确地解析、构造URI，并处理百分号编码。作为开发者，你的责任是正确地使用这些库，例如，在将用户输入或动态数据拼接到URI路径段之前，务必调用库提供的编码函数，而不是手动拼接字符串，以避免安全漏洞。

关系图谱