5.4 TrafficInfluence API
29.5223GPP5G SystemNetwork Exposure Function Northbound APIsRelease 18Stage 3TS
5.4.1 Resources
5.4.1.1 Overview
All resource URIs of this API should have the following root:
{apiRoot}/3gpp-traffic-influence/v1
"apiRoot" is set as described in clause 5.2.4 in 3GPP TS 29.122 [4]. "apiName" shall be set to "3gpp-traffic-influence" and "apiVersion" shall be set to "v1" for the current version defined in the present document. All resource URIs in the clauses below are defined relative to the above root URI.
This clause describes the structure for the Resource URIs as shown in figure 5.4.1.1-1 and the resources and HTTP methods used for the TrafficInfluence API.
Figure 5.4.1.1-1: Resource URI structure of the TrafficInfluence API
Table 5.4.1.1-1 provides an overview of the resources and HTTP methods applicable for the TrafficInfluence API.
Table 5.4.1.1-1: Resources and methods overview
|
Resource name |
Resource URI |
HTTP method |
Description |
|
Traffic Influence Subscription |
/{afId}/subscriptions |
GET |
Read all subscriptions for a given AF |
|
POST |
Create a new subscription to traffic influence |
||
|
Individual Traffic Influence Subscription |
/{afId}/subscriptions/{subscriptionId} |
GET |
Read a subscription to traffic influence |
|
PUT |
Modify all of the properties of an existing subscription to traffic influence |
||
|
PATCH |
Modify part of the properties of an existing subscription to traffic influence |
||
|
DELETE |
Delete a subscription to traffic influence |
5.4.1.2 Resource: Traffic Influence Subscription
5.4.1.2.1 Introduction
This resource allows a AF to read all active traffic influence subscribtions for the given AF.
5.4.1.2.2 Resource Definition
Resource URI: {apiRoot}/3gpp-traffic-influence/v1/{afId}/subscriptions
This resource shall support the resource URI variables defined in table 5.4.1.2.2-1.
Table 5.4.1.2.2-1: Resource URI variables for this resource
|
Name |
Data type |
Definition |
|
apiRoot |
string |
Clause 5.2.4 of 3GPP TS 29.122 [4]. |
|
afId |
string |
Identifier of the AF. |
5.4.1.2.3 Resource Methods
5.4.1.2.3.1 General
The following clauses specify the resource methods supported by the resource as described in clause 5.4.1.2.2.
5.4.1.2.3.2 GET
The GET method allows to read all active subscriptions for a given AF. The AF shall initiate the HTTP GET request message and the NEF shall respond to the message.
This method shall support the URI query parameters specified in table 5.4.1.2.3.2-1.
Table 5.4.1.2.3.2-1: URI query parameters supported by the GET method on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
N/A |
This method shall support the request data structures specified in table 5.4.1.2.3.2-2 and the response data structures and response codes specified in table 5.4.1.2.3.2-3.
Table 5.4.1.2.3.2-2: Data structures supported by the GET Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
N/A |
Table 5.4.1.2.3.2-3: Data structures supported by the GET Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
array(TrafficInfluSub) |
M |
0..N |
200 OK |
The subscription information for the AF in the request URI are returned. |
|
N/A |
307 Temporary Redirect |
Temporary redirection, during subscription retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
|
N/A |
308 Permanent Redirect |
Permanent redirection, during subscription retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
|
NOTE: The mandatory HTTP error status codes for the GET method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply. |
||||
Table 5.4.1.2.3.2-4: Headers supported by the 307 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative NEF. |
Table 5.4.1.2.3.2-5: Headers supported by the 308 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative NEF. |
5.4.1.2.3.3 POST
The POST method creates a new subscription resource to traffic influence subscription for a given AF. The AF shall initiate the HTTP POST request message and the NEF shall respond to the message. The NEF shall construct the URI of the created resource.
This method shall support the request data structures specified in table 5.4.1.2.3.3-1 and the response data structures and response codes specified in table 5.4.1.2.3.3-2.
Table 5.4.1.2.3.3-1: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
TrafficInfluSub |
M |
1 |
Parameters to register a subscription to influencing traffic routing and/or notification about UP management events with the NEF. |
Table 5.4.1.2.3.3-2: Data structures supported by the POST Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
TrafficInfluSub |
M |
1 |
201 Created |
The subscription was created successfully. The URI of the created resource shall be returned in the "Location" HTTP header. |
|
NOTE: The mandatory HTTP error status codes for the POST method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply. |
||||
Table 5.4.1.2.3.3-3: Headers supported by the 201 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
Contains the URI of the newly created resource, according to the structure: {apiRoot}/3gpp-traffic-Influence/v1/{afId}/subscriptions/{subscriptionId} |
5.4.1.3 Resource: Individual Traffic Influence Subscription
5.4.1.3.1 Introduction
This resource allows a AF to register a subscription to influencing traffic routing and/or notification about UP management events with the NEF.
5.4.1.3.2 Resource Definition
Resource URI: {apiRoot}/3gpp-traffic-influence/v1/{afId}/subscriptions/{subscriptionId}
This resource shall support the resource URI variables defined in table 5.4.1.3.2-1.
Table 5.4.1.3.2-1: Resource URI variables for this resource
|
Name |
Data type |
Definition |
|
apiRoot |
string |
Clause 5.2.4 of 3GPP TS 29.122 [4]. |
|
afId |
string |
Identifier of the AF. |
|
subscriptionId |
string |
Identifier of the subscription. |
5.4.1.3.3 Resource Methods
5.4.1.3.3.1 General
The following clauses specify the resource methods supported by the resource as described in clause 5.4.1.3.2.
5.4.1.3.3.2 GET
The GET method allows to read the active subscription for a given AF and subscription Id. The AF shall initiate the HTTP GET request message and theNEF shall respond to the message.
This method shall support the URI query parameters specified in table 5.4.1.3.3.2-1.
Table 5.4.1.3.3.2-1: URI query parameters supported by the GET method on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
N/A |
This method shall support the request data structures specified in table 5.4.1.3.3.2-2 and the response data structures and response codes specified in table 5.4.1.3.3.2-3.
Table 5.4.1.3.3.2-2: Data structures supported by the GET Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
N/A |
Table 5.4.1.3.3.2-3: Data structures supported by the GET Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
TrafficInfluSub |
M |
1 |
200 OK |
The subscription information for the AF in the request URI are returned. |
|
N/A |
307 Temporary Redirect |
Temporary redirection, during subscription retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
|
N/A |
308 Permanent Redirect |
Permanent redirection, during subscription retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
|
NOTE: The mandatory HTTP error status codes for the GET method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply. |
||||
Table 5.4.1.3.3.2-4: Headers supported by the 307 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative NEF. |
Table 5.4.1.3.3.2-5: Headers supported by the 308 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative NEF. |
5.4.1.3.3.3 PUT
The PUT method is used to replace an existing subscription resource to update a subscription. The AF shall initiate the HTTP PUT request message and the NEF shall respond to the message.
This method shall support the request data structures specified in table 5.4.1.3.3.3-1 and the response data structures and response codes specified in table 5.4.1.3.3.3-2.
Table 5.4.1.3.3.3-1: Data structures supported by the PUT Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
TrafficInfluSub |
M |
1 |
Modify an existing subscription to influencing traffic routing and/or notification about UP management events with the NEF. |
Table 5.4.1.3.3.3-2: Data structures supported by the PUT Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
TrafficInfluSub |
M |
1 |
200 OK |
The subscription was replaced successfully and a representation is returned. |
|
N/A |
204 No Content |
The subscription was replaced successfully. |
||
|
N/A |
307 Temporary Redirect |
Temporary redirection, during subscription modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
|
N/A |
308 Permanent Redirect |
Permanent redirection, during subscription modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
|
NOTE: The mandatory HTTP error status codes for the PUT method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply. |
||||
Table 5.4.1.3.3.3-3: Headers supported by the 307 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative NEF. |
Table 5.4.1.3.3.3-4: Headers supported by the 308 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative NEF. |
5.4.1.3.3.4 PATCH
The PATCH method allows to change some properties of an existing traffic influence subscription. The AF shall initiate the HTTP PATCH request message and the NEF shall respond to the message.
This method shall support the request data structures specified in table 5.4.1.3.3.4-1 and the response data structures and response codes specified in table 5.4.1.3.3.4-2.
Table 5.4.1.3.3.4-1: Data structures supported by the PATCH Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
TrafficInfluSubPatch |
M |
1 |
Partial update of a subscription to influencing traffic routing and/or notifications about UP management events with the NEF. |
Table 5.4.1.3.3.4-2: Data structures supported by the PATCH Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
TrafficInfluSub |
M |
1 |
200 OK |
The subscription was partial modified successfully and a representation is returned. |
|
N/A |
204 No Content |
The subscription was partial modified successfully. |
||
|
N/A |
307 Temporary Redirect |
Temporary redirection, during subscription modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
|
N/A |
308 Permanent Redirect |
Permanent redirection, during subscription modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
|
NOTE: The mandatory HTTP error status codes for the PATCH method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply. |
||||
Table 5.4.1.3.3.4-3: Headers supported by the 307 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative NEF. |
Table 5.4.1.3.3.4-4: Headers supported by the 308 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative NEF. |
5.4.1.3.3.5 DELETE
The DELETE method deletes the traffic influence subscription for a given AF. The AF shall initiate the HTTP DELETE request message and the NEF shall respond to the message.
This method shall support the URI query parameters specified in table 5.4.1.3.3.5-1.
Table 5.4.1.3.3.5-1: URI query parameters supported by the DELETE method on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
N/A |
This method shall support the request data structures specified in table 5.4.1.3.3.5-2 and the response data structures and response codes specified in table 5.4.1.3.3.5-3.
Table 5.4.1.3.3.5-2: Data structures supported by the DELETE Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
N/A |
Table 5.4.1.3.3.5-3: Data structures supported by the DELETE Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
N/A |
204 No Content |
The subscription was terminated successfully. |
||
|
N/A |
307 Temporary Redirect |
Temporary redirection, during subscription termination. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
|
N/A |
308 Permanent Redirect |
Permanent redirection, during subscription termination. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
|
NOTE: The mandatory HTTP error status codes for the DELETE method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply. |
||||
Table 5.4.1.3.3.5-4: Headers supported by the 307 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative NEF. |
Table 5.4.1.3.3.5-5: Headers supported by the 308 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative NEF. |
5.4.2 Notifications
5.4.2.1 Introduction
Upon receipt of a UP management event notification from the SMF indicating the subscribed event (e.g. a DNAI has changed) is detected, the NEF shall send an HTTP POST message including the notified event to the AF.
Upon receipt of the event notification, the AF may send an HTTP POST request as acknowledgement for the UP path management event notification to inform the NEF about the result of application layer relocation.
The NEF and the AF shall support the notification mechanism as described in clause 5.2.5 of 3GPP TS 29.122 [4].
Table 5.4.2.1-1: Notifications overview
|
Notification |
Callback URI |
HTTP method or custom operation |
Description (service operation) |
|
Event Notification |
{notificationDestination} |
POST |
The UP management event notification from the NEF to the AF. |
|
Acknowledgement of event notification |
{afAckUri} |
POST |
The Acknowledgement of Event Notification is used by the AF to acknowledge the NEF about handling result of the event notification. |
5.4.2.2 Event Notification
5.4.2.2.1 Description
The Event Notification is used by the NEF to report the UP path management event notification from the SMF to the AF.
5.4.2.2.2 Target URI
The Callback URI "{notificationDestination}" shall be used with the callback URI variables defined in table 5.4.2.2.2-1.
Table 5.4.2.2.2-1: Callback URI variables
|
Name |
Data type |
Definition |
|
notificationDestination |
Link |
Callback reference provided by the AF during creation/modification of the subscription within the TrafficInfluSub data type as defined in table 5.4.3.3.2-1 or the TrafficInfluSubPatch data type as defined in table 5.4.3.3.3-1. |
5.4.2.2.3 Operation Definition
5.4.2.2.3.1 Notification via HTTP POST
This method shall support the request data structures specified in table 5.4.2.2.3.1-1 and the response data structures and response codes specified in table 5.4.2.2.3.1-2.
Table 5.4.2.2.3.1-1: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
EventNotification |
M |
1 |
The UP management event notification is provided by the NEF to the AF. |
Table 5.4.2.2.3.1-2: Data structures supported by the POST Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
N/A |
204 No Content |
The event notification is received successfully. |
||
|
N/A |
307 Temporary Redirect |
Temporary redirection, during event notification. The response shall include a Location header field containing an alternative URI representing the end point of an alternative AF where the notification should be sent. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
|
N/A |
308 Permanent Redirect |
Permanent redirection, during event notification. The response shall include a Location header field containing an alternative URI representing the end point of an alternative AF where the notification should be sent. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
|
NOTE: The mandatory HTTP error status codes for the POST method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply. |
||||
Table 5.4.2.2.3.1-3: Headers supported by the 307 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI representing the end point of an alternative AF towards which the notification should be redirected. |
Table 5.4.2.2.3.1-4: Headers supported by the 308 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI representing the end point of an alternative AF towards which the notification should be redirected. |
5.4.2.2.3.2 Notification via Websocket
If supported by both AF and NEF and successfully negotiated, the EventNotification may alternatively be delivered through the Websocket mechanism as defined in clause 5.2.5.4 of 3GPP TS 29.122 [4].
5.4.2.3 Acknowledgement of event notification
5.4.2.3.1 Description
The Acknowledgement of Event Notification is used by the AF to acknowledge the NEF about handling result of the event notification (e.g. UP path change).
5.4.2.3.2 Target URI
The Callback URI "{afAckUri}" shall be used with the callback URI variables defined in table 5.4.2.3.2-1.
Table 5.4.2.3.2-1: Callback URI variables
|
Name |
Data type |
Definition |
|
afAckUri |
Link |
Callback reference provided by the NEF during event notification within the EventNotification data type as defined in Table 5.4.3.3.4-1. |
5.4.2.3.3 Operation Definition
5.4.2.3.3.1 Notification via HTTP POST
This method shall support the request data structures specified in table 5.4.2.3.3.1-1 and the response data structures and response codes specified in table 5.4.2.3.3.1-2.
Table 5.4.2.3.3.1-1: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
AfAckInfo |
M |
1 |
Acknowledgement information of event notification. |
Table 5.4.2.3.3.1-2: Data structures supported by the POST Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
N/A |
204 No Content |
The acknowledgement of event notification is received successfully. |
||
|
N/A |
307 Temporary Redirect |
Temporary redirection, during acknowledgement of event notification. The response shall include a Location header field containing an alternative URI representing the end point of an alternative NEF where the notification should be sent. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
|
N/A |
308 Permanent Redirect |
Permanent redirection, during acknowledgement of event notification. The response shall include a Location header field containing an alternative URI representing the end point of an alternative NEF where the notification should be sent. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
|
NOTE: The mandatory HTTP error status codes for the POST method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply. |
||||
Table 5.4.2.3.3.1-3: Headers supported by the 307 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI representing the end point of an alternative NEF towards which the notification should be redirected. |
Table 5.4.2.3.3.1-4: Headers supported by the 308 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI representing the end point of an alternative NEF towards which the notification should be redirected. |
5.4.3 Data Model
5.4.3.1 General
This clause specifies the application data model supported by the TrafficInfluence API.
Table 5.4.3.1-1 specifies the data types defined for the TrafficInfluence API.
Table 5.4.3.1-1: TrafficInfluence API specific Data Types
|
Data type |
Clause defined |
Description |
Applicability |
|
AfAckInfo |
5.4.3.3.6 |
Represents acknowledgement information of a traffic influence event notification. |
|
|
AfResultInfo |
5.4.3.3.5 |
Identifies the result of application layer handling. |
|
|
AfResultStatus |
5.4.3.4.4 |
Represents the status of application handling result. |
|
|
EventNotification |
5.4.3.3.4 |
Represents a traffic influence event notification. |
|
|
SubscribedEvent |
5.4.3.4.3 |
Represents the type of UP path management events for which the AF requests to be notified. |
|
|
TrafficInfluSub |
5.4.3.3.2 |
Represents a traffic influence subscription. |
|
|
TrafficInfluSubPatch |
5.4.3.3.3 |
Represents parameters to request the modification of a traffic influence subscription resource. |
5.4.3.2 Reused data types
The data types reused by the TrafficInfluence API from other specifications are listed in table 5.4.3.2-1.
Table 5.4.3.2-1: Re-used Data Types
|
Data type |
Reference |
Comments |
|
Dnai |
3GPP TS 29.571 [8] |
Identifies a DNAI. |
|
DnaiChangeType |
3GPP TS 29.571 [8] |
Describes the types of DNAI change. |
|
Dnn |
3GPP TS 29.571 [8] |
Identifies a DNN. |
|
DurationSec |
3GPP TS 29.571 [8] |
Identifies a period of time in units of seconds. |
|
EasIpReplacementInfo |
3GPP TS 29.571 [8] |
Represents EAS IP replacement information. |
|
EthFlowDescription |
3GPP TS 29.514 [7] |
Contains the Ethernet data flow information. (NOTE) |
|
ExternalGroupId |
3GPP TS 29.122 [4] |
External Group Identifier for a user group. |
|
FlowInfo |
3GPP TS 29.122 [4] |
Contains the IP data flow information. |
|
GeographicalArea |
Clause 5.17.3.3.4 |
Identifies a geographical area. |
|
Gpsi |
3GPP TS 29.571 [8] |
Identifies a GPSI. |
|
IpAddr |
3GPP TS 29.571 [8] |
Identifes an IP address. |
|
Ipv4Addr |
3GPP TS 29.122 [4] |
Identifies an IPv4 address. |
|
Ipv6Addr |
3GPP TS 29.122 [4] |
Identifies an IPv6 address. |
|
Ipv6Prefix |
3GPP TS 29.571 [8] |
Identifies an IPv6 Prefix. |
|
Link |
3GPP TS 29.122 [4] |
Identifies a referenced resource. |
|
MacAddr48 |
3GPP TS 29.571 [8] |
Identifies a MAC address. |
|
ReportingInformation |
3GPP TS 29.523 [22] |
Represents the event reporting requirements. |
|
RouteToLocation |
3GPP TS 29.571 [8] |
Describes the traffic routes to the locations of the application. |
|
Snssai |
3GPP TS 29.571 [8] |
Identifies the S-NSSAI. |
|
SupportedFeatures |
3GPP TS 29.571 [8] |
Used to negotiate the applicability of the optional features defined in table 5.4.4-1. |
|
TemporalValidity |
3GPP TS 29.514 [7] |
Indicates the time interval(s) during which the AF request is to be applied |
|
Uinteger |
3GPP TS 29.571 [8] |
Unsigned integer. |
|
UintegerRm |
3GPP TS 29.571 [8] |
This data type is defined in the same way as the "Uinteger" data type, but with the OpenAPI "nullable: true" property. |
|
WebsockNotifConfig |
3GPP TS 29.122 [4] |
Contains the configuration parameters to set up notification delivery over Websocket protocol. |
|
NOTE: In order to support a set of MAC addresses with a specific range in the traffic filter, feature MacAddressRange as specified in clause 5.4.4 shall be supported. |
||
5.4.3.3 Structured data types
5.4.3.3.1 Introduction
This clause defines the structured data types to be used in resource representations.
5.4.3.3.2 Type: TrafficInfluSub
This type represents a traffic influence subscription. The same structure is used in the subscription request and subscription response.
Table 5.4.3.3.2-1: Definition of type TrafficInfluSub
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability (NOTE 1) |
|
afServiceId |
string |
O |
0..1 |
Identifies a service on behalf of which the AF is issuing the request. |
|
|
afAppId |
string |
O |
0..1 |
Identifies an application. (NOTE 3) |
|
|
afTransId |
string |
O |
0..1 |
Identifies an NEF Northbound interface transaction, generated by the AF. |
|
|
appReloInd |
boolean |
O |
0..1 |
Identifies whether an application can be relocated once a location of the application has been selected. Set to "true" if it can be relocated; otherwise set to "false". Default value is "false" if omitted. |
|
|
dnn |
Dnn |
O |
0..1 |
Identifies a DNN, a full DNN with both the Network Identifier and Operator Identifier, or a DNN with the Network Identifier only. |
|
|
snssai |
Snssai |
O |
0..1 |
Identifies an S-NSSAI. |
|
|
externalGroupId |
ExternalGroupId |
O |
0..1 |
Identifies a group of users. (NOTE 2) |
|
|
anyUeInd |
boolean |
O |
0..1 |
Identifies whether the AF request applies to any UE (i.e. all UEs). This attribute shall set to "true" if applicable for any UE, otherwise, set to "false". (NOTE 2) |
|
|
subscribedEvents |
array(SubscribedEvent) |
O |
1..N |
Identifies the requirement to be notified of the event(s). |
|
|
gpsi |
Gpsi |
O |
0..1 |
Identifies a user. (NOTE 2) |
|
|
ipv4Addr |
Ipv4Addr |
O |
0..1 |
Identifies the IPv4 address. (NOTE 2) |
|
|
ipDomain |
string |
O |
0..1 |
The IPv4 address domain identifier. The attribute may only be provided if the ipv4Addr attribute is present. |
|
|
ipv6Addr |
Ipv6Addr |
O |
0..1 |
Identifies the IPv6 address. (NOTE 2) |
|
|
macAddr |
MacAddr48 |
O |
0..1 |
Identifies the MAC address. (NOTE 2) |
|
|
dnaiChgType |
DnaiChangeType |
O |
0..1 |
Identifies a type of notification regarding UP path management event. |
|
|
notificationDestination |
Link |
C |
0..1 |
Contains the Callback URL to receive the notification from the NEF. It shall be present if the "subscribedEvents" is present. |
|
|
requestTestNotification |
boolean |
O |
0..1 |
Set to true by the AF to request the NEF to send a test notification as defined in clause 5.2.5.3 of 3GPP TS 29.122 [4]. Set to false or omitted otherwise. |
Notification_test_event |
|
websockNotifConfig |
WebsockNotifConfig |
O |
0..1 |
Configuration parameters to set up notification delivery over Websocket protocol. |
Notification_websocket |
|
self |
Link |
C |
0..1 |
Link to the created resource. This parameter shall be supplied by the NEF in HTTP responses that include an object of TrafficInfluSub type |
|
|
trafficFilters |
array(FlowInfo) |
O |
1..N |
Identifies IP packet filters. (NOTE 3) |
|
|
ethTrafficFilters |
array(EthFlowDescription) |
O |
1..N |
Identifies Ethernet packet filters. (NOTE 3) |
|
|
trafficRoutes |
array(RouteToLocation) |
O |
1..N |
Identifies the N6 traffic routing requirement. |
|
|
tfcCorrInd |
boolean |
O |
0..1 |
Indication of traffic correlation. May only be included when "externalGroupId" attribute was included within the TrafficInfluSub data type previously. It is used to indicate that for the group of UEs, the targeted PDU sessions should be correlated by a common DNAI. Set to "true" if it should be correlated; otherwise set to "false". Default value is "false" if omitted. (NOTE 4) |
|
|
tempValidities |
array(TemporalValidity) |
O |
1..N |
Indicates the time interval(s) during which the AF request is to be applied. |
|
|
validGeoZoneIds |
array(string) |
O |
1..N |
Identifies a geographic zone that the AF request applies only to the traffic of UE(s) located in this specific zone. This attribute is deprecated; the attribute "geoAreas" should be used instead. |
|
|
geoAreas |
array(GeographicalArea) |
O |
1..N |
Identifies geographical areas within which the AF request applies. This attribute deprecates validGeoZoneIds attribute. |
|
|
afAckInd |
boolean |
O |
0..1 |
Identifies whether the AF acknowledgement of UP path event notification is expected. Set to "true" if the AF acknowledge is expected; otherwise set to "false". Default value is "false" if omitted. |
URLLC |
|
addrPreserInd |
boolean |
O |
0..1 |
Indicates whether UE IP address should be preserved. This attribute shall set to "true" if preserved, otherwise, set to "false". Defalult value is "false" if omitted. |
URLLC |
|
simConnInd |
boolean |
O |
0..1 |
Indication of simultaneous connectivity temporarily maintained for the source and target PSA. If it is included and set to "true", temporary simultaneous connectivity should be kept. The default value "false" applies, if the attribute is not present and has not been supplied previously. |
SimultConnectivity |
|
simConnTerm |
DurationSec |
O |
0..1 |
Indication of the minimum time interval to be considered for inactivity of the traffic routed via the source PSA during the edge re-location procedure. It may be included when the "simConnInd" attribute is set to true. |
SimultConnectivity |
|
maxAllowedUpLat |
Uinteger |
O |
0..1 |
Indicates the target user plane latency in units of milliseconds. The SMF may use this value to decide whether edge relocation is needed to ensure that the user plane latency does not exceed the value. |
AF_lantency |
|
easIpReplaceInfos |
array(EasIpReplacementInfo) |
O |
1..N |
Contains EAS IP replacement information. |
EASIPreplacement |
|
easRedisInd |
boolean |
O |
0..1 |
Indicates the EAS rediscovery is required for the application if it is included and set to "true". Defalult value is "false" if omitted. The indication shall be invalid after it was applied unless it is provided again. |
EASDiscovery |
|
eventReq |
ReportingInformation |
O |
0..1 |
Indicates the event reporting requirements. This attribute may be provided if the "EDGEAPP" feature is supported and the "subscribedEvents" attribute is present. |
EDGEAPP |
|
eventReports |
array(EventNotification) |
C |
1..N |
Represents user plane path management event report(s). This attribute shall be present in an HTTP POST response if the immediate reporting indication in the "immRep" attribute within the "eventReq" attribute is set to true and the "subscribedEvents" was present in the corresponding HTTP POST request and the report(s) are available. This attribute may also be present in an HTTP PUT or PATCH response when the report(s) are available. |
EDGEAPP |
|
suppFeat |
SupportedFeatures |
C |
0..1 |
Indicates the list of Supported features used as described in clause 5.4.4. This attribute shall be provided in the POST request and in the response of successful resource creation. |
|
|
NOTE 1: Properties marked with a feature as defined in clause 5.4.4 are applicable as described in clause 5.2.7 of 3GPP TS 29.122 [4]. If no feature is indicated, the related property applies for all the features. NOTE 2: One of individual UE identifier (i.e. "gpsi", "macAddr", "ipv4Addr" or "ipv6Addr"), External Group Identifier (i.e. "externalGroupId") or any UE indication "anyUeInd" shall be included. NOTE 3: One of "afAppId", "trafficFilters" or "ethTrafficFilters" shall be included. NOTE 4: The indication of traffic correlation shall be provided only when the AF requires that all the PDU sessions related to the 5G VN group member UEs should be correlated by a common DNAI in the user plane for the traffic as described in 3GPP TS 23.501 [3], clause 5.6.7.1 and clause 5.29. |
|||||
5.4.3.3.3 Type: TrafficInfluSubPatch
This type represents a subscription of traffic influence parameters provided by the AF to the NEF. The structure is used for HTTP PATCH request.
Table 5.4.3.3.3-1: Definition of type TrafficInfluSubPatch
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
appReloInd |
boolean |
O |
0..1 |
Identifies whether an application can be relocated once a location of the application has been selected. (NOTE) |
|
|
trafficFilters |
array(FlowInfo) |
O |
1..N |
Identifies IP packet filters. |
|
|
ethTrafficFilters |
array(EthFlowDescription) |
O |
1..N |
Identifies Ethernet packet filters. |
|
|
trafficRoutes |
array(RouteToLocation) |
O |
1..N |
Identifies the N6 traffic routing requirement. (NOTE) |
|
|
tfcCorrInd |
boolean |
O |
0..1 |
Indication of traffic correlation. May only be included when "externalGroupId" attribute was included within the TrafficInfluSub data type previously. It is used to indicate that for the group of UEs, the targeted PDU sessions should be correlated by a common DNAI. |
|
|
tempValidities |
array(TemporalValidity) |
O |
1..N |
Indicates the time interval(s) during which the AF request is to be applied. (NOTE) |
|
|
validGeoZoneIds |
array(string) |
O |
1..N |
Identifies a geographic zone that the AF request applies only to the traffic of UE(s) located in this specific zone. (NOTE) This attribute is deprecated; the attribute "geoAreas" should be used instead. |
|
|
geoAreas |
array(GeographicalArea) |
O |
1..N |
Identifies geographical areas within which the AF request applies. (NOTE) This attribute deprecates validGeoZoneIds attribute. |
|
|
afAckInd |
boolean |
O |
0..1 |
Identifies whether the AF acknowledgement of UP path event notification is expected. |
URLLC |
|
addrPreserInd |
boolean |
O |
0..1 |
Indicates whether UE IP address should be preserved. (NOTE) |
URLLC |
|
simConnInd |
boolean |
O |
0..1 |
Indication of simultaneous connectivity temporarily maintained for the source and target PSA. If it is included and set to "true", temporary simultaneous connectivity should be kept. |
SimultConnectivity |
|
simConnTerm |
DurationSec |
O |
0..1 |
Indication of the minimum time interval to be considered for inactivity of the traffic routed via the source PSA during the edge re-location procedure. |
SimultConnectivity |
|
maxAllowedUpLat |
UintegerRm |
O |
0..1 |
Indicates the target user plane latency in units of milliseconds. The SMF may use this value to decide whether edge relocation is needed to ensure that the user plane latency does not exceed the value. |
AF_latency |
|
easIpReplaceInfos |
array(EasIpReplacementInfo) |
O |
1..N |
Contains EAS IP replacement information. |
EASIPreplacement |
|
easRedisInd |
boolean |
O |
0..1 |
Indicates the EAS rediscovery is required for the application if it is included and set to "true". Defalult value is "false" if omitted. The indication shall be invalid after it was applied unless it is provided again. |
EASDiscovery |
|
notificationDestination |
Link |
O |
0..1 |
Contains the Callback URL to receive the notification from the NEF. |
|
|
eventReq |
ReportingInformation |
O |
0..1 |
Indicates the event reporting requirements. This attribute may be provided if the "EDGEAPP" feature is supported. |
EDGEAPP |
|
NOTE: The value of the property shall be set to NULL for removal. |
|||||
5.4.3.3.4 Type: EventNotification
Table 5.4.3.3.4-1: Definition of type EventNotification
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability (NOTE 1) |
|
afTransId |
string |
O |
0..1 |
Identifies an NEF Northbound interface transaction, generated by the AF. |
|
|
dnaiChgType |
DnaiChangeType |
M |
1 |
Identifies the type of notification regarding UP path management event. |
|
|
sourceTrafficRoute |
RouteToLocation |
O |
0..1 |
Identifies the N6 traffic routing information associated to the source DNAI. May be present if the "subscribedEvent" sets to "UP_PATH_CHANGE". (NOTE 3) |
|
|
subscribedEvent |
SubscribedEvent |
M |
1 |
Identifies a UP path management event the AF requested to be notified of. |
|
|
targetTrafficRoute |
RouteToLocation |
O |
0..1 |
Identifies the N6 traffic routing information associated to the target DNAI. May be present if the "subscribedEvent" sets to "UP_PATH_CHANGE". (NOTE 3) |
|
|
sourceDnai |
Dnai |
O |
0..1 |
Source DN Access Identifier. Shall be included for event "UP_PATH_CHANGE" if the DNAI changed (NOTE 2, NOTE 3). |
|
|
targetDnai |
Dnai |
O |
0..1 |
Target DN Access Identifier. Shall be included for event "UP_PATH_CHANGE" if the DNAI changed (NOTE 2, NOTE 3). |
|
|
gpsi |
Gpsi |
O |
0..1 |
Identifies a user. |
|
|
srcUeIpv4Addr |
Ipv4Addr |
O |
0..1 |
The IPv4 Address of the served UE for the source DNAI. |
|
|
srcUeIpv6Prefix |
Ipv6Prefix |
O |
0..1 |
The Ipv6 Address Prefix of the served UE for the source DNAI. |
|
|
tgtUeIpv4Addr |
Ipv4Addr |
O |
0..1 |
The IPv4 Address of the served UE for the target DNAI. |
|
|
tgtUeIpv6Prefix |
Ipv6Prefix |
O |
0..1 |
The Ipv6 Address Prefix of the served UE for the target DNAI. |
|
|
ueMac |
MacAddr48 |
O |
0..1 |
UE MAC address of the served UE. |
|
|
afAckUri |
Link |
O |
0..1 |
The URI provided by the NEF for the AF acknowledgement. May only be included for event "UP_PATH_CHANGE". |
URLLC |
|
NOTE 1: Properties marked with a feature as defined in clause 5.4.4 are applicable as described in clause 5.2.7 of 3GPP TS 29.122 [4]. If no feature is indicated, the related property applies for all the features. NOTE 2: If the DNAI is not changed while the N6 traffic routing information is changed, the "sourceDnai" attribute and "targetDnai" attribute shall not be provided. NOTE 3: The change from the UP path status where no DNAI applies to a status where a DNAI applies indicates the activation of the related AF request and therefore only the target DNAI and N6 traffic routing information is provided in the event notification; the change from the UP path status where a DNAI applies to a status where no DNAI applies indicates the de-activation of the related AF request and therefore only the source DNAI and N6 traffic routing information is provided in the event notification. |
|||||
5.4.3.3.5 Type: AfResultInfo
Table 5.4.3.3.5-1: Definition of type AfResultInfo
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
afStatus |
AfResultStatus |
M |
1 |
Identifies the result of the application relocation. |
|
|
trafficRoute |
RouteToLocation |
O |
0..1 |
Identifies the N6 traffic routing information associated to the target DNAI. May only be present if the "afStatus" sets to "SUCCESS". |
|
|
upBuffInd |
boolean |
O |
0..1 |
If present and set to "true", it indicates that buffering of uplink traffic to the target DNAI is needed. The default value is "false". May only be present if the "afStatus" sets to "SUCCESS". |
ULBuffering |
|
easIpReplaceInfos |
array(EasIpReplacementInfo) |
O |
1..N |
Contains EAS IP replacement information. |
EASIPreplacement |
5.4.3.3.6 Type AfAckInfo
Table 5.4.3.3.6-1: Definition of type AfAckInfo
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
afTransId |
string |
C |
0..1 |
Identifies an NEF Northbound interface transaction, generated by the AF. It shall be provided if the AF has previously provided it. |
|
|
ackResult |
AfResultInfo |
M |
1 |
Identifies the result of application layer handling. |
|
|
gpsi |
Gpsi |
O |
0..1 |
Identifies a GPSI. |
5.4.3.4 Simple data types and enumerations
5.4.3.4.1 Introduction
This clause defines simple data types and enumerations that can be referenced from data structures defined in the previous clauses.
5.4.3.4.2 Simple data types
The simple data types defined in table 5.4.3.4.2-1 shall be supported.
Table 5.4.3.4.2-1: Simple data types
|
Type Name |
Type Definition |
Description |
Applicability |
5.4.3.4.3 Enumeration: SubscribedEvent
The enumeration SubscribedEvent represents the type of UP path management events for which the AF requests to be notified. It shall comply with the provisions defined in table 5.4.3.4.3-1.
Table 5.4.3.4.3-1: Enumeration SubscribedEvent
|
Enumeration value |
Description |
|
UP_PATH_CHANGE |
The AF requests to be notified when the UP path changes for the PDU session. |
5.4.3.4.4 Enumeration: AfResultStatus
The enumeration AfResultStatus represents the status of application handling result. It shall comply with the provisions defined in table 5.4.3.4.4-1.
Table 5.4.3.4.4-1: Enumeration AfResultStatus
|
Enumeration value |
Description |
|
SUCCESS |
The application layer is ready or the relocation is completed. |
|
TEMP_CONGESTION |
The application relocation fails due to temporary congestion. |
|
RELOC_NO_ALLOWED |
The application relocation fails because application relocation is not allowed. |
|
OTHER |
The application relocation fails due to other reason. |
5.4.4 Used Features
The table below defines the features applicable to the TrafficInfluence API. Those features are negotiated as described in clause 5.2.7 of 3GPP TS 29.122 [4].
Table 5.4.4-1: Features used by TrafficInfluence API
|
Feature number |
Feature Name |
Description |
|
1 |
Notification_websocket |
The delivery of notifications over Websocket is supported as described in 3GPP TS 29.122 [4]. This feature requires that the Notification_test_event feature is also supported. |
|
2 |
Notification_test_event |
The testing of notification connection is supported as described in 3GPP TS 29.122 [4]. |
|
3 |
URLLC |
This feature indicates support of Ultra Reliable Low Latency Communication (URLLC) requirements (i.e. AF application relocation acknowledgement and UE address(es) preservation). |
|
4 |
MacAddressRange |
Indicates the support of a set of MAC addresses with a specific range in the traffic filter. |
|
5 |
AF_latency |
This feature indicates support for Edge relocation considering user plane latency. |
|
6 |
EASDiscovery |
This feature indicates the support of EAS (re)discovery. |
|
7 |
EASIPreplacement |
This feature indicates the support of provisioning of EAS IP replacement info. |
|
8 |
ExposureToEAS |
This feature indicates support for the indication provided by the AF of direct event notification of QoS monitoring events from the UPF to the Local NEF or the AF in 5GC. |
|
9 |
SimultConnectivity |
This feature indicates support of temporary simultaneous connectivity over source and target PSA at edge relocation. |
|
10 |
ULBuffering |
This feature indicates support for Uplink buffering indication for edge relocation. |
|
11 |
EDGEAPP |
This feature controls the support of EDGE applications related functionalities (e.g. support the provisioning of event reporting requirements). |
|
Feature: A short name that can be used to refer to the bit and to the feature, e.g. "Notification". Description: A clear textual description of the feature. |
||
5.4.5 Error handling
5.4.5.1 General
HTTP error handling shall be supported as specified in clause 5.2.6 of 3GPP TS 29.122 [4].
In addition, the requirements in the following clauses shall apply.
5.4.5.2 Protocol Errors
In this Release of the specification, there are no additional protocol errors applicable for the TrafficInfluence API.
5.4.5.3 Application Errors
The application errors defined for TrafficInfluence API are listed in table 5.4.5.3-1.
Table 5.4.5.3-1: Application errors
|
Application Error |
HTTP status code |
Description |
Applicability |