11 Media Session Handling (M5) APIs

26.5123GPP5G Media Streaming (5GMS)ProtocolsRelease 17TS

11.1 General

This clause defines the Media Session Handling APIs used by the Media Session Handler to access resources exposed by the 5GMS AF at interface M5.

NOTE: While the entirety of the Media Session Handling APIs apply to downlink media streaming, only a subset is applicable to uplink media streaming. Specifically, the Consumption Reporting API is not applicable to uplink media streaming.

11.2 Service Access Information API

11.2.1 General

The Service Access Information API is used by the Media Session Handler to obtain configuration information from the 5GMS AF that enables it to use the other Media Session Handling APIs specified in clause 11.3 et seq.

11.2.2 Resource structure

The Service Access Information API is accessible through the following URL base path:

{apiRoot}/3gpp-m5/{apiVersion}/service-access-information/

The operations and the corresponding HTTP methods in Table 11.2.2-1 are supported. In each case, the sub-resource path specified in the second column shall be appended to the URL base path.

Table 11.2.2‑1: Operations supported by the Service Access Information API

Operation	Sub-resource path	Allowed HTTP method(s)	Description
Fetch Service Access Information	{provisioningSessionId}	GET	Used to acquire the Service Access Information resource for the specified Provisioning Session. The {provisioningSessionId} uniquely identifies the Service Access Information Resource and is allocated by the 5GMS AF during creation of a Provisioning Session.

11.2.3 Data model

11.2.3.1 ServiceAccessInformation resource type

The data model for the ServiceAccessInformation resource is specified in table 11.2.3.1-1 below. Different properties are present in the resource depending on the type of Provisioning Session from which the Service Access Information is derived (as indicated in the provisioningSessionType property) and this is specified in the Applicability column.

Table 11.2.3.1‑1: Definition of ServiceAccessInformation resource

