51学通信

深度解析 3GPP TS 29.577：6. API定义与数据模型 (最终章)

14分钟阅读

好的，我们已经抵达了3GPP TS 29.577规范深度解读的最后一站。在前文中，我们已经全面掌握了Nipsmgw_SMService和Nrouter_SMService的功能逻辑和API交互流程。现在，我们将进入协议的最底层，对构成这些交互内容的“DNA”——API定义和数据模型——进行精细的解剖。

深度解析 3GPP TS 29.577：6. API定义与数据模型 (最终章)

本文技术原理深度参考了3GPP TS 29.577 V18.4.0 (2024-06) Release 18规范中，第六章“API Definitions”的全部核心内容。本文是TS 29.577解读的最终章，旨在为读者提供一份详尽的Nipsmgw和Nrouter API“施工图”和“材料清单”，我们将剖析两大服务的API资源和所有核心JSON对象的精确结构，揭示每个字段在5G短信路由和转发过程中的具体作用。

引言：从“规程”到“电文”——API的微观构造

我们已经学习了5G短信业务的“操作规程”——知道了UDM如何通过RoutingInfo操作“更新导航地图”，以及SMS-GMSC如何通过MtForwardSm操作“委托货运”。

现在，我们将进入“电报编译室”，学习如何将这些规程，编码成IP-SM-GW和SMS Router能够精确无误解析的“电文”——即具体的HTTP API和JSON数据体。第六章“API Definitions”正是这份规范的“电码本”。

  • 6.1 Nipsmgw_SMService Service API: 定义了IP-SM-GW接口的编码规则。
  • 6.2 Nrouter_SMService Service API: 定义了SMS Router接口的编码规则。

由于这两个API在逻辑和结构上的高度一致性，我们将重点剖析Nipsmgw_SMService，并对Nrouter_SMService的差异点进行说明。对于负责开发UDM、SMS-GMSC或IP-SM-GW/SMS Router的工程师来说，这一章是他们工作的核心参考。

1. 解读第6.1章 Nipsmgw_SMService Service API - IP-SM-GW的接口蓝图

本节定义了Nipsmgw_SMService的完整API实现。

1.1 6.1.3 Resources (资源) - 唯一的“用户信息档案”

Nipsmgw_SMService API的资源模型非常聚焦，所有操作都围绕一个核心资源展开。

Figure 6.1.3.1-1: Resource URI structure of the Nipsmgw_SMService API

URI结构展示了一个核心资源和其下的一个自定义操作：

  • /mt-sm-infos: MT短信信息集合。这是一个逻辑上的集合资源。
  • /{gpsi}: 代表一个单个用户的MT短信信息资源，即“用户信息档案”。
  • /sendsms: 在单个用户资源下执行的自定义操作。

Table 6.1.3.1-1: Resources and methods overview

Resource purpose/nameResource URIHTTP methodDescription (service operation)
MtSmInfo (Document)/mt-sm-infos/{gpsi}PUTCreate Routing Information for MT SMS.
/mt-sm-infos/{gpsi}/sendsmssendsms (POST)…allow NF Service Consumer to send SMS payload…
  • PUT /mt-sm-infos/{gpsi}: 对应RoutingInfo操作，用于创建或更新用户的路由信息档案。
  • POST /mt-sm-infos/{gpsi}/sendsms: 对应MtForwardSm操作，用于在该用户的档案下执行“发送短信”的动作。

1.2 RoutingInfo API (PUT) 的数据模型

  • 请求 (PUT):

    • Request Body (CreateRoutingData):

      Table 6.1.6.2.2-1: Definition of type CreateRoutingData

      • smsfId (M): NfInstanceId。必须提供，指明为该用户服务的SMSF实例的唯一ID。
      • smsf3Gpp / smsfNon3Gpp (O): SmsfRegistration。更详细的SMSF注册信息，可以区分3GPP和非3GPP接入。NOTE 1指出，新版API推荐使用这两个结构体来传递完整的SMSF地址信息，而smsfId则为了向后兼容而保留。
      • ipSmGwGuidanceInd (C): boolean。一个指示符，由UDM设置，告知IP-SM-GW，SMS-GMSC是否期望在响应中收到IP-SM-GW的引导信息（地址）。

  • 响应 (201 Created):

    • Response Body (CreatedRoutingData):

      Table 6.1.6.2.3-1: Definition of type CreatedRoutingData

      • ipsmgwIpv4 / ipsmgwIpv6 / ipsmgwFqdn: IP-SM-GW的IPv4/IPv6地址或FQDN。
      • ipSmGwNfInstanceId: IP-SM-GW的NF实例ID。
      • ipSmGwGuidance: 更详细的引导信息。 核心作用: IP-SM-GW在响应中“自报家门”，以便UDM可以将这些地址信息提供给SMS-GMSC，让SMS-GMSC知道下次应该把短信发往哪里。

