Content for TS 29.501 Word version: 19.0.0
4.6.2 Use of Subscribe/Notify Communication
4.6.2.1 General
4.6.2.2 Management of Subscriptions
4.6.2.2.1 General
4.6.2.2.2 Creation of a Subscription
4.6.2.2.3 Modify a subscription
4.6.2.2.3.1 Modification of a Subscription Using HTTP PUT
4.6.2.2.3.2 Modification of a Subscription Using HTTP PATCH
4.6.2.2.4 Delete a subscription
4.6.2.3 Notifications
4.6.2.4 Special provisions to support the seamless change of AMF as NF service consumer
...
...
4.6.2 Use of Subscribe/Notify Communication p. 27
4.6.2.1 General p. 27
Subscribe/Notify communication between 5GC NFs can be used to keep involved NFs (consumers of a service) informed of data changes or events that occur at another NF (producer of the service). A notification is a message that contains information about the event.
Service consumer NFs (clients) need to subscribe to notifications at the service provider NF (server). This either happens explicitly by means of creating a new subscription resource (see clause 4.6.2.2), or implicitly by updating a relevant resource.
Service consumer NFs can in principle explicitly or implicitly subscribe to be notified about data change to any type of resource of any resource archetype (Document, Store or Collection). It is up to the API to define the resources that support subscriptions.
When the change/event occurs at the service producer NF, notifications (see clause 4.6.2.3) are sent from the service producer NF to the service consumer NFs. This communication initiated by the service producer to the service consumers requires that the service consumer NF (client) takes the role of an HTTP server and the service producer NF (server) takes the role of an HTTP client.
During the explicit subscription the service consumer NF (client) provides a callback URI and possibly additional filter criteria to the service producer NF (server). When the data-change/event occurs that matches the filter criteria in the subscription, the service producer NF (taking the role of an HTTP client) uses the provided callback URI to notify the service consumer NF (taking the role of an HTTP server) about the change.
4.6.2.2 Management of Subscriptions p. 27
4.6.2.2.1 General p. 27
The HTTP method to create a subscription shall be POST. The HTTP method to modify a subscription shall be PUT or PATCH. The HTTP method to delete a subscription (i.e. to unsubscribe) shall be DELETE (see RFC 9110).
Subscriptions may be implicit, i.e. exist without being explicitly created by a dedicated subscribe operation.
Two types of implicit subscriptions exist:
- The subscription is implied by an explicit operation different from the subscribe operation, which does not use the GET method. The subscription implied by the explicit operation and the corresponding notification shall be part of the same service.
- The subscription exists without any explicit operation.
4.6.2.2.2 Creation of a Subscription p. 27
Figure 4.6.2.2.2-1 illustrates explicit creation of a subscription.
The parent resource (collection of subscriptions) is identified by the request URI.
The data structure in the content of the POST request shall contain a callback URI, and may contain additional criteria to filter the set of events that trigger a notification. The request may contain an expiry time, suggested by the NF Service Consumer as a hint, representing the time up to which the subscription is desired to be kept active and the time after which the subscribed event shall stop generating notifications. Absence of a suggested expiry time from the request indicates that the subscription is suggested to be unlimited in time until explicitly terminated by the service consumer.
On success, "201 Created" shall be returned, the content of the POST response shall contain a representation of the created subscription, and the "Location" header shall contain the URI of the created resource. The created resource shall be served by the same NF (service) instance that received the service request, unless the 5GC SBI API specifications explicitly specified that in specific use cases the created resource may be served by another NF (service) instance. If in such specific use cases the resource is created in a different NF (service) instance, the identifier of the serving NF (service) instance shall be included in the response message.
If the HTTP scheme used in the returned URI is "https", then the authority of the URI included in the Location header shall be an FQDN, and not an IP address.
The response based on operator policies and taking into account the expiry time included in the request or the absence of an expiry time from the request, may contain a confirmed expiry time (i.e. a future timestamp), as determined by the NF Service Producer, after which the subscription becomes invalid. Absence of a confirmed expiry time from the response indicates that the subscription is confirmed to be unlimited in time until explicitly terminated by the service consumer. The confirmed expiry time should be less than or equal to the suggested expiry time (if any). If the suggested expiry time is present in the request, the confirmed expiry time should not be absent from the response. Once the subscription expires, if the NF Service Consumer wants to keep receiving notifications, it shall create a new subscription in the NF Service Producer. The NF Service Producer shall not provide the same expiry time (i.e. a future timestamp) for many subscriptions in order to avoid all of them expiring and recreating the subscription at the same time.
On failure, the appropriate HTTP status code indicating the error shall be returned and appropriate additional error information should be returned in the POST response body (see clause 4.9).
4.6.2.2.3 Modify a subscription p. 28
4.6.2.2.3.1 Modification of a Subscription Using HTTP PUT p. 28
Procedures that allow a NF service consumer to update the subscription at the server by means of a complete replacement shall use the HTTP PUT method to replace the current subscription with a new representation.
Figure 4.6.2.2.3.1-1 illustrates modification a subscription using HTTP PUT.
Step 1.
On failure, the appropriate HTTP status code indicating the error shall be returned and appropriate additional error information should be returned in the PUT response body (see clause 4.8).
If the NF Service Consumer is not allowed to update the subscription information, the "403 Forbidden" HTTP status code shall be returned and appropriate additional error information should be returned in the PUT response body (see clause 4.8).
If the resource that is to be updated does not exist at the NF service producer, the "404 Not Found" HTTP status code shall be returned.
The NF Service Consumer shall send a PUT request to the resource URI representing the individual subscription. The content of the PUT request shall contain the subscription information to be replaced including the criteria to filter the set of events that trigger a notification. The request may contain an updated expiry time, suggested by the NF Service Consumer as a hint, to extend the subscription lifetime, representing the time upto which the subscription is desired to be kept active and the time after which the subscribed event shall stop generating notifications. If the request does not contain an expiry time, the NF Service Producer shall consider that the NF Service Consumer requests for an extension of the existing subscription lifetime without indicating any specific expiration time; still, the NF Service Producer shall be authoritative to set the expiry time in the subscription response according to its own policies.
Step 2.
On success, "204 No Content" without any response body or "200 OK" with a response body providing current resource representation shall be returned.
When "200 OK" is returned, the response based on operator policies and taking into account the expiry time included in the request, may contain an expiry time (i.e a future timestamp), as determined by the NF Service Producer, after which the subscription becomes invalid. If an expiry time was included in the request, then the expiry time returned in the response should be less than or equal to that value. Once the subscription expires, if the NF Service Consumer wants to keep receiving notifications, it shall create a new subscription in the NF Service Producer, as specified in clause 4.6.2.2.2. The NF Service Producer shall not provide the same expiry time (i.e. a future timestamp) for many subscriptions in order to avoid all of them expiring and recreating the subscription at the same time. If the expiry time is not included in the response, the NF Service Consumer shall consider the subscription to be valid without an expiry time.
When "204 No Content" is returned, it shall be interpreted that the NF Service Producer accepted entirely the resource representation provided by the NF Service Consumer in the request; e.g., if the request contained a proposed expiry time, a 204 response shall be interpreted as if such timestamp is accepted by the NF Service Producer as the expiration time for the subscription and, similarly, if the request did not contain a proposed expiry time, a 204 response shall be interpreted as if no expiration time is set by the NF Service Producer for the subscription.
4.6.2.2.3.2 Modification of a Subscription Using HTTP PATCH p. 29
Procedures that allow a NF service consumer to update subscription at the server by means of a partial replacement shall use the HTTP PATCH method (see RFC 5789) to modify the current subscription according to given modification instructions.
Figure 4.6.2.2.3.2-1 illustrates updating a resource using HTTP PATCH.
Step 1.
On failure, the appropriate HTTP status code indicating the error shall be returned and appropriate additional error information should be returned in the PATCH response body (see clause 4.8).
The NF Service Consumer shall send a PATCH request to the resource URI representing the individual subscription. The content of the PATCH request shall contain the modification instructions. The request may contain an expiry time (i.e. a future timestamp), requested by the NF Service Consumer, representing the time upto which the subscription is desired to be kept active and the time after which the subscribed event shall stop generating notifications.
Step 2.
On success, "204 No Content" without any response body or "200 OK" with a response body containing the modified subscription information shall be returned. When "204 No Content" is returned and if the request included an expiry time, then the requested expiry time shall be accepted by the NF Service Producer. When "200 OK" is returned and if the request included an expiry time then the response based on operator policies and taking into account the expiry time included in the request, shall contain an expiry time (i.e. a future timestamp), as determined by the NF Service Producer, after which the subscription becomes invalid. If an expiry time was included in the request, then the expiry time returned in the response should be less than or equal to that value. Once the subscription expires, if the NF Service Consumer wants to keep receiving notifications, it shall create a new subscription in the NF Service Producer, as specified in clause 4.6.2.2.2. The NF Service Producer shall not provide the same expiry time (i.e. a future timestamp) for many subscriptions in order to avoid all of them expiring and recreating the subscription at the same time.
4.6.2.2.4 Delete a subscription p. 30
Figure 4.6.2.2.4-1 illustrates explicit deletion of a subscription.
Step 1.
On failure, the appropriate HTTP status code indicating the error shall be returned in the DELETE response body (see clause 4.8).
The NF Service Consumer shall send a DELETE request to the resource URI representing the individual subscription. The request body shall be empty.
Step 2.
On success, "204 No Content" shall be returned. The response body shall be empty.
4.6.2.3 Notifications p. 31
The HTTP method for the notification that corresponds to an explicit subscription shall be POST (see RFC 9110).
Figure 4.6.2.3-1 illustrates a notification.
Step 1.
On failure, the appropriate HTTP status code indicating the error shall be returned and appropriate additional error information should be returned in the POST response body (see clause 4.8).
The callback reference provided during creation of the subscription resource, or otherwise known from implicit subscription, is used as the request URI. The callback reference for implicit subscriptions are obtained from the NRF. When an NF / NF service registers with the NRF, the default notification subscriptions along with the callback URI for receiving those notifications may be provided (see clause 6.1.6.2.3 of TS 29.510).
The content of the POST request shall contain the notification content.
The content of the notification should follow the resource definition of the subscribed resource and can for example be based on the resource definition of the GET operation, but it is up to the API to define the notification resource definition.
Each API that supports subscription to collection/store archetype resources, should specify in their semantics whether notifications should be sent by changes on the collection/store resource ONLY (i.e. creation/deletion of the main top-level resource itself, and creation/deletion of its children), or if in addition the consumer can expect to get notifications from changes on the resource representation.
Step 2.
On success, "200 OK" shall be returned if any information needs to be included in the content of the POST response; otherwise, "204 No Content" shall be returned and the content of the POST response shall be empty.
4.6.2.4 Special provisions to support the seamless change of AMF as NF service consumer p. 31
Services consumed by an AMF can be transferred seamlessly to a new AMF when the corresponding UE context is transferred to that AMF.
To support a seamless change of AMF as NF service consumer, the procedures in clause 4.6.2 are applied with the following special provisions:
- When becoming aware that a new AMF is requiring notifications related to a subscription resource, the NF service producer shall exchange the authority part of the corresponding Notification URI with the address of that new NF service consumer and shall use that URI in subsequent communication.
- Each AMF within a set of AMFs supporting seamless changes shall be prepared to receive notifications at the Notification URI constructed according to bullet 1 with the own IP address as authority part from the NF service producer, by either handling the notifications, or by replying with an HTTP "307 temporary redirect" error response pointing to new NF service consumer, or by replying with another HTTP error such as an "404 Not found".