Property name	Type	Cardinality	Usage	Description	Applicability
provisioningSessionId	ResourceId	1..1	RO	Unique identification of the M1 Provisioning Session.	All types
provisioningSession‌Type	Provisioning‌Session‌Type	1..1	RO	The type of Provisioning Session.	All types.
streamingAccess	Object	0..1	RO		downlink
mediaPlayerEntry	Url	0..1	RO	A document or a pointer to a document that defines a media presentation e.g. MPD for DASH content or URL to a video clip file.
eMBMS‌Service‌Announcement‌Locator	Url	0..1	RO	A pointer to a document that defines a User Service Announcement for eMBMS where the service announcement file is available.	downlink
clientConsumptionReporting‌Configuration	Object	0..1	RO		downlink
reportingInterval	DurationSec	0..1	RO	The time interval, expressed in seconds, between consumption report messages being sent by the Media Session Handler. The value shall be greater than zero. When this property is omitted, a single final report shall be sent immediately after the media streaming session has ended.
serverAddresses	Array(Url)	1..1	RO	A list of 5GMSd AF addresses (URLs) where the consumption reporting messages are sent by the Media Session Handler. See NOTE. (Opaque URL, following the 5GMS URL format.)
locationReporting	Boolean	1..1	RO	Stipulates whether the Media Session Handler is required to provide location data to the 5GMSd AF in consumption reporting messages (in case of MNO or trusted third parties).
accessReporting	Boolean	1..1	RO	Stipulates whether the Media Session Handler is required to provide consumption reporting messages to the 5GMSd AF when the access network changes during a media streaming session.
samplePercentage	Percentage	1..1	RO	The percentage of media streaming sessions that shall send consumption reports, expressed as a floating point value between 0.0 and 100.0.
dynamicPolicyInvocation‌Configuration	Object	0..1	RO		downlink, uplink
serverAddresses	Array(Url)	1..1	RO	A list of 5GMSd AF addresses (URLs) which offer the APIs for dynamic policy invocation sent by the Media Session Handler. See NOTE. (Opaque URL, following the 5GMS URL format.)
validPolicyTemplateIds	Array(ResourceId)	1..1	RO	A list of Policy Template identifiers which the 5GMS Client is authorized to use.
sdfMethods	Array(SdfMethod)	1..1	RO	A list of recommended service data flow description methods (descriptors), e.g. 5-Tuple, ToS, 2-Tuple, etc., which should be used by the Media Session Handler to describe the service data flows for the traffic to be policed.
externalReferences	Array(String)	0..1	RO	Additional identifier for this Policy Template, unique within the scope of its Provisioning Session, that can be cross-referenced with external metadata about the media streaming session. Example: "HD_Premium".
clientMetricsReporting‌Configurations	Array(Object)	0..1	RO		downlink, uplink
serverAddresses	Array(Url)	1..1	RO	A list of 5GMS AF addresses to which metrics reports shall be sent. See NOTE. (Opaque URL, following the 5GMS URL format.)
scheme	Uri	1..1	RO	The metrics reporting scheme that metrics reports shall use (see clause 4.7.5).
dataNetworkName	Dnn	0..1	RO	The DNN which shall be used when sending metrics reports. If not specified, the name of the default DN shall be used.
reportingInterval	DurationSec	0..1	RO	The time interval, expressed in seconds, between metrics reports being sent by the Media Session Handler. The value shall be greater than zero. When this property is omitted, a single final report shall be sent immediately after the media streaming session has ended.
samplePercentage	Percentage	1..1	RO	The percentage of media streaming sessions that shall report metrics, expressed as a floating point value between 0.0 and 100.0.
urlFilters	Array(String)	0..1	RO	A non-empty list of URL patterns for which metrics reporting shall be done. The format of each pattern shall be a regular expression as specified in [5]. If not specified, reporting shall be done for all sessions.
metrics	Array(String)	1..1	RO	A list of metrics which shall be reported.
networkAssistanceConfiguration	Object	0..1	RO		downlink, uplink
serverAddress	Url	1..1	RO	Address of the 5GMS AF that offers the APIs for 5GMS AF-based Network Assistance, for access by the 5GMSd Media Session Handler. See NOTE. This address shall be an opaque URL, following the 5GMS URL format.
client‌EdgeResources‌Configuration	Object	0..1	RO	Present only for Provisioning Sessions with client-driven edge computing management mode provisioned.	downlink, uplink
eligibilityCriteria	Edge‌Processing‌Eligibility‌Criteria	0..1	RO	Conditions for activating edge resources for media streaming sessions in the scope of this Service Access Information. (See clause 6.4.3.8.)
easDiscoveryTemplate	EAS‌Discovery‌Template	1..1	RO	A template for the EAS discovery filter that shall be used by the EEC to discover and select a 5GMS EAS instance to serve media streaming sessions in the scope of this Service Access Information. (See clause 11.2.3.2.)
easRelocation‌Requirements	M5EAS‌Relocation‌Requirements	0..1	RO	EAS relocation tolerance and requirements. If absent, the EEC shall assume that relocation is tolerated by all 5GMS EAS instances in the scope of this Service Access Information. (See clause 11.2.3.3.)
NOTE: In deployments where multiple instances of the 5GMSd AF expose the Media Session Handling APIs at M5, the 5G System may use a suitable mechanism (e.g. HTTP load balancing or DNS resolution) to direct requests to a suitable AF instance.

11.2.3.2 EASDiscoveryTemplate type

Table 6.4.3.10-1  Definition of EASDiscoveryTemplate type

Property name	Type	Cardinality	Description
easType	string	1..1	The type of 5GMS EAS required to support media streaming sessions in the scope o. Corresponding to EASProfile.type, as specified in clause 8.1.5.2.3 of TS 29.558 [43].
easProviderIds	array(string)	1..1	The set of acceptable EAS provider identifiers. If empty, 5GMS EAS instances of the specified easType from any provider are acceptable. Corresponding to EASProfile.provId, as specified in clause 8.1.5.2.3 of TS 29.558 [43].
easFeatures	array(string)	1..1	The required service features for the EAS to serve this session. If empty, 5GMS EAS instances of the specified easType with any feature set are acceptable. Corresponding to EASProfile.easFeats, as specified in clause 8.1.5.2.3 of TS 29.558 [43]

