51学通信

深度解析 3GPP TS 29.576：5.1 Nmfaf_3daDataManagement Service API (数据管道配置API)

13分钟阅读

好的，我们已经圆满完成了对3GPP TS 29.576规范第四章功能逻辑的全面剖析。现在，我们将正式进入协议实现的“深水区”——第五章和第六章，将前面所有的功能描述，转化为精确、可编程的API接口和数据模型。

由于TS 29.576定义了两套独立的API，我们将分两篇最终章来完成解读。本篇将聚焦于第一套核心API——Nmfaf_3daDataManagement。

深度解析 3GPP TS 29.576：5.1 Nmfaf_3daDataManagement Service API (数据管道配置API)

本文技术原理深度参考了3GPP TS 29.576 V18.6.0 (2025-03) Release 18规范中，第五章5.1节“Nmfaf_3daDataManagement Service API”的全部核心内容。本文旨在为读者提供一份详尽的MFAF“数据管道配置”API“施工图”，我们将剖析其完整的资源模型、每一个API端点的具体用法，以及构成这些API交互的核心JSON对象的精确结构。

引言：从“设计图”到“控制台”——API的精确化实现

在第四章，我们扮演了“数据管道设计师”的角色，理解了Configure和Deconfigure这两个核心操作的逻辑功能。我们知道了如何从概念上设计一个数据流。

现在，我们将转换角色，成为坐在“MFAF中央控制台”前的DevOps工程师。第五章5.1节，就是这个控制台的操作手册。它将抽象的设计图，转化为可以输入到控制台的具体“指令”——即HTTP API调用。我们将学习：

  • 控制台的“登录地址”和“通信协议”是什么？(API入口与通信规则)
  • 控制台提供了哪些可以操作的“配置项”？(Resources)
  • 如何通过API指令，创建、修改和删除一个数据管道配置？

这将是一次从“做什么”到“怎么做”的终极跨越，为我们后续理解3ca数据分发API打下坚实的基础。

1. 解读第5.1.1章 & 5.1.2章 Introduction & Usage of HTTP (API入口与通信规则)

这部分内容为Nmfaf_3daDataManagement API的交互设定了基础框架，遵循SBA的统一规定。

3GPP TS 29.576 - 5.1.1 Introduction

The API URI of the Nmfaf_3daDataManagement API shall be: {apiRoot}/<apiName>/<apiVersion> …

  • The <apiName> shall be “nmfaf-3dadatamanagement”.
  • The <apiVersion> shall be “v1”.
  • API入口: nmfaf-3dadatamanagement API的根路径被确定为{apiRoot}/nmfaf-3dadatamanagement/v1。

3GPP TS 29.576 - 5.1.2 Usage of HTTP

  • 通信协议: HTTP/2。
  • 数据格式: application/json 和 application/problem+json。

2. 解读第5.1.3章 Resources (资源) - “配置项”的层级化管理

本节通过资源结构图和总览表，为我们绘制了3da API的完整“控制面板”。

2.1 5.1.3.1 Overview (资源概览)

“Figure 5.1.3.1-1: Resource URI structure of the Nmfaf_3daDataManagement API”展示了一个标准的集合/成员资源模型：

  • /configurations: MFAF配置集合。代表了MFAF中所有的数据管道配置。
  • /{transRefId}: 单个MFAF配置。代表一个由transRefId唯一标识的具体数据管道。

“Table 5.1.3.1-1: Resources and methods overview”将HTTP方法与Configure/Deconfigure操作进行了精确映射。

Resource nameResource URIHTTP methodDescription
MFAF Configurations/configurationsPOSTCreates a new individual MFAF Configuration resource.
Individual MFAF Configuration/configurations/{transRefId}PUTModifies an existing Individual MFAF Configuration subresource.
DELETEDeletes an Individual MFAF Configuration…

API操作与服务操作的映射关系:

  • POST /configurations: 实现 创建 配置 (Configure)。
  • PUT /configurations/{transRefId}: 实现 修改 配置 (Configure-Update)。
  • DELETE /configurations/{transRefId}: 实现 删除 配置 (Deconfigure)。

