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.

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.
  extension	No	SubscriptionExtension object	Extended information
  subscriptions	No	Array of BatchAddSubscriptionsRequestBody objects	This parameter is mandatory when subscriptions need to be created in batches. SMN allows you to create a maximum of 50 subscriptions at a time.

  Table 1 BatchAddSubscriptionsRequestBody

  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.
  extension	No	SubscriptionExtension object	Extended subscription information

  Table 2 SubscriptionExtension

  Parameter	Mandatory	Type	Description
  header	No	Map<String,String>	This is an HTTP header field, which can be customized within the field range. The field content exists in the form of key/value pairs. When a topic is used to send messages, confirmed subscription messages carry the user-defined HTTP header. Header for subscriptions over HTTP or HTTPS. The header must meet the following requirements: key can contain letters, digits, and hyphens (-). key cannot end with a hyphen (-) nor contain consecutive hyphens (-). You can specify up to 10 key/value pairs. key must start with x- but not x-smn. Examples: x-abc-cba or x-abc. The total length of all key/value pairs cannot exceed 1,024 characters. The value is case insensitive. The key value must be unique. value must be an ASCII code. Unicode characters are not supported. Spaces are allowed.

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