11.2.3.3 M5EASRelocationRequirements type

Table 11.2.3.3-1: Definition of M5EASRelocationRequirements type

Property name	Type	Cardinality	Description
tolerance	EASRelocation‌Tolerance	1..1	Indicates whether the 5GMS EAS instance tolerates relocation. (See clause 6.4.4.4.)
maxInterruptionDuration	UintegerRm	0..1	The maximum downtime (expressed in milliseconds) that an application can tolerate during EAS relocation. If the expected downtime of the application is expected to exceed this duration, relocation of the 5GMS AS EAS instance shall not be performed.

11.2.4 Operations

This clause defines the behaviour that is expected from the 5GMS AF when a Service Access Information resource is acquired by the Media Session Handler. The main operation that is performed is to look up or generate the Service Access Information corresponding to the requested Provisioning Session.

11.3 Consumption Reporting API

11.3.1 General

The Consumption Reporting API allows the Media Session Handler to report downlink media consumption to the 5GMSd AF. The API defines data models, resources and the related procedures for the creation and management of the consumption reporting procedures. This procedure is configured by the ServiceAccessInformation resource, as defined in clause 11.2.3.

11.3.2 Reporting procedure

Consumption reports shall be submitted to one of the URLs selected from the ClientConsumptionReporting‌Configuration.‌serverAddresses array of the ServiceAccessInformation resource (see clause 11.2.3). The path of the URL should conform to the following general format:

{apiRoot}/3gpp-m5/{apiVersion}/consumption-reporting/{aspId}

where {aspId} shall be substituted by the 5GMS Client with the relevant Application Service Provider identifier.

The only HTTP method supported by this endpoint is POST.

11.3.3 Report format

11.3.3.1 ConsumptionReport format

This type represents the format of consumption report instance. This structure is used by the Media Session Handler to report the consumption.

Table 11.3.3.1-1: Definition of ConsumptionReport format

Property name	Data type	Cardinality	Description
mediaPlayerEntry	string	1..1	Identifies the Media player entry. In the case of DASH, the media player entry pointer shall be the URL of the MPD.
reportingClientId	string	1..1	Identifier of the reporting client that consumed the streaming media service associated with this consumption report. If available to the Media Session Handler, a GPSI value (see clause 28.8 of TS 23.003 [7]); otherwise, a stable and globally unique string.
consumptionReportingUnits	Array(Consumption‌Reporting‌Unit)	1..1	An array of consumption reporting units.

11.3.3.2 ConsumptionReportingUnit type

This type represents a single consumption reporting unit.

Table 11.3.3.2-1: Definition of type ConsumptionReportingUnit

Property name	Data type	Cardinality	Description
mediaConsumed	string	1..1	Identifies the media consumed. In the case of DASH, the value of the Representation@id attribute shall be quoted.
mediaEndpointAddress	EndpointAddress	0..1	The IP address and port number of the endpoint used to access the media consumed. Present only if access reporting is enabled in the Consumption Reporting Configuration.
startTime	DateTime	1..1	The time when this consumption reporting unit started.
duration	DurationSec	1..1	The duration of this consumption reporting unit.
locations	Array(TypedLocation)	0..1	A time-ordered list of UE location(s) where the media was consumed during the period of this consumption reporting unit. Present only if location reporting is enabled in the Consumption Reporting Configuration (only for trusted AF). The cardinality of objects in this array is 1..N.

11.4 Metrics Reporting API

11.4.1 General

The Metrics Reporting API allows the Media Session Handler to send QoE metrics reports to the 5GMS AF. This procedure is configured by the ServiceAccessInformation resource, as defined in clause 11.2.3. Note that multiple metrics configurations can be active at the same time, each identified by a unique metricsReportingConfigurationId.

