Adding a Subscription¶

Description¶

API name
Subscribe
Function
Add a subscription to a specified topic. If the status of the subscription is unconfirmed, a confirmation message is sent to the subscriber. After confirming the subscription, the subscriber can receive notification messages published to the topic.
By default, 10,000 subscriptions can be added to a topic. However, in a high-concurrency scenario, which is rare, extra subscriptions may be added successfully.
The API is idempotent. If the added subscription already exists, a successful result and status code 200 are returned. Otherwise, the status code is 201.

URI¶

URI format
POST /v2/{project_id}/notifications/topics/{topic_urn}/subscriptions
Parameter description
Parameter
Mandatory
Type
Description
project_id
Yes
String
Project ID
See Obtaining a Project ID.
topic_urn
Yes
String
Unique resource ID of a topic. You can obtain it by referring to Querying Topics.

Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID See Obtaining a Project ID.
topic_urn	Yes	String	Unique resource ID of a topic. You can obtain it by referring to Querying Topics.

Request¶

Parameter description

Parameter	Mandatory	Type	Description
endpoint	Yes	String	Message endpoint Note For an HTTP subscription, the endpoint starts with http://. For an HTTPS subscription, the endpoint starts with https://. For an email subscription, the endpoint is an email address. For an SMS subscription, the endpoint is a phone number.
protocol	Yes	String	Subscription protocol (Different protocols indicate different types of endpoints to receive messages.) The following protocols are supported: email: The endpoints are email address. sms: The endpoints are phone numbers. http and https: The endpoints are URLs.
remark	No	String	Description of the subscription The remarks must be UTF-8-coded and can contain up to 128 bytes.

Parameter

Mandatory

Type

Description

endpoint

Yes

String

Message endpoint

Note

For an HTTP subscription, the endpoint starts with http://.

For an HTTPS subscription, the endpoint starts with https://.

For an email subscription, the endpoint is an email address.

For an SMS subscription, the endpoint is a phone number.

protocol

Yes

String

Subscription protocol (Different protocols indicate different types of endpoints to receive messages.)

The following protocols are supported:

email: The endpoints are email address.
sms: The endpoints are phone numbers.
http and https: The endpoints are URLs.

remark

String

Description of the subscription

The remarks must be UTF-8-coded and can contain up to 128 bytes.

Example request

POST https://{SMN_Endpoint}/v2/{project_id}/notifications/topics/urn:smn:regionId:762bdb3251034f268af0e395c53ea09b:test_topic_v1/subscriptions

{
    "protocol": "email",
    "endpoint": "xxx@xxx.com",
    "remark": "O&M"
}

Response¶

Parameter description
Parameter
Type
Description
request_id
String
Request ID, which is unique
subscription_urn
String
Resource identifier of a subscription, which is unique

Parameter	Type	Description
request_id	String	Request ID, which is unique
subscription_urn	String	Resource identifier of a subscription, which is unique

Example response

{
    "request_id": "fdbabe38ead6482b8574f82a3d1168e9",
    "subscription_urn": "urn:smn:regionId:762bdb3251034f268af0e395c53ea09b:test_topic_v1:2e778e84408e44058e6cbc6d3c377837"
}

Returned Value¶

See Returned Value.

Error Codes¶

See Error Codes.

last updated: 2024-09-07 00:17