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
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.
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
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.