11.4.2 Reporting procedure

Metrics reports related to a specific metricsReportingConfigurationId shall be submitted to one of the URLs selected from the ClientMetricsReportingConfiguration.serverAddresses array of the ServiceAccessInformation resource (see clause 11.2.3). The path of the URL should conform to the following general format:

{apiRoot}/3gpp-m5/{apiVersion}/metrics-reporting/‌{provisioningSessionId}/‌{metricsReportingConfigurationId}

where {provisioningSessionId} shall be substituted by the 5GMS Client with the relevant Provisioning Session identifier and {metricsReportingConfigurationId} shall be substituted with the relevant Metrics Reporting Configuration identifier.

The only HTTP method supported by this endpoint is POST.

11.4.3 Report format

Metrics reports shall be submitted by the Media Session Handler in a format specified by the metrics reporting scheme in question. The Content-Type HTTP request header shall be set in accordance with the relevant metrics reporting scheme specification.

NOTE: For downlink media streaming, TS 26.247 [7] clauses 10.6.1 and 10.6.2 specify the required MIME content type and metrics report format for the 3GPP urn:‌3GPP:‌ns:‌PSS:‌DASH:‌QM10 metrics reporting scheme. For virtual reality media the report format is further extended as defined in TS 26.118 [42] clause 9.4.

In XML documents representing metrics reports for 3GP-DASH downlink media streaming services, the ReceptionReport@clientID attribute, if present and is available to the Media Session Handler, should be a GPSI value as defined by TS 23.003 [7]. Otherwise, this attribute should be represented by a stable and globally unique string.

11.5 Dynamic Policies API

11.5.1 Overview

The Dynamic Policies API allows the Media Session Handler to request a specific policy and charging treatment to be applied to a particular application data flow of a downlink or uplink media streaming session by invoking RESTful operations on the 5GMS AF at interface M5. The API defines a set of data models, resources and the related procedures for the creation and management of the dynamic policy request.

Application Identifiers, referring to one or more Packet Flow Description (PFD), may be used as alternative traffic filtering parameters for dynamic policy invocation. The 5GMSd AF shall first provision a PFD in the PFDF for one or more (external) Application IDs by sending an HTTP POST message to the NEF as specified in clause 4.4.10 of TS 29.122 [12]. The mapping between the (external) Application Identifiers and PFDs stored in the PFDF will then be pushed to or pulled from the SMF and installed in the UPF for future traffic identifications.

NOTE: The PFDF is a functionality within the NEF.

11.5.2 Resource structure

The Dynamic Policies API is accessible through the following URL base path:

{apiRoot}/3gpp-m5/{apiVersion}/dynamic-policies/

Table 11.5.2‑1 below specifies the operations and the corresponding HTTP methods that are supported by this API. The sub-resource path specified in the second column shall be appended to the URL base path.

Table 11.5.2-1: Operations supported by the Dynamic Policies API

Resource name	Sub-resource path	Allowed HTTP methods	Description
Dynamic Policies		POST	Create a new Dynamic Policy resource. If the operation succeeds, the URL of the created Dynamic Policy Instance resource shall be returned in the Location header of the response.
Dynamic Policy	{dynamicPolicyId}	GET	Read a Dynamic Policy resource.
		PUT	Replace an existing Dynamic Policy resource.
		PATCH	Modify an existing Dynamic Policy resource.
		DELETE	Delete an existing Dynamic Policy resource.

11.5.3 Data model

11.5.3.1 DynamicPolicy resource

The DynamicPolicy resource is specified in table 11.5.3.1-1 below.

Table 11.5.3.1-1: Definition of Dynamic Policy resource

