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, 10000 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 according 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. For a DMS subscription, the endpoint is a message queue.
  protocol	Yes	String	Subscription protocol (Different protocols indicate different types of endpoints to receive messages.) Currently, 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 a UTF-8-coded character string containing 128 bytes at most.

• 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 section Returned Value.

Error Code

See section Error Code.