2.2 API操作详解

POST /configurations (创建配置)
  • 请求体 (MfafConfiguration): 必须包含一个MfafConfiguration对象，其核心是messageConfigurations数组，定义了一个或多个数据流的完整配置（数据源、处理逻辑、目的地）。
  • 成功响应 (201 Created):
    • 响应体: MfafConfiguration对象，是MFAF确认并可能补充（如mfafNotiInfo）后的最终配置。
    • Location头: 必须包含新创建配置的URI，形如.../configurations/{transRefId}。这个transRefId是MFAF生成的唯一标识。
PUT /configurations/{transRefId} (修改配置)
  • 请求体 (MfafConfiguration): 必须包含修改后的完整MfafConfiguration对象。
  • 成功响应 (200 OK / 204 No Content):
    • 200 OK: 修改成功，响应体是更新后的MfafConfiguration对象。
    • 204 No Content: 修改成功，响应体为空。
DELETE /configurations/{transRefId} (删除配置)
  • 请求: 无请求体。
  • 成功响应 (204 No Content): 表示配置及相关的底层订阅已成功删除。

3. 解读第5.1.6章 Data Model - “配置指令”的精确语法

本节定义了3da API交互中核心JSON对象的结构。

3.1 Type: MfafConfiguration - “数据管道”的总蓝图

这是POST和PUT操作的请求体，也是201/200响应的主体。

Table 5.1.6.2.2-1: Definition of type MfafConfiguration

  • messageConfigurations (M): array(MessageConfiguration)，基数1..N。核心字段，包含一个或多个具体的数据流配置。

3.2 Type: MessageConfiguration - 单个数据流的详细设计图

这是messageConfigurations数组中的元素，定义了一个从“入口”到“出口”的完整数据流。

Table 5.1.6.2.3-1: Definition of type MessageConfiguration

Attribute nameData typePDescription
correIdstringMAnalytics/Data Consumer Notification Correlation ID.
formatInstructFormattingInstructionOFormatting instructions to be used.
mfafNotiInfoMfafNotiInfoCThe MFAF notification information (i.e., data source).
notificationURIUriMThe notification URI of Data/Analytics Consumer.
notifEndpointsarray(NotifyEndpoint)OAdditional notification target addresses.
procInstructProcessingInstructionOProcessing instructions. (Single)
multiProcInstructsarray(ProcessingInstruction)OProcessing instructions. (Multiple)
adrfIdNfInstanceIdONF instance identifier of the ADRF.
suppFeatSupportedFeaturesCSupported features.

字段深度剖析:

  • 入口 (mfafNotiInfo): 定义数据从哪里来。MfafNotiInfo对象内部会包含数据源NF的标识和它所产生的通知的标识。
  • 出口 (notificationURI, notifEndpoints): 定义数据送到哪里去。notificationURI是主送地址，notifEndpoints可以定义多个“抄送”地址。
  • 加工 (formatInstruct, procInstruct, multiProcInstructs): 定义数据如何处理。multiProcInstructs的存在说明MFAF支持对同一份数据执行链式的、多步骤的处理。
  • 仓储 (adrfId): 定义处理后的数据是否需要以及存储到哪个分析数据仓库（ADRF）中。

3.3 Type: MfafNotiInfo - 数据源的“名片”

Table 5.1.6.2.4-1: Definition of type MfafNotiInfo

  • mfafNotifUri (M): MFAF用于接收来自数据源通知的URI。
  • mfafCorreld (M): MFAF用于关联这些通知的ID。 核心逻辑: 这个对象是MFAF在响应中返回给配置者的。它告诉配置者：“我已经为你的任务创建了一个内部的接收端点（mfafNotifUri）和关联ID（mfafCorreld）。如果你需要手动去数据源那里配置（虽然通常是MFAF自己去），请使用这个信息。”

总结与宣告