Property name	Data type	Cardinality	Usage	Description
dynamicPolicyId	ResourceId	1..1	RO	Unique identifier for this Dynamic Policy.
policyTemplateId	ResourceId	1..1	C: RW R: RO U: RW	Identifies the Policy Template which should be applied to the application flow(s).
serviceDataFlowDescriptions	Array(ServiceDataFlowDescription)	1..1	C: RW R: RO U: RW	Describes the service data flows managed by this Dynamic Policy.
provisioningSessionId	ResourceId	1..1	C: RW R: RO U: RW	Uniquely identifies Provisioning Session, which is linked to the Application Service Provider.
qosSpecification	M5QoSSpecification	0..1	C: RW R: RO U: RW	Describes the network Quality of Service properties of this Dynamic Policy.
enforcementMethod	String	0..1	C: RO R: RO U: RO	Description of the Policy Enforcement Method. The parameter is set by the 5GMSd AF.
enforcementBitRate	Integer	0..1	C: RO R: RO U: RO	Description of the enforcement bit rate.

11.5.4 Operations

This clause defines the behaviour that is expected when activating a Dynamic Policy Instance. The policyTemplateId uniquely identifies the Policy Template, to which the Dynamic Policy Instance is associated. The provisioningSessionId associates the Dynamic Policy Instance to a Provisioning Session.

The Dynamic Policy resource contains a serviceDataFlowDescription property which contains the service data flow template according to TS 23.503. The ServiceDataFlowDescription shall contain one of:

– a flowDescription object (including 5-Tuples, Type of Service, Security Parameter Index, etc.).

– a domainName.

When the Media Session Handler activate a QoS-related Dynamic Policy Template, then the qosSpecifcation property shall be present and it shall contain the following properties:

– marBwDlBitRate or marBwUlBitRate, indicating the maximum requested bit rate by the Media Session Handler.

– mirBwDlBitRate or mirBwUlBitRate, indicating the minimum requested bit rate by the Media Session Handler.

– minDesBwDlBitRate or minDesBwUlBitrate, indicating the minimum bit rate desired by the Media Session Handler.

When the 5G System employs a traffic enforcement function to ensure that the traffic is complying a certain traffic policy, the Dynamic Policy resource may contain the following two properties:

– an enforcementMethod, indicating the type of enforcement method (like leaky bucket).

– an enforcementBitrate property, indicating the maximal permitted bit rate.

11.6 Network Assistance API

11.6.1 Overview

If AF-based Network Assistance is supported, then the Network Assistance API component of interface M5, as defined in the present sub-clause, is first used to provision a Network Assistance Session resource. The Network Assistance Resource can then be used to obtain bit rate recommendations and to issue delivery boost requests during the ongoing media streaming session.

11.6.2 Resource structure

The Network Assistance API is accessible via the following URL base path:

{apiRoot}/3gpp‑m5/{apiVersion}/network-assistance/

Table 11.6.2‑1 below specifies the operations and the corresponding HTTP methods that are supported by this API. In each case, the sub-resource path specified in the second column of the table shall be appended to the URL base path.

Table 11.6.2-1: Operations supported by the Network Assistance API

Operation	Sub‑resource path	Allowed HTTP method(s)	Description
Create Network Assistance Session resource		POST	Provision a new Network Assistance Session. If the operation succeeds, the URL of the created Network Assistance Session resource shall be returned in the Location header of the response.
Fetch a Network Assistance Session resource	{naSessionId}	GET	Fetch the properties of an existing Network Assistance Session.
Update a Network Assistance Session resource	{naSessionId}	PUT, PATCH	Update the properties of an existing Network Assistance Session.
Request a bit rate recommendation	{naSessionId}/recommendation	GET	Obtain a bit rate recommendation for the next recommendation window.
Request a delivery boost	{naSessionId}/boost-request	POST	Request a delivery boost for the next recommendation window.
Terminate Network Assistance Session	{naSessionId}	DELETE	Terminate a Network Assistance session.

11.6.3 Data model

11.6.3.1 NetworkAssistanceSession resource

The NetworkAssistanceSession resource is specified in Table 11.6.3.1-1 below.

Table 11.6.3.1-1: Definition of NetworkAssistanceSession resource

