APIs Device to Cloud One M2 M SUB - Subscription

The subscription resource (resourceType=23) contains subscription information for its subscribed-to resource (usually the parent resource of the subscription). A subscription to a resource allows an entity in the oneM2M architecture to be notified about changes of the subscribed-to resource. The subscription resource shall represent a subscription to a subscribed-to resource. In order to establish a subscription, a subscription resource shall be created as a child resource of the subscribed-to resource. The subscription child resource contains information about the exact scope of the subscription and targets to be notified.

For example, a flexContainer resource having a subscription resource as a child resource shall result in notification(s) of target(s) configured in the subscription resource when changes to the parent flexContainer resource matching with notification event criteria described by the subscription resource occur.

In general, an Originator/client shall be able to create a resource of subscription resource type when the Originator has RETRIEVE privilege to the subscribed-to resource. The Originator which creates a subscription resource becomes the resource subscriber.

A subscription resource can be configured to implement a blocking “UPDATE” to a resource or attributes of a resource whereby a notification is sent to the notification target to respond with the result of the “UPDATE” request.

Each subscription may include notification policies that specify which, when, and how notifications are sent.

When a subscription is created, a “verification” request is send to each of the specified notifiationURI’s. If any of these verification requests is answered with a negative response, then the creation of the subscription resource fails.

A subscription resource shall be deleted when the parent subscribed-to resource is deleted. When a subscription resource is deleted, a Notify request shall be sent to the target indicated by the attribute subscriberURI if it is present in the subscription. The notificaion’s subscriptionDeletion attribute is set to True.

Universal and common attributes Copied!

Mode: RW = Read/Write, RO = Read Only, WO = Write Once

Resource specific attributes Copied!

Mode: RW = Read/Write, RO = Read Only, WO = Write Once

Request Optionality: NP = not provisioned, O = optional, M = Mandatory

Attributes: enc (eventNotificationCriteria) Copied!

This attribute (notification policy) indicates the event criteria for which a notification is to be generated. When no eventNotificationCriteria attribute is present in a subscription resource, the Hosting CSE shall trigger notifications for this subscription when any of the attributes of the subscribed-to resource is modified.

Attributes: nu (notificationURI) Copied!

This attribute shall be configured as a list consisting of one or more targets that the Hosting CSE shall send notifications to. A target shall be formatted as a oneM2M compliant Resource-ID or as an identifier compliant with a oneM2M supported protocol binding (e.g. http, coap, mqtt).

If a target is formatted as a oneM2M compliant Resource-ID, then the target shall be formatted as a structured or unstructured CSE-Relative-Resource-ID, SP-Relative-Resource-ID, and/or Absolute-Resource-ID of an AE or CSEBase resource. A Hosting CSE shall use this information to determine proper pointOfAccess, requestReqchability and/or pollingChannel information needed to send a notification to the target. The following is an example.

• /CSE0001/AE0001

For a target that is formatted as an identifier compliant with a oneM2M supported protocol binding, the details of this format are defined by the respective oneM2M protocol specification. The following is an example of an HTTP URI compliant with oneM2M HTTP protocol binding.

• https://172.25.30.25:7000/notification/handler

For a subscription to a fanoutpoint resource, if subscription resource in request contains a notificationForwardingURI, then the group hosting CSE shall configure the notificationURI of the fanout subscription request with an address specified by the Group Hosting CSE that can be used by the Group Hosting CSE to receive aggregated notifications.

A notification serialization type may be appended to each notification target configured in this list. The Hosting CSE shall serialize notifications and send it to a notification target based on this serialization type indicator. Possible serialization types are defined in the TS-0004 [3] (e.g. XML, JSON or CBOR). If a notification serialization type is not appended to a notification target, a default shall apply based on the Hosting CSE local policy. The syntax for appending a serialization type to a notification target shall use the “?” delimiter character as shown in the below examples.

• http://mydomain/notificationHandler?ct=json
• CSE02/base/ae2?ct=xml

Attribute: su (subscriberURI) Copied!

This attribute shall be configured with the target of the subscriber. The target is used by the Hosting CSE to determine where to send a notification when the subscription is deleted. A target shall be formatted as a oneM2M compliant Resource-ID or as an identifier compliant with one of the oneM2M supported protocol bindings (the detailed format of which are defined by each respective oneM2M protocol binding specification).

Default and allowed values of notificationContentType Copied!

JSON representation example Copied!

The following shows a reduced (leaving out, for example, the specification of acpi) example of a subscription resource.

The following JSON structure shows a couple of aspects:

-The eventNotificationCriteria (enc/net) is set to “Updates of the subscribed resource” (Typ A). This means that every time the parent resource is updated a Notification request is send to the receivers that are specified in the notificationURI attribute.

• The notificationContentType (nct) is set to “all attributes”, which is the default
• The list of notificationURI (nu) has a single reference. This one is not a direct URL but a reference to a oneM2M resource that will provide one or more URI’s in it’s poa attribute. But the nu attribute may also contain one or more direct URL’s.
• The optional subscriberURI (su) in this example does provide a direct URL, though it also may contain a similar reference as the notificationURI attribute.

{
    "m2m:sub": {
        "ct": "20200604T124129,747687",
        "enc": {
            "net": [
                1
            ]
        },
        "et": "20210604T124129,747727",
        "lt": "20200604T124129,747687",
        "nct": 1,
        "nu": [
            "cse-in/MyAe2"
        ],
        "pi": "CptYsTQniov",
        "ri": "sub2314301238682681243",
        "rn": "MySubscriptionResource",
        "st": 0,
        "su": "http://example.com/notification",
        "ty": 23
    }
}

Creating a subscription Copied!

Creating a subscription resource directly under the CSEBase resource in order to monitor all new and deleted resources (“enc/net: [ 3, 4 ]”) directly under the CSEBase :

POST {{API_URL}}/device-management-orchestrator/v3/{{TENANT}} HTTP/2
Accept: application/vnd.onem2m-res+json
Content-Length: 147
Content-Type: application/vnd.onem2m-res+json;ty=23
X-M2M-Origin: CAdmin
X-M2M-RI: 1234
X-M2M-RVI: 3
 
{
    "m2m:sub": {
        "enc": {
            "net": [
                3, 4
            ]
        },
        "nct": 1,
        "nu": [
            "http://127.0.0.1:9999/"
        ],
        "rn": "MySubscriptionResource",
        "su": "http://127.0.0.1:9999/"
    }
}

This first results in the following verification notification request to the notification server running aa (for this example) 127.0.0.1:9999 :

Accept: */*
Content-Type: application/json
X-M2M-Origin: /id-in
X-M2M-RI: 4363191154431212110
X-M2M-RVI: 3
Content-Length: 82
 
{
    "m2m:sgn": {
        "vrq": true,
        "sur": "/id-in/sub4330031175576407550",
        "cr": "CAdmin"
    }
}