1.3 MtForwardSm API (POST) 的数据模型

  • 请求 (POST):

    • Request Body (SmsData):

      Table 6.1.6.2.4-1: Definition of type SmsData

      • smsPayload (M): RefToBinaryData。这是一个引用，指向multipart消息中包含短信PDU的二进制部分。
      • 实际实现: 请求的Content-Type为multipart/related。JSON部分是SmsData对象，其中smsPayload字段的值是二进制部分的Content-ID。二进制部分的Content-Type是application/vnd.3gpp.sms。附录B.2给出了一个非常清晰的示例。

  • 响应 (200 OK):

    • Response Body (SmsDeliveryData):

      Table 6.1.6.2.5-1: Definition of type SmsDeliveryData

      • smsPayload (M): RefToBinaryData。同样是一个引用，指向响应的multipart消息中包含投递报告 (Delivery Report) 的二进制部分。 核心逻辑: 请求和响应都是“信封+信件”的模式。JSON对象是“信封”，提供了元数据；二进制部分是“信件”，包含了真正的SMS PDU或报告PDU。

2. 解读第6.2章 Nrouter_SMService Service API - SMS Router的接口蓝图

如前所述，Nrouter_SMService的API在结构和逻辑上与Nipsmgw_SMService高度一致。

  • 资源模型: 完全相同，也是围绕PUT /mt-sm-infos/{gpsi}和POST /mt-sm-infos/{gpsi}/sendsms构建。
  • 数据模型:
    • RoutingInfo (PUT):
      • 请求体同样是CreateRoutingData。
      • 响应体是CreatedRoutingData，但内容有所不同。

        Table 6.2.6.2.2-1: Definition of type CreatedRoutingData (for Nrouter)

        • routerIpv4 / routerIpv6 / routerFqdn: 返回的是SMS Router的地址。
        • routerNfInstanceId: SMS Router的NF实例ID。
    • MtForwardSm (POST):
      • 请求体是SmsData，响应体是SmsDeliveryData。这部分与IP-SM-GW完全相同，因为短信载荷的传输与具体是哪个NF处理无关。

核心差异: 唯一的实质性差异在于RoutingInfo成功创建资源后的响应体。IP-SM-GW返回自己的地址信息，而SMS Router返回它自己的地址信息。这确保了UDM和SMS-GMSC总能获得正确的下一跳地址。

3. 全景复盘：一次完整的短信投递API之旅

让我们将所有API和数据模型串联起来，以API的视角，完整地走一遍小李接收验证码的生命周期：

  1. 准备阶段 - 路由注册

    • 小李手机在5G网络注册短信服务。
    • UDM → IP-SM-GW: PUT /nipsmgw-smservice/v1/mt-sm-infos/{小李的gpsi}
    • Request Body (CreateRoutingData): {"smsfId": "smsf-instance-uuid-01", ...}
    • IP-SM-GW → UDM: 201 Created
    • Response Body (CreatedRoutingData): {"ipsmgwFqdn": "ipsmgw.operator.net", ...}
    • UDM记录下IP-SM-GW的地址。

  2. 投递阶段 - 短信发送

    • 验证码短信到达SMS-GMSC。SMS-GMSC向UDM查询，得知应发往ipsmgw.operator.net。
    • SMS-GMSC → IP-SM-GW: POST /nipsmgw-smservice/v1/mt-sm-infos/{小李的gpsi}/sendsms
    • Request Body (Multipart):
      • JSON部分 (SmsData): {"smsPayload": {"contentId": "sms_pdu"}}
      • 二进制部分 (Content-ID: sms_pdu): 包含短信内容的原始二进制PDU。
    • IP-SM-GW根据已注册的路由，将短信转发给SMSF-01。
    • IP-SM-GW → SMS-GMSC: 200 OK
    • Response Body (Multipart): 包含JSON部分的SmsDeliveryData和二进制部分的投递报告PDU。

总结与宣告