通过对第五章Nmfaf_3daDataManagement API的深度解读，我们已经将MFAF“数据管道工”的“控制台”操作得炉火纯青。

  1. 标准的资源管理API: API围绕/configurations资源，通过POST/PUT/DELETE实现了对数据管道配置的完整生命周期管理。

  2. 声明式的配置模型: 核心数据结构MfafConfiguration和MessageConfiguration提供了一种强大的声明式方法来定义端到端的数据流，将数据源、处理逻辑、目的地等所有要素都包含在一个原子性的配置单元中。

  3. 高度的灵活性与可扩展性: 支持批量配置（messageConfigurations数组）、多步处理（multiProcInstructs）、多目的地分发（notifEndpoints）和持久化存储（adrfId），使得MFAF能够支持极其复杂和多样化的数据分析场景。

我们已经完成了对TS 29.576规范第一部分核心服务的完整解读。我们已经知道如何指挥MFAF去搭建数据处理的“流水线”。

接下来，按照您的指令，我们将继续拆解本规范的第二部分核心服务，深入4.3节和5.2节，探索Nmfaf_3caDataManagement服务，看看数据在这条“流水线”上加工完成后，是如何被打包、通知和交付的。

FAQ

Q1：transRefId和correId有什么区别？ A1：这两个ID处于不同的层级，作用也不同。

  • transRefId (Transaction Reference Id): 是MFAF为整个MfafConfiguration资源分配的唯一ID，是这个配置在MFAF中的“主键”。它用于API层面（URI中）对整个配置进行PUT或DELETE。
  • correId (Correlation Id): 是数据流的业务层关联ID，由配置者（DCCF/NWDAF）在MessageConfiguration中提供。当MFAF通过3ca服务将数据分发出去时，会在通知中回传这个correId，以便最终的数据消费者能够将收到的数据与最初的分析任务关联起来。

Q2：procInstruct和multiProcInstructs为什么会同时存在？ A2：这是为了兼容性和扩展性。procInstruct支持单个处理指令，是基础功能。而multiProcInstructs是一个数组，支持将多个处理指令链接起来，形成一个处理链。这是一个更高级的特性（由MultiProcessingInstruction特性开关控制）。例如，可以配置为“先按用户ID进行过滤（指令1），再对结果按时间窗口进行聚合（指令2）”。规范建议，如果支持该特性，应优先使用multiProcInstructs。

Q3：notifEndpoints这个字段有什么用？为什么有了notificationURI还需要它？ A3：notificationURI是主通知端点，是数据流的“主干道”。而notifEndpoints提供了一种“数据分叉”或“抄送”的能力。MFAF可以将同一份处理后的数据，同时发送给多个不同的消费者。例如，一份网络拥塞分析报告，可以主送到NWDAF（notificationURI）用于长期趋势分析，同时“抄送”一份到NEF（notifEndpoints中的一个条目），由NEF实时暴露给某个第三方交通管理应用。

Q4：谁负责向mfafNotiInfo中MFAF提供的mfafNotifUri发送通知？ A4：原始的数据源NF（如AMF, SMF, NWDAF等）。MFAF在Configure成功后，会拿着mfafNotiInfo中的信息，去向数据源NF发起一个事件订阅请求（例如，调用Namf_EventExposure_Subscribe）。在那个订阅请求中，MFAF会把自己生成的mfafNotifUri作为回调地址提供给数据源NF。这样，当数据源有事件发生时，它就会向这个地址发送通知，数据就流入了MFAF的数据管道。

Q5：3da API的安全性是如何保证的？ A5：3da API的权限非常高，其安全性至关重要。规范在5.1.9 Security节中指出，除了通用的TLS和OAuth 2.0保护外，它定义了一个专门的OAuth 2.0 scope——"nmfaf-3dadatamanagement"。只有拥有这个scope权限的NF（主要是经过严格认证的DCCF和NWDAF）才能调用3da的API。任何其他NF（如PCF, SMF）都无法配置MFAF，只能作为3ca服务的被动数据接收者。

关系图谱