Property name	Type	Cardinality	Usage	Description
naSessionId	ResourceId	1..1	C: RO R: RO U: RO	Unique identifier for this Network Assistance Session.
serviceDataFlowInformation	Array(ServiceDataFlowDescription)	0..1	C: RW R: RO U: RW	Identification of the application flows for the media streaming session for which Network Assistance is to be used, e.g. 2-tuple (IP addresses) or 5-tuple (IP Addresses, protocol and ports).
policyTemplateId	ResourceId	0..1	C: RW R: RO U: RW	Identification of the policy that is in force for the media streaming session.
requestedQoS	M5QoSSpecification	0..1	C: RW R: RO U: RW	The requested QoS parameters.
recommendedQoS	M5QoSSpecification	0..1	C: RO R: RO U: RO	The QoS parameters currently recommended by the 5GMS AF.
notficationURL	Url	0..1	C: RO R: RO U: RO	A URL to the MQTT channel over which notifications are to be sent by the 5GMS AF for this session. When set, the Media Session Handler shall subscribe to this channel. The notification messages shall be in the form of the M5QoSSpecification data type.

11.6.4 Operations

The 5GMS Client uses the POST method to create a Network Assistance session with the 5GMS AF. The AF returns the Network Assistance session identifier if session setup was successful, otherwise an error code is returned without a Network Assistance session identifier.

The 5GMS Client uses the Network Assistance session resource identifier (naSessionId) provided by the AF to refer all subsequent API calls to the AF applicable to that Network Assistance session.

The 5GMS AF populates the Network Assistance session resource with the service data flow information and optionally the policy template identifier that are valid for the media streaming session for which Network Assistance operations are to be performed. The AF uses this information to execute Network Assistance operations in the 5GC.

The 5GMS Client uses the GET method with the Network Assistance Session resource identifier to retrieve a Network Assistance Session resource from the 5GMS AF. The AF returns the Network Assistance Session resource if retrieval was successful, otherwise an appropriate error code is returned without the session resource in case of failure.

The 5GMS Client uses the GET method with the sub-resource path specified in Table 11.6.2‑1 to request a bit rate recommendation from the 5GMS AF. The 5GMSd AF shall return the recommended bit rate in an HTTP response body of type M5QoSSpecification if a bit rate recommendation could be obtained, otherwise an appropriate HTTP error code shall be returned with no response body.

– For a downlink media streaming session, the recommended minimum and maximum downlink bit rates shall be indicated in the properties mirBwDlBitRate and marBwDlBitRate respectively. The 5GMSd Client shall ignore the mandatory properties related to uplink streaming, i.e. mirBwUlBitRate and marBwUlBitRate.

– For an uplink media streaming session, the recommended minimum and maximum uplink bit rates shall be indicated in the properties mirBwUlBitRate and marBwUlBitRate, respectively. The 5GMSu Client shall ignore the mandatory properties related to downlink streaming, i.e. mirBwDlBitRate and marBwDlBitRate.

If a unique recommendation is given by the 5GMS AF then this recommended bit rate shall be set in both of these properties. The optional properties minDesBwDlBitRate, minDesBwUlBitRate, desLatency and desLoss shall not be included in the response.

The 5GMS Client uses the POST method with the sub-resource path specified in Table 11.6.2‑1 to request a delivery boost from the 5GMS AF. The 5GMS AF shall respond with the OperationSuccessResponse data type indicating whether or not the delivery boost will be attempted by the network within an upcoming nominal time period.

The 5GMS Client uses the PUT or PATCH methods to replace the existing steaming session parameters with new settings. The 5GMS AF returns the NetworkAssistanceSession resource with settings resulting from the PUT or PATCH update operation.

The 5GMS Client uses the DELETE method to terminate the indicated Network Assistance session. The 5GMS AF returns an appropriate response code. If the termination was successful, then any subsequent calls referring to the terminated session will result in the error 404 (Not Found).