通过对TS 29.577第六章API定义与数据模型的最终解剖，我们已经将5G短信业务的两大核心接口的实现细节了然于胸。

  1. 一致而灵活的API设计: 规范为IP-SM-GW和SMS Router这两个角色定义了逻辑上完全一致的API，体现了SBA的标准化思想。同时，通过在响应中返回不同的NF地址，又巧妙地支持了两种不同的网络架构。

  2. RESTful与RPC的结合: API的设计兼具两种风格。RoutingInfo操作采用纯粹的RESTful PUT方法管理资源，而MtForwardSm则采用RPC风格的POST自定义操作来执行动作，两者都非常贴合业务的本质。

  3. Multipart消息的关键作用: 在短信业务中，multipart消息是不可或缺的。它为在JSON-RPC风格的SBA接口中，高效、标准地传输二进制短信载荷提供了完美的解决方案。

至此，我们对3GPP TS 29.577规范的系列深度解读已全部完成。 我们从短信这个“老兵”在5G“新战场”的挑战出发，深入到IP-SM-GW和SMS Router这两大“桥梁”的功能逻辑，最终抵达了构成其服务能力的每一个API和数据模型的细节。

这份规范是5G网络向后兼容、实现业务连续性的一个绝佳范例。它告诉我们，SBA架构不仅能支持创新的未来业务，也能以优雅、高效的方式，将过去几十年积累的宝贵业务资产无缝地继承和发扬光大。

FAQ

Q1：CreateRoutingData中的smsf3Gpp和smsfNon3Gpp有什么区别？ A1：这两个字段用于区分UE是通过哪种接入网注册的短信服务。smsf3Gpp包含了UE通过3GPP标准接入（如5G NR, LTE）注册的SMSF信息。smsfNon3Gpp则包含了UE通过非3GPP接入（如不可信的WiFi）注册的SMSF信息。UDM可以同时提供这两种信息，使得IP-SM-GW在未来可以根据短信的特性或UE当前的接入状态，选择更优的SMSF进行投递。

Q2：MtForwardSm的响应中返回的SmsDeliveryData包含了什么？是最终的“已送达”报告吗？ A2：不完全是。SmsDeliveryData中包含的投递报告，其内容和时机取决于底层网络的实现。在最简单的模型中，它可能只是IP-SM-GW成功将短信转发给下一跳SMSF的一个确认。SMSF将短信递交给AMF，AMF再尝试递交给UE，这个过程可能还需要一些时间。最终UE是否成功接收、手机是否返回确认ACK，这些更深层次的投递状态，通常会通过更复杂的机制（如短信中心的回执功能）来处理，而不仅仅体现在这次同步的API响应中。

Q3：Nipsmgw_SMService API的OAuth 2.0安全scope是如何定义的？ A3：规范在6.1.9 Security节中定义了三个scope：

  • "nipsmgw_smservice": 访问整个API的基础权限。
  • "nipsmgw_smservice:mtsminfos:write": 专门用于PUT /mt-sm-infos/{gpsi}操作的写权限。这个权限应该只授予UDM。
  • "nipsmgw_smservice:sendsms:invoke": 专门用于POST .../sendsms操作的调用权限。这个权限应该只授予SMS-GMSC。 通过这种精细化的scope划分，可以实现对API消费者的最小权限授权，提升了系统的安全性。

Q4：为什么RoutingInfo操作的响应中，除了201 Created和200 OK/204 No Content，就没有其他的成功响应码了？ A4：因为PUT方法的语义决定了这一点。PUT请求的目标是使服务器上某个URI所代表的资源的状态，与请求体中的状态保持一致。这个操作最终只有两种结果：

  1. 资源原先不存在，服务器创建了它 → 201 Created。
  2. 资源原先已存在，服务器更新了它 → 200 OK (带内容) 或 204 No Content (不带内容)。 没有其他可能的成功状态，因此也不需要其他的成功响应码。

Q5：如果我想深入了解SMSF是如何与AMF交互，通过“SMS over NAS”发送短信的，应该看哪个规范？ A5：你应该关注3GPP TS 29.518 (Namf_Communication Service API)。SMSF作为服务消费者，会调用AMF提供的Namf_Communication_N1N2MessageTransfer服务，将需要发送给UE的NAS消息（其中就封装了SMS PDU）提交给AMF。AMF再通过N1接口将这个NAS消息透明地传达给UE。将TS 29.577和TS 29.518结合起来，你就能构建一个从SMS-GMSC到UE的、完整的SBA MT-SMS信令链路。

关系图谱