APIs
+ +Topic Operations
+ +-
+
- Creating a Topic
+
+ - Modifying a Topic
+
+ - Deleting a Topic
+
+ - Querying Topics
+
+ - Querying Topic Details
+
+ - Querying Topic Attributes
+
+ - Modifying Topic Attributes
+
+ - Deleting a Specified Topic Attribute
+
+ - Deleting All Topic Attributes
+
+
Version Querying
+ +Listing All SMN API Versions
+Description
- API name
QueryApiSupportVersions
+ - Function
List all SMN API versions.
+
URI
- URI format
GET /
+
Request
- Request example
GET https://{SMN_Endpoint}/+
Response
- Parameter description
++ +
+Parameter
+Type
+Description
+versions
+Versions structure
+Version object list. For details, see Table 1.
++ + +
+Table 1 Versions structure Parameter
+Type
+Description
+id
+String
+Version number, for example, v2
+min_version
+String
+Minimum micro-version number. If the APIs do not support micro-versions, no information will be returned.
+status
+String
+Version status, which can be the following:
+- CURRENT: widely used version
- SUPPORTED: earlier version, which is still supported
- DEPRECATED: deprecated version, which may be deleted later
updated
+String
+Version release time, which must be UTC time. For example, the release time of v2 is 2014-06-28T12:20:21Z.
+version
+String
+Maximum micro-version number. If the APIs do not support micro-versions, no information will be returned.
+links
+Links structure array
+URL of an API. For details, see Table 2.
+ - Response example
{ + "versions": [ + { + "id": "v2", + "links": [ + { + "href": "https://127.0.0.1/v2", + "rel": "self" + } + ], + "min_version": "", + "status": "CURRENT", + "updated": "2018-09-19T00:00:00Z", + "version": "" + } + ] +}+
Returned Value
See section Returned Value.
+Error Code
See section Error Code.
+Querying the SMN API v2 Version
+Description
- API name
QueryV2ApiInfo
+ - Function
Query the SMN API v2 version information.
+
URI
- URI format
GET /{api_version}
+ - Parameter description
++
+Parameter
+Mandatory
+Type
+Description
+api_version
+Yes
+String
+Version to be queried
+NOTE:+Currently, only v2 is supported.
+
Request
- Request example
GET https://{SMN_Endpoint}/v2+
Response
- Parameter description
++ +
+Table 1 Parameter in the response Parameter
+Type
+Description
+version
+Object
+Version object
++ + +
+Table 2 Description of the version field Parameter
+Type
+Description
+id
+String
+Version number, for example, v2
+links
+Links structure array
+URL of an API. For details, see Table 3.
+min_version
+String
+Minimum micro-version number. If the APIs do not support micro-versions, no information will be returned.
+status
+String
+Version status, which can be the following:
+- CURRENT: widely used version
- SUPPORTED: earlier version which is still supported
- DEPRECATED: deprecated version which may be deleted later
updated
+String
+Version release time, which must be UTC time. For example, the release time of v2 is 2014-06-28T12:20:21Z.
+version
+String
+Maximum micro-version number. If the APIs do not support micro-versions, no information will be returned.
+ - Response example
{ + "version": + { + "id": "v2", + "links": [ + { + "href": "https://127.0.0.1/v2", + "rel": "self" + } + ], + "min_version": "", + "status": "CURRENT", + "updated": "2018-09-19T00:00:00Z", + "version": "" + } +}+
Returned Value
See section Returned Value.
+Error Code
See section Error Code.
+Creating a Topic
+Description
- API name
CreateTopic
+
- Function
Create a topic. Each user can create 3000 topics at most. In the high-concurrent scenario, a user may create a few topics more than 3000.
+The API is idempotent. It returns a successful result after creating a topic. If a topic of the same name already exists, the status code is 200. Otherwise, the status code is 201.
+
URI
- URI format
POST /v2/{project_id}/notifications/topics
+
- Parameter description
++
+Parameter
+Mandatory
+Type
+Description
+project_id
+Yes
+String
+Project ID
+ +
Request
- Parameter description
++
+Parameter
+Mandatory
+Type
+Description
+name
+Yes
+String
+Name of the topic to be created
+The topic name is a string of 1 to 255 characters. It must contain letters, digits, hyphens (-), and underscores (_), and must start with a letter or digit.
+display_name
+No
+String
+Topic display name, which is presented as the name of the email sender in email messages
+The display name cannot exceed 192 bytes.
+The value is left blank by default.
+
- Request example
POST https://{SMN_Endpoint}/v2/{project_id}/notifications/topics+{ + "name": "test_topic_v2", + "display_name": "testtest" +}+
Response
- Parameter description
++
+Parameter
+Type
+Description
+request_id
+String
+Request ID, which is unique
+topic_urn
+String
+Unique resource ID of a topic. You can obtain it based on Querying Topics.
+
- Response example
{ + "request_id": "6a63a18b8bab40ffb71ebd9cb80d0085", + "topic_urn": "urn:smn:regionId:f96188c7ccaf4ffba0c9aa149ab2bd57:test_topic_v2" +}+
Returned Value
See Returned Value.
+Error Codes
See Error Code.
+Modifying a Topic
+Description
- API name
UpdateTopic
+
- Function
Update the topic display name.
+
URI
- URI format
PUT /v2/{project_id}/notifications/topics/{topic_urn}
+
- 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 according to Querying Topics.
+
Request
- Parameter description
++
+Parameter
+Mandatory
+Type
+Description
+display_name
+No
+String
+Topic display name, which is presented as the name of the email sender in email messages
+The display name cannot exceed 192 bytes.
+ - Request example
PUT https://{SMN_Endpoint}/v2/{project_id}/notifications/topics/urn:smn:regionId:f96188c7ccaf4ffba0c9aa149ab2bd57:test_topic_v2 +{ + "display_name":"testtest222" +}+
Response
- Parameter description
++
+Parameter
+Type
+Description
+request_id
+String
+Request ID, which is unique
+ - Response example
{ + "request_id": "6a63a18b8bab40ffb71ebd9cb80d0085" +}+
Returned Value
See section Returned Value.
+Error Code
See section Error Code.
+Deleting a Topic
+Description
- API name
DeleteTopic
+
- Function
Delete a topic and its subscribers. If a topic is deleted, a pending message will fail to deliver to the topic subscribers.
+
URI
- URI format
DELETE /v2/{project_id}/notifications/topics/{topic_urn}
+
- 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 according to Querying Topics.
+
Request
DELETE https://{SMN_Endpoint}/v2/{project_id}/notifications/topics/urn:smn:regionId:f96188c7ccaf4ffba0c9aa149ab2bd57:test_topic_v2
+Response
- Parameter description
++
+Parameter
+Type
+Description
+request_id
+String
+Request ID, which is unique
+ - Response example
{ + "request_id": " 5fcba32bd2814ea39431829c22bda94b", +}+
Returned Value
See section Returned Value.
+Error Code
See section Error Code.
+Querying Topics
+Description
- API name
ListTopics
+
- Function
Query the topic list by page. The list is sorted by the topic creation time in descending order. If no topic has been created, an empty list is returned.
+
URI
- URI format
GET /v2/{project_id}/notifications/topics?offset={offset}&limit={limit}
+
- Parameter description
++
+Parameter
+Mandatory
+Type
+Description
+project_id
+Yes
+String
+Project ID
+ +offset
+No
+int
+Offset
+If the value is an integer greater than 0 but less than the number of resources, all resources after this offset will be queried. The default value is 0.
+limit
+No
+int
+- Number of resources returned on each page
- Value range: 1–100
Commonly used values are 10, 20, and 50.
+The default value is 100.
+
Request
GET https://{SMN_Endpoint}/v2/{project_id}/notifications/topics?offset=0&limit=100
+Response
- Parameter description
++ +
+Parameter
+Type
+Description
+request_id
+String
+Request ID, which is unique
+topic_count
+int
+Number of topics in your account
+NOTE:+No matter what offset and limit values you have set in the request, this parameter always returns the total number of topics.
+topics
+Topic structure array
+Topic details
+See Table 1.
++
+Table 1 Topic structure Parameter
+Type
+Description
+topic_urn
+String
+Resource identifier of a topic, which is unique
+name
+String
+Topic name
+display_name
+String
+Topic display name, which is presented as the name of the email sender in email messages
+push_policy
+Int
+Message push policy
+- 0: Failed messages will be saved in message queues.
- 1: Failed messages will be discarded.
- Response example
{ + "request_id": "70bb40bef50e4a14b116a5a527fd7432", + "topic_count": 1, + "topics": [ + { + "topic_urn": "urn:smn:regionId:8bad8a40e0f7462f8c1676e3f93a8183:test_topic_v2", + "display_name": "testtest", + "name": "test_topic_v1", + "push_policy": 0 + } + ] +}+
Returned Value
See section Returned Value.
+Error Code
See section Error Code.
+Querying Topic Details
+Description
- API name
QueryTopicDetail
+
- Function
Query the detailed information about a topic.
+
URI
- URI format
GET /v2/{project_id}/notifications/topics/{topic_urn}
+
- 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 according to Querying Topics.
+
Request
GET https://{SMN_Endpoint}/v2/{project_id}/notifications/topics/urn:smn:regionId:8bad8a40e0f7462f8c1676e3f93a8183:test_create_topic_v2
+Response
- Parameter description
++
+Parameter
+Type
+Description
+request_id
+String
+Request ID, which is unique
+name
+String
+Name of the topic
+topic_urn
+String
+Unique resource ID of a topic. You can obtain it according to Querying Topics.
+display_name
+String
+Topic display name, which is presented as the name of the email sender in email messages
+push_policy
+int
+Message pushing policy
+0 indicates that the message sending fails and the message is cached in the queue. 1 indicates that the failed message is discarded.
+create_time
+String
+Time when the topic was created
+The UTC time is in YYYY-MM-DDTHH:MM:SSZ format.
+update_time
+String
+Time when the topic was updated
+The UTC time is in YYYY-MM-DDTHH:MM:SSZ format.
+ - Response example
{ + "update_time":"2016-08-01T02:16:38Z", + "push_policy":0, + "create_time":"2016-08-01T02:16:38Z", + "name":"test_create_topic_v2", + "topic_urn":"urn:smn:regionId:8bad8a40e0f7462f8c1676e3f93a8183:test_create_topic_v2", + "display_name":"test create topic v2", + "request_id":"6837531fd3f54550927b930180a706bf" +}+
Returned Value
See section Returned Value.
+Error Code
See section Error Code.
+Querying Topic Attributes
+Description
- API name
ListTopicAttributes
+
- Function
Query the topic attribute information.
+
URI
- URI format
GET /v2/{project_id}/notifications/topics/{topic_urn}/attributes?name={name}
+
- 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 according to Querying Topics.
+name
+No
+String
+Attribute name
+Only specified attribute names are supported. For details, see section Topic Attribute List.
++
If the name parameter is not specified, all attribute values of the topic are queried. The supported attribute values are provided in section Topic Attribute List.
+
Request
GET https://{SMN_Endpoint}/v2/{project_id}/notifications/topics/urn:smn:regionId:8bad8a40e0f7462f8c1676e3f93a8183:test_create_topic_v2/attributes?name=access_policy
+Response
- Parameter description
++
+Parameter
+Type
+Description
+request_id
+String
+Request ID, which is unique
+attributes
+Map
+Attribute key-value pair
+access_policy: topic access policy
+introduction: description of a topic
+ - Response example
{ + "request_id":"6837531fd3f54550927b930180a706bf", + "attributes": { + "access_policy": "{ + "Version": "2016-09-07", + "Id": "__default_policy_ID", + "Statement": [ + { + "Sid": "__user_pub_0", + "Effect": "Allow", + "Principal": { + "CSP": [ + "urn:csp:iam::93dc1b4697ac493d9b7d089569f86b32:root" + ] + }, + "Action": ["SMN:Publish","SMN:QueryTopicDetail"], + "Resource": "urn:smn:regionId:8bad8a40e0f7462f8c1676e3f93a8183:aaa" + }, + { + "Sid": "__service_pub_0", + "Effect": "Allow", + "Principal": { + "Service": ["obs"] + }, + "Action": ["SMN:Publish","SMN:QueryTopicDetail"], + "Resource": "urn:smn:regionId:8bad8a40e0f7462f8c1676e3f93a8183:aaa" + } + ] + }" + } + }++ The value of access_policy is a JSON character string, which requires escape characters. While in the preceding example, the characters are not escaped. You need to escape them before using the policy.
+
Returned Value
See section Returned Value.
+Error Code
See section Error Code.
+Modifying Topic Attributes
+Description
- API name
UpdateTopicAttribute
+
- Function
Modify the topic attributes.
+
URI
- URI format
PUT /v2/{project_id}/notifications/topics/{topic_urn}/attributes/{name}
+
- 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 according to Querying Topics.
+name
+Yes
+String
+Attribute name
+Only specified attribute names are supported. For details, see Topic Attribute List.
+
Request
- Parameter description
++ +
+Parameter
+Mandatory
+Type
+Description
+value
+Yes
+String
+Topic attribute value
+The value cannot exceed 30 KB. For details, see Table 1.
++ +
+Table 1 Topic attribute values Name
+Description
+Restriction
+Version
+Policy specification version
+Currently, only 2016-09-07 is supported.
+Id
+Policy ID, which uniquely identifies a policy
+The value cannot be empty.
+Statement
+Statements used to configure a topic policy. Each topic policy may contain one or more statements. You can use statements to grant topic permissions to other users or cloud services.
+A policy must contain at least one statement. For details about elements in a statement, see Table 2.
++
+Table 2 Statement elements description Element
+Description
+Restriction
+Sid
+Statement ID
+The statement ID must be unique, for example, statement01 or statement02.
+Effect
+Statement effect
+The value can be Allow or Deny.
+Principal
+NotPrincipal
+- Principal: object to which the statement applies
- NotPrincipal: object to which the statement does not apply
There are currently two supported values:
+- CSP: one or more cloud users
- Service: one or more cloud services
Either the Principal or NotPrincipal element must be configured.
+- If you enter CSP, you must specify user information in the format urn:csp:iam::domainId:root. You need to obtain the domain ID of each user you specify.
- If you enter Service, you must specify the cloud service names in lower case.
Action
+NotAction
+- Action: allowed statement action
- NotAction: statement action not allowed
You can use a wildcard character to configure a set of actions, for example, SMN:Update* and SMN:Delete*. If you only enter a wildcard character (*) in a statement, all supported actions are allowed.
+
Either the Action or NotAction element must be configured.
+The following actions are supported:
+- SMN:UpdateTopic
- SMN:DeleteTopic
- SMN:QueryTopicDetail
- SMN:ListTopicAttributes
- SMN:UpdateTopicAttribute
- SMN:DeleteTopicAttributes
- SMN:DeleteTopicAttributeByName
- SMN:ListSubscriptionsByTopic
- SMN:Subscribe
- SMN:Unsubscribe
- SMN:Publish
Resource
+NotResource
+- Resource: topic to which a statement applies
- NotResource: topic to which a statement does not apply
Either the Resource or NotResource element must be configured.
+You need to enter a topic URN.
+ - Example request
PUT https://{SMN_Endpoint}/v2/{project_id}/notifications/topics/{topic_urn}/attributes/access_policy+{ + "value": "{ + \"Version\": \"2016-09-07\", + \"Id\": \"__default_policy_ID\", + \"Statement\": [ + { + \"Sid\": \"__user_pub_0\", + \"Effect\": \"Allow\", + \"Principal\": { + \"CSP\": [ + \"urn:csp:iam::{domainID}:root\" + ] + }, + \"Action\": [\"SMN:Publish\",\"SMN:QueryTopicDetail\"], + \"Resource\": \"{topic_urn}\" + }, + { + \"Sid\": \"__service_pub_0\", + \"Effect\": \"Allow\", + \"Principal\": { + \"Service\": [\"obs\"] + }, + \"Action\": [\"SMN:Publish\",\"SMN:QueryTopicDetail\"], + \"Resource\": \"{topic_urn}\" + } + ] + }" + }++ You need to replace {project_id}, {domainID}, and {topic_urn} with the actual values.
+domainID indicates the user's domain ID. To obtain it, log in to the SMN console, click My Credential in the username drop-down list on the upper right.
+
Response
- Parameter description
++
+Parameter
+Type
+Description
+request_id
+String
+Request ID, which is unique
+ - Example response
{ + "request_id":"6837531fd3f54550927b930180a706bf" +}+
Returned Value
See Returned Value.
+Error Code
See Error Code.
+Deleting a Specified Topic Attribute
+Description
- API name
DeleteTopicAttributeByName
+
- Function
Delete a specified topic attribute.
+
URI
- URI format
DELETE /v2/{project_id}/notifications/topics/{topic_urn}/attributes/{name}
+
- 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 according to Querying Topics.
+name
+Yes
+String
+Attribute name
+Only specified attribute names are supported. For details, see section Topic Attribute List.
+
Request
DELETE https://{SMN_Endpoint}/v2/{project_id}/notifications/topics/{topic_urn}/attributes/access_policy
+Response
- Parameter description
++
+Parameter
+Type
+Description
+request_id
+String
+Request ID, which is unique
+ - Example response
{ + "request_id":"6837531fd3f54550927b930180a706bf" +}+
Returned Value
See Returned Value.
+Error Code
See Error Code.
+Deleting All Topic Attributes
+Description
- API name
DeleteTopicAttributes
+
- Function
Delete all topic attributes.
+
URI
- URI format
DELETE /v2/{project_id}/notifications/topics/{topic_urn}/attributes
+
- 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 according to Querying Topics.
+
Request
DELETE https://{SMN_Endpoint}/v2/{project_id}/notifications/topics/{topic_urn}/attributes
+Response
- Parameter description
++
+Parameter
+Type
+Description
+request_id
+String
+Request ID, which is unique
+ - Example response
{ + "request_id":"6837531fd3f54550927b930180a706bf" +}+
Returned Value
See section Returned Value.
+Error Code
See section Error Code.
+Subscription Operations
+ +-
+
- Querying Subscriptions
+
+ - Querying Subscriptions of a Specified Topic
+
+ - Adding a Subscription
+
+ - Deleting a Subscription
+
+
Querying Subscriptions
+Description
- API name
ListSubscriptions
+
- Function
Query the list of all subscriptions by page. The list is sorted by the subscription adding time in ascending order. If no subscription has been added, an empty list is returned.
+
URI
- URI format
GET /v2/{project_id}/notifications/subscriptions?offset={offset}&limit={limit}
+ - Parameter description
++
+Parameter
+Mandatory
+Type
+Description
+project_id
+Yes
+String
+Project ID
+ +offset
+No
+int
+Offset
+If the value is an integer greater than 0 but less than the number of resources, all resources after this offset will be queried. The default value is 0.
+limit
+No
+int
+- Value range: 1–100
Commonly used values are 10, 20, and 50.
+ - Number of resources returned on each page
The default value is 100.
+ - Value range: 1–100
Request
GET https://{SMN_Endpoint}/v2/{project_id}/notifications/subscriptions?offset=0&limit=2
+Response
- Parameter description
++ +
+Parameter
+Type
+Description
+request_id
+String
+Request ID, which is unique
+subscription_count
+int
+Number of subscriptions
+subscriptions
+Subscription structure array
+See Table 1.
++
+Table 1 Subscription structure Parameter
+Type
+Description
+topic_urn
+String
+Resource identifier of a topic, which is unique
+protocol
+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.
subscription_urn
+String
+Resource identifier of a subscription, which is unique
+owner
+String
+Project ID of the topic creator
+endpoint
+String
+Message receiving endpoint
+remark
+String
+Remarks
+status
+Int
+Subscription status
+- 0: unconfirmed
- 1: confirmed
- 3: canceled
- Example response
{ + "request_id": "4650b14bf221492fb819c231d167e6fe", + "subscription_count": 2, + "subscriptions": [ + { + "topic_urn": "urn:smn:regionId:762bdb3251034f268af0e395c53ea09b:test_topic_v1", + "protocol": "sms", + "subscription_urn": "urn:smn:regionId:762bdb3251034f268af0e395c53ea09b:test_topic_v1:2e778e84408e44058e6cbc6d3c377837", + "owner": "762bdb3251034f268af0e395c53ea09b", + "endpoint": "xxxxxxxxxxx", + "remark": "", + "status": 0 + }, + { + "topic_urn": "urn:smn:regionId:762bdb3251034f268af0e395c53ea09b:test_topic_v1", + "protocol": "email", + "subscription_urn": "urn:smn:regionId:762bdb3251034f268af0e395c53ea09b:test_topic_v1:a2d52a9f5c3b47f48c3fafb177a58796", + "owner": "762bdb3251034f268af0e395c53ea09b", + "endpoint": "xx@xx.com", + "remark": "", + "status": 0 + } +] +}+
Returned Value
See section Returned Value.
+Error Code
See section Error Code.
+Querying Subscriptions of a Specified Topic
+Description
- API name
ListSubscriptionsByTopic
+
- Function
Query the list of subscriptions of a specified topic by page. The list is sorted by the subscription adding time in ascending order. If no subscription has been added to the topic, an empty list is returned.
+
URI
- URI format
GET /v2/{project_id}/notifications/topics/{topic_urn}/subscriptions?offset={offset}&limit={limit}
+
- 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 according to Querying Topics.
+offset
+No
+int
+Offset
+If the value is an integer greater than 0 but less than the number of resources, all resources after this offset will be queried. The default value is 0.
+limit
+No
+int
+- Number of resources returned on each page
- Value range: 1–100
Commonly used values are 10, 20, and 50.
+The default value is 100.
+
Request
GET https://{SMN_Endpoint}/v2/{project_id}/notifications/topics/urn:smn:regionId:762bdb3251034f268af0e395c53ea09b:test_topic_v1/subscriptions?offset=0&limit=100
+Response
- Parameter description
++ +
+Parameter
+Type
+Description
+request_id
+String
+Request ID, which is unique
+subscription_count
+int
+Number of subscriptions
+subscriptions
+Subscription structure array
+For details, see Table 1.
++
+Table 1 Subscription structure Parameter
+Type
+Description
+topic_urn
+String
+Resource identifier of a topic, which is unique
+protocol
+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.
subscription_urn
+String
+Resource identifier of a subscription, which is unique
+owner
+String
+Project ID of the topic creator
+endpoint
+String
+Message receiving endpoint
+remark
+String
+Remarks
+status
+Int
+Subscription status
+- 0: unconfirmed
- 1: confirmed
- 3: canceled
- Example response
{ + "request_id": "4650b14bf221492fb819c231d167e6fe", + "subscription_count": 2, + "subscriptions": [ + { + "topic_urn": "urn:smn:regionId:762bdb3251034f268af0e395c53ea09b:test_topic_v1", + "protocol": "sms", + "subscription_urn": "urn:smn:regionId:762bdb3251034f268af0e395c53ea09b:test_topic_v1:2e778e84408e44058e6cbc6d3c377837", + "owner": "762bdb3251034f268af0e395c53ea09b", + "endpoint": "xxxxxxxxxx", + "remark": "", + "status": 0 + }, + { + "topic_urn": "urn:smn:regionId:762bdb3251034f268af0e395c53ea09b:test_topic_v1", + "protocol": "email", + "subscription_urn": "urn:smn:regionId:762bdb3251034f268af0e395c53ea09b:test_topic_v1:a2d52a9f5c3b47f48c3fafb177a58796", + "owner": "762bdb3251034f268af0e395c53ea09b", + "endpoint": "xx@xx.com", + "remark": "", + "status": 0 + } +] +}+
Returned Value
See section Returned Value.
+Error Code
See section Error Code.
+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
+ +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.
+Deleting a Subscription
+Description
- API name
Unsubscribe
+
- Function
Delete a specified subscription.
+
URI
- URI format
DELETE /v2/{project_id}/notifications/subscriptions/{subscription_urn}
+
- Parameter description
++
+Parameter
+Mandatory
+Type
+Description
+project_id
+Yes
+String
+Project ID
+ +subscription_urn
+Yes
+String
+Unique resource ID of a topic. You can obtain it according to Querying Subscriptions.
+
Request
DELETE https://{SMN_Endpoint}/v2/{project_id}/notifications/subscriptions/urn:smn:regionId:762bdb3251034f268af0e395c53ea09b:test_topic_v1:2e778e84408e44058e6cbc6d3c377837
+Response
- Parameter description
++
+Parameter
+Type
+Description
+request_id
+String
+Request ID, which is unique
+ - Response example
{ + "request_id":"f3197b274a6b473a8007eed79e716c30" +}+
Returned Value
See section Returned Value.
+Error Code
See section Error Code.
+Template Operation
+ +-
+
- Creating a Message Template
+
+ - Modifying a Message Template
+
+ - Deleting a Message Template
+
+ - Querying Message Templates
+
+ - Querying the Message Template Details
+
+
Creating a Message Template
+Description
- API name
CreateMessageTemplate
+
- Function
Create a message template for quick message sending to reduce the request data volume.
+By default, a user can create a maximum of 100 message templates. However, in a high-concurrency scenario, which is rare, extra templates may be successfully created.
+
URI
- URI format
POST /v2/{project_id}/notifications/message_template
+
- Parameter description
++
+Parameter
+Mandatory
+Type
+Description
+project_id
+Yes
+String
+Project ID
+ +
Request
- Parameter description
++
+Parameter
+Mandatory
+Type
+Description
+message_template_name
+Yes
+String
+Template name
+The template name is a string of 1 to 64 characters. It must contain upper- or lower-case letters, digits, hyphens (-), and underscores (_), and must start with a letter or digit.
+content
+Yes
+String
+Template content, which currently supports plain text only
+The template content cannot be left blank or larger than 256 KB.
+protocol
+No
+String
+Protocol supported by the template
+Currently, the following protocols are supported:
+- default
- sms
- dms
- http and https
- Example request
POST https://{SMN_Endpoint}/v2/{project_id}/notifications/message_template+{ + "message_template_name": "confirm_message", + "protocol": "https", + "content": "(1/2)You are invited to subscribe to topic({topic_id}). Click the following URL to confirm subscription:(If you do not want to subscribe to this topic, ignore this message.)" +}+
Response
- Parameter description
++
+Parameter
+Type
+Description
+request_id
+String
+Request ID, which is unique
+message_template_id
+String
+Resource identifier of the template, which is unique
+
- Example response
{ + "request_id":"ca03efa691624d8eb2dfeba01a1bcf6e", + "message_template_id":"57ba8dcecda844878c5dd5815b65d10f" +}+
Returned Value
See section Returned Value.
+Error Code
See section Error Code.
+Modifying a Message Template
+Description
- API name
UpdateMessageTemplate
+
- Function
Modify the message template content.
+
URI
- URI format
PUT /v2/{project_id}/notifications/message_template/{message_template_id}
+
- Parameter description
++
+Parameter
+Mandatory
+Type
+Description
+project_id
+Yes
+String
+Project ID
+ +message_template_id
+Yes
+String
+Unique resource ID of a topic. You can obtain it according to Querying Message Templates.
+
Request
- Parameter description
++
+Parameter
+Mandatory
+Type
+Description
+content
+Yes
+String
+Template content, which currently supports plain text only
+The template content cannot be left blank or larger than 256 KB.
+ - Request example
PUT https://{SMN_Endpoint}/v2/{project_id}/notifications/message_template/b3ffa2cdda574168826316f0628f774f+{ + "content": "(1/22)You are invited to subscribe to topic({topic_id_id1}). Click the following URL to confirm subscription:(If you do not want to subscribe to this topic, ignore this message.)" +}+
Response
- Parameter description
++
+Parameter
+Type
+Description
+request_id
+String
+Request ID, which is unique
+ - Response example
{ + "request_id": "5fcba32bd2814ea39431829c22bda94b" +}+
Returned Value
See section Returned Value.
+Error Code
See section Error Code.
+Deleting a Message Template
+Description
- API name
DeleteMessageTemplate
+
- Function
Delete a message template. After you delete the template, you cannot use it to publish messages any more.
+
URI
- URI format
DELETE /v2/{project_id}/notifications/message_template/{message_template_id}
+
- Parameter description
++
+Parameter
+Mandatory
+Type
+Description
+project_id
+Yes
+String
+Project ID
+ +message_template_id
+Yes
+String
+Unique resource ID of a topic. You can obtain it according to Querying Message Templates.
+
Request
DELETE https://{SMN_Endpoint}/v2/{project_id}/notifications/message_template/b3ffa2cdda574168826316f0628f774e
+Response
- Parameter description
++
+Parameter
+Type
+Description
+request_id
+String
+Request ID, which is unique
+ - Response example
{ + "request_id": " 5fcba32bd2814ea39431829c22bda94b" +}+
Returned Value
See section Returned Value.
+Error Code
See section Error Code.
+Querying Message Templates
+Description
- API name
ListMessageTemplates
+
- Function
Query the template list by page. The list is sorted by the template creation time in ascending order. If no template has been created, an empty list is returned. The parameters message_template_name and protocol are added.
+
The template list provides only brief information. To query the template details, see section Querying the Message Template Details.
+URI
- URI format
GET /v2/{project_id}/notifications/message_template?offset={offset}&limit={limit}&message_template_name={message_template_name}&protocol={protocol}
+
- Parameter description
++
+Parameter
+Mandatory
+Type
+Description
+project_id
+Yes
+String
+Project ID
+ +offset
+No
+int
+Offset
+If the value is an integer greater than 0 but less than the number of resources, all resources after this offset will be queried. The default value is 0.
+limit
+No
+int
+- Number of resources returned on each page
- Value range: 1–100
Commonly used values are 10, 20, and 50.
+The default value is 100.
+
message_template_name
+No
+String
+Template name
+The template name is a string of 1 to 64 characters. It must contain upper- or lower-case letters, digits, hyphens (-), and underscores (_), and must start with a letter or digit.
+protocol
+No
+String
+Protocol supported by the template
+Currently, the following protocols are supported:
+- default
- sms
- dms
- http and https
Request
GET https://{SMN_Endpoint}/v2/{project_id}/notifications/message_template?offset=0&limit=2&message_template_name=test1&protocol=email
+Response
- Parameter description
++ +
+Parameter
+Type
+Description
+request_id
+String
+Request ID, which is unique
+message_template_count
+int
+Number of returned templates
+message_templates
+Message template structure array
+For details, see Table 1.
++
+Table 1 Message template structure Parameter
+Type
+Description
+message_template_id
+String
+Template ID
+message_template_name
+String
+Template name
+protocol
+String
+Protocol supported by the template
+Currently, the following protocols are supported:
+- default
- sms
- dms
- http and https
tag_names
+String array
+Template variable list
+create_time
+String
+Time when the template was created
+The UTC time is in YYYY-MM-DDTHH:MM:SSZ format.
+update_time
+String
+Last time when the template was updated
+The UTC time is in YYYY-MM-DDTHH:MM:SSZ format.
+ - Response example
{ + "message_templates":[ + { + "message_template_name":"confirm_message", + "update_time":"2016-08-02T08:22:18Z", + "create_time":"2016-08-02T08:22:18Z", + "tag_names":[ + "topic_urn" + ], + "message_template_id":"79227dfdf88d4e52a1820ca1eb411635" + }, + { + "message_template_name":"confirm_message", + "protocol":"email", + "update_time":"2016-08-02T08:22:19Z", + "create_time":"2016-08-02T08:22:19Z", + "tag_names":[ + "topic_id" + ], + "message_template_id":"ecf63465804a4b10a0573980be78ffba" + }, + { + "message_template_name":"confirm_message", + "protocol":"https", + "update_time":"2016-08-02T08:22:20Z", + "create_time":"2016-08-02T08:22:20Z", + "tag_names":[ + "topic_id" + ], + "message_template_id":"57ba8dcecda844878c5dd5815b65d10f" + } + ], + "request_id":"ce7f2f7343224f8c9597b05a9a0bcc2e", + "message_template_count":3 +}+
Returned Value
See section Returned Value.
+Error Code
See section Error Code.
+Querying the Message Template Details
+Description
- API name
QueryMessageTemplateDetail
+
- Function
Query the template details, including the template content.
+
URI
- URI format
GET /v2/{project_id}/notifications/message_template/{message_template_id}
+
- Parameter description
++
+Parameter
+Mandatory
+Type
+Description
+project_id
+Yes
+String
+Project ID
+ +message_template_id
+Yes
+String
+Unique resource ID of a topic. You can obtain it according to Querying Message Templates.
+
Request
GET https://{SMN_Endpoint}/v2/{project_id}/notifications/message_template/57ba8dcecda844878c5dd5815b65d10f
+Response
- Parameter description
++
+Parameter
+Type
+Description
+message_template_id
+String
+Template ID
+message_template_name
+String
+Template name
+protocol
+String
+Protocol supported by the template
+Currently, the following protocols are supported:
+- default
- sms
- dms
- http and https
tag_names
+String
+Variable list
+The variable name will be quoted in braces ({}) in the template. When you use a template to send messages, you can replace the variable with any content.
+create_time
+String
+Time when the template was created
+The UTC time is in YYYY-MM-DDTHH:MM:SSZ format.
+update_time
+String
+Last time when the template was updated
+The UTC time is in YYYY-MM-DDTHH:MM:SSZ format.
+content
+String
+Template content
+request_id
+String
+Request ID, which is unique
+ - Example response
{ + "message_template_name": "confirm_message", + "protocol": "https", + "update_time": "2016-08-02T08:22:25Z", + "create_time": "2016-08-02T08:22:20Z", + "request_id":"ba79ca8f794f4f50985ce7b98a401b47", + "tag_names": [ + "topic_id_id4" + ], + "content": "(1/24)You are invited to subscribe to topic({topic_id_id4}). Click the following URL to confirm subscription:(If you do not want to subscribe to this topic, ignore this message.)", + "message_template_id": "57ba8dcecda844878c5dd5815b65d10f" +}+
Returned Value
See section Returned Value.
+Error Code
See section Error Code.
+Message Publishing
+ +-
+
- Publishing Messages in the Text Format
+
+ - Publishing Messages Using a Message Structure
+
+ - Publishing Messages Using a Template
+
+
Publishing Messages in the Text Format
+Description
- API name
Publish
+
- Function
Publish messages in the text format to a topic. After the message ID is returned, the message has been saved and is to be pushed to the subscribers of the topic.
+
URI
- URI format
POST /v2/{project_id}/notifications/topics/{topic_urn}/publish
+
- 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 according to Querying Topics.
+
Request
- Parameter description
++
+Parameter
+Mandatory
+Type
+Description
+subject
+Yes
+String
+Message subject, which is used as the email subject when you publish email messages. The value cannot exceed 512 characters.
+message
+Yes
+String
+Message content
+The message content is a UTF-8-coded character string of no more than 256 KB. For SMS subscribers, if the content exceeds 256 bytes, the system will divide it into multiple messages and send only the first two.
+ +time_to_live
+No
+String
+Time-to-live (TTL) of a message, specifically, the maximum time period for retaining the message in the system
+If the period expires, the system will discard the message. The time period is measured in seconds, and the default TTL is 3600s (one hour).
+The value must be a positive integer less than or equal to 604,800 (3600 x 24 x 7).
+ - Example request
POST https://{SMN_Endpoint}/v2/{project_id}/notifications/topics/urn:smn:regionId: f96188c7ccaf4ffba0c9aa149ab2bd57:test_create_topic_v2/publish+{ + "subject": "test message v2", + "message": "Message test message v2", + "time_to_live":"3600" +}+
Response
- Parameter description
++
+Parameter
+Type
+Description
+request_id
+String
+Request ID, which is unique
+message_id
+String
+Message ID, which is unique
+ - Example response
{ + "message_id": "bf94b63a5dfb475994d3ac34664e24f2", + "request_id": "9974c07f6d554a6d827956acbeb4be5f" +}+
Returned Value
See section Returned Value.
+Error Code
See section Error Code.
+Publishing Messages Using a Message Structure
+Description
- API name
Publish
+
- Function
Use the message structure to publish a message to the topic. After the message ID is returned, the message has been saved and is to be pushed to the subscribers of the topic. This API allows you to send different message content to different types of subscribers.
+
URI
- URI format
POST /v2/{project_id}/notifications/topics/{topic_urn}/publish
+
- 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 according to Querying Topics.
+
Request
- Parameter description
++
+Parameter
+Mandatory
+Type
+Description
+subject
+Yes
+String
+Message subject, which is presented as the email subject when SMN sends massages to email subscribers
+The message subject cannot exceed 512 bytes.
+message_structure
+Yes
+String
+Message structure, which contains JSON character strings. Specify protocols in the structure, which can be http, https, email, dms, and sms.
+The default protocol is mandatory. If the system fails to match any other protocols, the default message is sent.
+NOTE:+Three message formats are supported:
+- message
- message_structure
- message_template_name
If the three formats are specified at the same time, they take effect in the following sequence: message_structure > message_template_name > message.
+time_to_live
+No
+String
+TTL of a message, specifically, the maximum time period for retaining the message in the system
+If the period expires, the system will discard the message. The time period is measured in seconds, and the default TTL is 3600s (one hour).
+The value must be a positive integer less than or equal to 604,800 (3600 x 24 x 7).
+ - Example request
POST https://{SMN_Endpoint}/v2/{project_id}/notifications/topics/urn:smn:regionId: f96188c7ccaf4ffba0c9aa149ab2bd57:test_create_topic_v2/publish+{ + "subject": "test message v2", + "time_to_live":"3600", + "message_structure": "{"default":"test v2 default", "email":"abc"}" +}++ For example, a topic has two types of subscriptions, SMS and email. After the API is called to publish messages, the email subscriber will receive message "abc", and the SMS subscriber will receive the default message "test v2 default".
+
Response
- Parameter description
++
+Parameter
+Type
+Description
+request_id
+String
+Request ID, which is unique
+message_id
+String
+Message ID, which is unique
+ - Example response
{ + "message_id": "bf94b63a5dfb475994d3ac34664e24f2", + "request_id": "9974c07f6d554a6d827956acbeb4be5f" +}+
Returned Value
See section Returned Value.
+Error Code
See section Error Code.
+Publishing Messages Using a Template
+Description
- API name
Publish
+
- Function
Use the message template to publish a message to a topic. After the message ID is returned, the message has been saved and is to be pushed to the subscribers of the topic. This API allows you to send messages to different types of subscribers using different template protocols with the same name.
+
URI
- URI format
POST /v2/{project_id}/notifications/topics/{topic_urn}/publish
+
- 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 according to Querying Topics.
+
Request
- Parameter description
++
+Parameter
+Mandatory
+Type
+Description
+subject
+Yes
+String
+Message subject, which is presented as the email subject when SMN sends massages to email subscribers
+The message subject cannot exceed 512 bytes.
+message_template_name
+Yes
+String
+Message template name, which can be obtained according to Querying Message Templates
+NOTE:+Three message formats are supported:
+- message
- message_structure
- message_template_name
If the three formats are specified at the same time, they take effect in the following sequence:
+message_structure>message_template_name>message
+tags
+Yes
+JSON key-value pair
+Variable parameters and values
+The value cannot be left blank.
+time_to_live
+No
+String
+TTL of a message, specifically, the maximum time period for retaining the message in the system
+If the period expires, the system will discard the message. The time period is measured in seconds, and the default TTL is 3600s (one hour).
+The value must be a positive integer less than or equal to 604,800 (3600 x 24 x 7).
+ - Request example
POST https://{SMN_Endpoint}/v2/{project_id}/notifications/topics/urn:smn:regionId: f96188c7ccaf4ffba0c9aa149ab2bd57:test_create_topic_v2/publish+{ + "subject": "test message template v2", + "message_template_name": "confirm_message", + "time_to_live":"3600", + "tags": { + "topic_urn": "topic_urn3331", + "topic_id": "topic_id3332" + } +}+
Response
- Parameter description
++
+Parameter
+Type
+Description
+request_id
+String
+Request ID, which is unique
+message_id
+String
+Message ID, which is unique
+ - Response example
{ + "message_id": "bf94b63a5dfb475994d3ac34664e24f2", + "request_id": "9974c07f6d554a6d827956acbeb4be5f" +}+
Returned Value
See section Returned Value.
+Error Code
See section Error Code.
+SMS Message Operations
+ +Sending a Transactional SMS Message to a Phone Number
+Description
Direct SMS messaging is not available to new users. If you want to use these APIs, go to Cloud Communications > Message&SMS.
+- API name
SmsPublish
+ - Function
Send a transactional SMS message to a specified phone number, usually used for verification code or notification.
+
URI
- URI format
POST /v2/{project_id}/notifications/sms
+ - Parameter description
++
+Parameter
+Mandatory
+Type
+Description
+project_id
+Yes
+String
+Project ID
+ +
Request
- Parameter description
++
+Parameter
+Mandatory
+Type
+Description
+endpoint
+Yes
+String
+Phone number
+The phone number must be preceded by a plus sign (+) and a country code.
+message
+Yes
+String
+SMS message content
+If the content exceeds 256 bytes, the system will divide it into multiple messages, each containing 256 bytes at most and send only the first two.
+
- Example request+
POST https://{SMN_Endpoint}/v2/{project_id}/notifications/sms +{ + "endpoint": "+00111****1990", + "message": "SMS message test" +}+
Response
- Parameter description
++
+Parameter
+Type
+Description
+request_id
+String
+Request ID, which is unique
+message_id
+String
+Message ID, which is unique
+
- Example response
{ + "message_id": "bf94b63a5dfb475994d3ac34664e24f2", + "request_id": "9974c07f6d554a6d827956acbeb4be5f" +}+
Returned Value
See section Returned Value.
+Error Code
See section Error Code.
+Resource Tag Operations
+ +-
+
- Querying Resources by Tag
+
+ - Adding or Deleting Resource Tags in Batches
+
+ - Adding a Resource Tag
+
+ - Deleting a Resource Tag
+
+ - Querying Resource Tags
+
+ - Querying Tags in a Specified Project
+
+
Querying Resources by Tag
+Description
- API name
GetResourceInstances
+
- Function
Query SMN resources by tag.
+
URI
- URI format
POST /v2/{project_id}/{resource_type}/resource_instances/action
+
- Parameter description
++
+Parameter
+Mandatory
+Type
+Description
+project_id
+Yes
+String
+Project ID
+ +resource_type
+Yes
+String
+Resource type
+The value can be the following:
+smn_topic: topic
+ + +
Request
- Parameter description
++ +
+Parameter
+Mandatory
+Type
+Description
+tags
+No
+Tags structure array
+Includes specified tags. For details, see Table 1.
+NOTE:+The structure body is mandatory. A maximum of 10 tag keys are allowed in each query operation. The tag key cannot be left blank or set to the empty string. Each tag key can have up to 10 tag values. Each tag key and tag values of one key must be unique. Resources identified by different keys are in AND relationship.
+tags_any
+No
+Tags structure array
+Includes any of the specified tags. For details, see Table 1.
+NOTE:+The structure body is mandatory. A maximum of 10 tag keys are allowed in each query operation. The tag key cannot be left blank or set to the empty string. Each tag key can have up to 10 tag values. Each tag key and tag values of one key must be unique. Resources identified by different keys are in OR relationship.
+not_tags
+No
+Tags structure array
+Excludes specified tags. For details, see Table 1.
+NOTE:+The structure body is mandatory. A maximum of 10 tag keys are allowed in each query operation. The tag key cannot be left blank or set to the empty string. Each tag key can have up to 10 tag values. Each tag key and tag values of one key must be unique. Resources identified by different keys are in NAND relationship.
+not_tags_any
+No
+Tags structure array
+Excludes any of the specified tags. For details, see Table 1.
+NOTE:+The structure body is mandatory. A maximum of 10 tag keys are allowed in each query operation. The tag key cannot be left blank or set to the empty string. Each tag key can have up to 10 tag values. Each tag key and tag values of one key must be unique. Resources identified by different keys are in NOR relationship.
+limit
+No
+String
+Maximum number of resources to be queried
+- If action is set to count, this parameter does not take effect.
- If action is set to filter, this parameter takes effect. Its value ranges from 1 to 1000 (default).
offset
+No
+String
+Start location of pagination query. The query starts from the next resource of the specified location. You do not need to specify this parameter when querying resources on the first page. When you query resources on subsequent pages, set this parameter to the location returned in the response body for the previous query.
+- If action is set to count, this parameter does not take effect.
- If action is set to filter, this parameter takes effect. Its value can be 0 (default) or a positive integer.
action
+Yes
+String
+Operation to be performed. The value can be filter or count (case-sensitive).
+filter: queries resources in pages based on filter conditions.
+count: queries the total number of resources meeting filter conditions.
+matches
+No
+Match condition structure array
+Key-value pair to be matched
+The key can only be resource_name.
+The value will be exactly matched.
++
+Table 1 Tags structure Parameter
+Mandatory
+Type
+Description
+Constraint
+key
+Yes
+String
+Tag key
+A key contains 127 Unicode characters and cannot be blank.
+values
+Yes
+String list
+Value list
+Each value contains a maximum of 255 Unicode characters. If the value starts with an asterisk (*), the character string following the asterisk is fuzzy-matched. The values field cannot be missing, but can be an empty list. If it is empty, any value will be matched. The values are in OR relationship.
+ - Request example
POST https://{SMN_Endpoint}/v2/{project_id}/{resource_type}/resource_instances/action+- Request body when action is set to filter
{ + "offset": "100", + "limit": "100", + "action": "filter", + "matches":[ + { + "key": "resource_name", + "value": "resource1" + } + ], + "not_tags": [ + { + "key": "key1", + "values": ["*value1","value2"] + }, + { + "key": "key2", + "values": ["*value21","value22"] + } + ], + "tags": [ + { + "key": "key1", + "values": ["*value1","value2"] + } + ], + "tags_any": [ + { + "key": "key1", + "values": ["value1", "value2"] + } + ], + "not_tags_any": [ + { + "key": "key1", + "values": ["value1", "value2"] + } + ] +}+ - Request body when action is set to count
{ + "action": "count", + "not_tags": [ + { + "key": "key1", + "values": ["value1", "*value2"] + } + ], + "tags": [ + { + "key": "key1", + "values": ["value1", "value2"] + } + ], + "tags_any": [ + { + "key": "key1", + "values": [ "value1", "value2"] + } + ], + "not_tags_any": [ + { + "key": "key1", + "values": ["value1", "value2"] + } + ], + "matches":[ + { + "key": "resource_name", + "value": "resouurce" + } + ] +}+
- Request body when action is set to filter
Response
- Parameter description
++ +
+Parameter
+Mandatory
+Type
+Description
+resources
+Yes
+Resource structure array
+For details, see Table 2.
+total_count
+Yes
+Integer
+Total number of resources
++ +
+Table 2 Resource structure Parameter
+Mandatory
+Type
+Description
+resource_id
+Yes
+String
+Resource ID
+resource_detail
+Yes
+Object
+Resource details. Resource object used for extension. The value is left blank by default.
+For topic resources, the value of this field is {"topic_urn":"${TopicUrn}","display_name":"display name"}.
+For other resources, the value is null.
+tags
+Yes
+Resource_tag structure array
+List of queried tags. If no tag is matched, an empty array is returned. For details, see Table 3.
+resource_name
+Yes
+String
+Resource name
++
+Table 3 Resource_tag structure Parameter
+Mandatory
+Type
+Description
+Constraint
+key
+Yes
+String
+Tag key
+The key contains 36 Unicode characters at most and cannot be blank or an empty string. It can contain only digits, letters, hyphens (-), and underscores (_) and must not start or end with a space.
+value
+Yes
+String
+Tag value
+Each value contains 43 Unicode characters at most and can be an empty string. It can contain only digits, letters, hyphens (-), and underscores (_) and must not start or end with a space.
+
- Response example
Response body when action is set to filter
+{ + "resources": [ + { + "resource_detail": { + "topic_urn":"urn:smn:regionId:f96188c7ccaf4ffba0c9aa149ab2bd57:resouece1", + "display_name":"testtest" + }, + "resource_id": "cffe4fc4c9a54219b60dbaf7b586e132", + "resource_name": "resouece1", + "tags": [ + { + "key": "key1", + "value": "value1" + } + ] + } + ], + "total_count": 1000 +}+Response body when action is set to count
+{ + "total_count": 1000 +}+
Returned Value
See section Returned Value.
+Error Code
See section Error Code.
+Adding or Deleting Resource Tags in Batches
+Description
- API name
BatchCreateOrDeleteResourceTags
+ - Function
Add or delete tags for a specified resource in batches.
+You can add a maximum of 10 tags to a resource.
++ The API is idempotent. When you are to create tags, if there are duplicate keys in the request body, an error is reported.
+If a to-be-created tag has the same key as an existing tag, the tag will be created and overwrite the existing one.
+When tags are being deleted and some tags do not exist, the operation is considered successful by default. The character set of the tags will not be checked.
+
URI
- URI format
POST /v2/{project_id}/{resource_type}/{resource_id}/tags/action
+ - Parameter description
++
+Parameter
+Mandatory
+Type
+Description
+project_id
+Yes
+String
+Project ID
+ +resource_type
+Yes
+String
+Resource type
+The value can be the following:
+smn_topic: topic
+ + +resource_id
+Yes
+String
+Resource ID
+Obtain a resource ID:
+- Add X-SMN-RESOURCEID-TYPE=name in the request header and set the resource ID to the topic name.
- Call the GetResourceInstances API to obtain the resource ID.
Request
- Parameter description
++ +
+Parameter
+Mandatory
+Type
+Description
+tags
+Yes
+Resource_tag structure array
+Tag list. For details, see Table 1.
+When you delete tags, the tag structure cannot be missing, and the key cannot be left blank or be an empty string. The system does not check the character set when deleting a tag.
+action
+Yes
+String
+Operation to be performed, which can be create or delete
++
+Table 1 Resource_tag structure Parameter
+Mandatory
+Type
+Description
+Constraint
+key
+Yes
+String
+Tag key
+The key contains 36 Unicode characters at most and cannot be blank or an empty string. It can contain only digits, letters, hyphens (-), and underscores (_) and must not start or end with a space.
+value
+Yes
+String
+Tag value
+Each value contains 43 Unicode characters at most and can be an empty string. It can contain only digits, letters, hyphens (-), and underscores (_) and must not start or end with a space.
+
- Request example
POST https://{SMN_Endpoint}/v2/{project_id}/{resource_type}/{resource_id}/tags/action+
- Request bodyRequest body when action is set to create+
{ + "action": "create", + "tags": [ + { + "key": "key1", + "value": "value1" + }, + { + "key": "key", + "value": "value3" + } + ] +}+Request body when action is set to delete
+{ + "action": "delete", + "tags": [ + { + "key": "key1" + }, + { + "key": "key2", + "value": "value3" + } + ] +}+
Response
None
+Returned Value
See Returned Value.
+Error Code
See section Error Code.
+Adding a Resource Tag
+Description
- API name
CreateResourceTag
+
- Function
You can add a maximum of 10 tags to a resource.
+The API is idempotent. If a to-be-created tag has the same key as an existing tag, the tag will be created and overwrite the existing one.
+
URI
- URI format
POST /v2/{project_id}/{resource_type}/{resource_id}/tags
+ - Parameter description
++
+Parameter
+Mandatory
+Type
+Description
+project_id
+Yes
+String
+Project ID
+ +resource_type
+Yes
+String
+Resource type
+The value can be the following:
+smn_topic: topic
+ + +resource_id
+Yes
+String
+Resource ID
+Obtain a resource ID:
+- Add X-SMN-RESOURCEID-TYPE=name in the request header and set the resource ID to the topic name.
- Call the GetResourceInstances API to obtain the resource ID.
Request
- Parameter description
++ +
+Parameter
+Mandatory
+Type
+Description
+tag
+Yes
+Resource tag structure
+Resource tag to be added. For details, see Table 1.
++
+Table 1 Resource_tag structure Parameter
+Mandatory
+Type
+Description
+Constraint
+key
+Yes
+String
+Tag key
+The key contains 36 Unicode characters at most and cannot be blank or an empty string. It can contain only digits, letters, hyphens (-), and underscores (_) and must not start or end with a space.
+value
+Yes
+String
+Tag value
+Each value contains 43 Unicode characters at most and can be an empty string. It can contain only digits, letters, hyphens (-), and underscores (_) and must not start or end with a space.
+
- Request example
POST https://{SMN_Endpoint}/v2/{project_id}/{resource_type}/{resource_id}/tags+
- Example request
{ + "tag": + { + "key":"DEV", + "value":"DEV1" + } +}+
Response
None
+Returned Value
See Returned Value.
+Error Code
See section Error Code.
+Deleting a Resource Tag
+Description
- API name
DeleteResourceTag
+
- Function
The API is idempotent. When deleting a tag, the system does not check its character set. The tag key cannot be left blank or be an empty string. If the key of the tag to be deleted does not exist, 404 will be returned.
+
URI
- URI format
DELETE /v2/{project_id}/{resource_type}/{resource_id}/tags/{key}
+
- Parameter description
++
+Parameter
+Mandatory
+Type
+Description
+project_id
+Yes
+String
+Project ID
+ +resource_type
+Yes
+String
+Resource type
+The value can be the following:
+smn_topic: topic
+ + +resource_id
+Yes
+String
+Resource ID
+Obtain a resource ID:
+- Add X-SMN-RESOURCEID-TYPE=name in the request header and set the resource ID to the topic name.
- Call the GetResourceInstances API to obtain the resource ID.
Request
- Request example
DELETE https://{SMN_Endpoint}/v2/{project_id}/{resource_type}/{resource_id}/tags/{key}+
Response
None
+Returned Value
See Returned Value.
+Error Code
See section Error Code.
+Querying Resource Tags
+Description
- API name
ListResourceTags
+
- Function
Query tags of a specified resource.
+
URI
- URI format
GET /v2/{project_id}/{resource_type}/{resource_id}/tags
+ - Parameter description
++
+Parameter
+Mandatory
+Type
+Description
+project_id
+Yes
+String
+Project ID
+ +resource_type
+Yes
+String
+Resource type
+The value can be the following:
+smn_topic: topic
+ + +resource_id
+Yes
+String
+Resource ID
+Obtain a resource ID:
+- Add X-SMN-RESOURCEID-TYPE=name in the request header and set the resource ID to the topic name.
- Call the GetResourceInstances API to obtain the resource ID.
Request
- Parameter description
None
+
- Request example
GET https://{SMN_Endpoint}/v2/{project_id}/{resource_type}/{resource_id}/tags+
Response
- Parameter description
++ +
+Parameter
+Type
+Description
+tags
+Resource_tag structure array
+Tag list. For details, see Table 1.
++
+Table 1 Resource_tag structure Parameter
+Mandatory
+Type
+Description
+Constraint
+key
+Yes
+String
+Tag key
+The key contains 36 Unicode characters at most and cannot be blank or an empty string. It can contain only digits, letters, hyphens (-), and underscores (_) and must not start or end with a space.
+value
+Yes
+String
+Tag value
+Each value contains 43 Unicode characters at most and can be an empty string. It can contain only digits, letters, hyphens (-), and underscores (_) and must not start or end with a space.
+
- Response example
{ + "tags": [ + { + "key": "key1", + "value": "value1" + }, + { + "key": "key2", + "value": "value3" + } + ] +}+
Returned Value
See section Returned Value.
+Error Code
See section Error Code.
+Querying Tags in a Specified Project
+Description
- API name
GetProjectTags
+
- Function
Query all tags of a resource type in a specified project.
+
URI
- URI format
GET /v2/{project_id}/{resource_type}/tags
+ - Parameter description
++
+Parameter
+Mandatory
+Type
+Description
+project_id
+Yes
+String
+Project ID
+ +resource_type
+Yes
+String
+Resource type
+The value can be the following:
+smn_topic: topic
+ + +
Request
- Parameter description
None
+
- Request example
GET https://{SMN_Endpoint}/v2/{project_id}/{resource_type}/tags+
Response
- Parameter description
++ +
+Parameter
+Type
+Description
+tags
+Tags structure array
+Tag list. For details, see Table 1.
++
+Table 1 Tags structure Parameter
+Mandatory
+Type
+Description
+Constraint
+key
+Yes
+String
+Tag key
+A key contains 127 Unicode characters and cannot be blank.
+values
+Yes
+String list
+Value list
+Each value contains a maximum of 255 Unicode characters. If the value starts with an asterisk (*), the character string following the asterisk is fuzzy-matched. The values field cannot be missing, but can be an empty list. If it is empty, any value will be matched. The values are in OR relationship.
+
- Response example
{ + "tags": [ + { + "key": "key1", + "values": ["value1""value2"] + }, + { + "key": "key2", + "values": ["value1","value2"] + } + ] +}+
Returned Value
See section Returned Value.
+Error Code
See section Error Code.
+Public Parameters
+ +General Request Return Code
+ +-
+
- Exception Response
+
+ - Returned Value
+
+
Exception Response
+- Parameter description
++
+Parameter
+Type
+Description
+request_id
+String
+Request ID
+code
+String
+See section Error Code.
+message
+String
+See section Error Code.
+
- Example
{ + "request_id": "aad0860d089c482b943971f802a6718e", + "code": "SMN.0006", + "message": "Topic not found." +}+
Returned Value
+- Normal
++
+Returned Value
+Description
+200
+The task is submitted successfully.
+201
+Resource creation succeeds.
+
- Abnormal
++
+Returned Value
+Description
+400 Bad Request
+Incorrect request parameters.
+401 Unauthorized
+Authentication failed.
+403 Forbidden
+No permission to access the requested resource.
+404 Not Found
+The requested resource does not exist.
+500 Internal Server Error
+The request fails because the server is abnormal.
+501 Not Implemented
+The request fails because the server does not support the requested function.
+502 Bad Gateway
+The request fails because the returned response is invalid.
+503 Service Unavailable
+The request fails because the system is abnormal.
+504 Gateway Timeout
+Gateway times out.
+
Error Code
+Module + |
+HTTP Status Code + |
+Error Code + |
+Error Message + |
+Handling Measure + |
+
|---|---|---|---|---|
Tag management + |
+400 + |
+SMN.0038 + |
+Parameter: tag is invalid. + |
+Enter a valid value for tag. + |
+
Tag management + |
+403 + |
+SMN.0075 + |
+Parameter: tags are too many. + |
+A message template can contain a maximum of 90 non-repeated variables. + |
+
Direct SMS messaging + |
+403 + |
+SMN.0057 + |
+The number of SMS messages exceeds the limit. + |
+You can send at most 60 SMS messages to a single phone number within one hour and 200 within 12 hours. +This limit is applicable only to direct SMS message sending. There is no limit on the number of messages you can publish to a topic. + |
+
Public + |
+403 + |
+SMN.0001 + |
+No permission to request resources. + |
+Add the required permission. + |
+
Public + |
+400 + |
+SMN.0015 + |
+Parameter: Offset or limit is invalid. + |
+Enter a valid offset and limit. + |
+
Public + |
+500 + |
+SMN.0016 + |
+Database Exceptions. + |
+Contact customer service for technical support. + |
+
Public + |
+400 + |
+SMN.0017 + |
+Parameter: Remark is invalid. + |
+Enter a valid value for remark. + |
+
Public + |
+500 + |
+SMN.0018 + |
+Service internal error. + |
+Contact customer service for technical support. + |
+
Public + |
+403 + |
+SMN.0022 + |
+Parameter: token is invalid. + |
+Specify a valid token. + |
+
Public + |
+400 + |
+SMN.0033 + |
+Parameter: push_policy is invalid. + |
+Enter a valid value for push_policy. + |
+
Public + |
+400 + |
+SMN.0034 + |
+Parameter: subscription_auth_policy is invalid. + |
+Enter a valid value for subscription_auth_policy. + |
+
Public + |
+400 + |
+SMN.0035 + |
+Parameter: validation_policy is invalid. + |
+Enter a valid value for validation_policy. + |
+
Public + |
+400 + |
+SMN.0036 + |
+Parameter: xdomain_type is invalid. + |
+Enter a valid value for xdomain_type. + |
+
Public + |
+400 + |
+SMN.0059 + |
+Parameter: job_id is invalid. + |
+Contact customer service for technical support. + |
+
Public + |
+404 + |
+SMN.0060 + |
+Job not found. + |
+Contact customer service for technical support. + |
+
Public + |
+400 + |
+SMN.0061 + |
+Parameter: Service name is invalid. + |
+Contact customer service for technical support. + |
+
Public + |
+400 + |
+SMN.0062 + |
+Parameter: Show name is invalid. + |
+Contact customer service for technical support. + |
+
Public + |
+404 + |
+SMN.0063 + |
+Cloud service not found. + |
+Contact customer service for technical support. + |
+
Public + |
+403 + |
+SMN.0065 + |
+The number of email messages exceeds the limit. + |
+Contact customer service for technical support. + |
+
Public + |
+400 + |
+SMN.0066 + |
+Parameter: System parameter name is invalid. + |
+Contact customer service for technical support. + |
+
Public + |
+400 + |
+SMN.0067 + |
+Parameter: System parameter value is invalid. + |
+Contact customer service for technical support. + |
+
Public + |
+404 + |
+SMN.0068 + |
+System parameter not found. + |
+Contact customer service for technical support. + |
+
Public + |
+403 + |
+SMN.0069 + |
+Not authorized to subscribe internal endpoints. + |
+Enter a correct HTTP/HTTPS endpoint. + |
+
Public + |
+403 + |
+SMN.0070 + |
+No permission to request resources. The role is op_restricted. Contact customer service. + |
+Check the account balance and top up your account. If the fault persists, contact customer service. + |
+
Public + |
+403 + |
+SMN.0071 + |
+No permission to request resources. The role is op_suspended. + |
+Check whether your account has been frozen. + |
+
Public + |
+400 + |
+SMN.0074 + |
+Failed to add permission. + |
+Contact customer service for technical support. + |
+
Public + |
+400 + |
+SMN.0077 + |
+Parameter: Status is invalid. + |
+Enter a valid value for status. + |
+
Subscription management + |
+400 + |
+SMN.0011 + |
+Parameter: Protocol is invalid. + |
+Specify a correct protocol. + |
+
Subscription management + |
+400 + |
+SMN.0012 + |
+Parameter: Endpoint is invalid. + |
+Specify a valid endpoint. + |
+
Subscription management + |
+404 + |
+SMN.0013 + |
+Subscription resource not found. + |
+Specify an existing subscription endpoint. + |
+
Subscription management + |
+400 + |
+SMN.0014 + |
+Parameter: SubscriptionUrn is invalid. + |
+Enter a valid subscription URN. + |
+
Subscription management + |
+400 + |
+SMN.0043 + |
+Parameter: subscription is invalid. + |
+Enter a valid value for subscription. + |
+
Subscription management + |
+403 + |
+SMN.0078 + |
+The maximum number of subscriptions has been reached. + |
+The number of subscriptions has reached the limit. + |
+
Publishing a message + |
+403 + |
+SMN.0008 + |
+Parameter: Subject is invalid. + |
+Enter a valid value for subject. + |
+
Publishing a message + |
+403 + |
+SMN.0009 + |
+Parameter: Message is invalid. + |
+Enter a valid message. + |
+
Publishing a message + |
+400 + |
+SMN.0019 + |
+Producer Exceptions. + |
+Contact customer service for technical support. + |
+
Publishing a message + |
+400 + |
+SMN.0021 + |
+MessageStructure is invalid. + |
+Specify a correct message structure. + |
+
Message template + |
+400 + |
+SMN.0024 + |
+Parameter: content is invalid. + |
+Enter valid message template content. + |
+
Message template + |
+200 + |
+SMN.0025 + |
+Template already exists. + |
+You cannot create the same template twice. + |
+
Message template + |
+404 + |
+SMN.0027 + |
+Template not found. + |
+Specify an existing message template. + |
+
Message template + |
+400 + |
+SMN.0031 + |
+Parameter: template_id is invalid. + |
+Enter a valid template ID. + |
+
Message template + |
+400 + |
+SMN.0032 + |
+Parameter: message_template_name is invalid. + |
+Enter a valid value for message_template_name. + |
+
Message template + |
+400 + |
+SMN.0042 + |
+Parameter: Message_template_name is invalid. + |
+Enter a valid value for message_template_name. + |
+
Message template + |
+400 + |
+SMN.0044 + |
+Exceeded template limit. + |
+You can create a maximum of 100 text message templates. + |
+
Message template + |
+404 + |
+SMN.0076 + |
+Default message template not found. + |
+Create a default message template using the same template name. + |
+
Topic management + |
+400 + |
+SMN.0002 + |
+Parameter: Name is invalid. + |
+Enter a valid topic name. + |
+
Topic management + |
+400 + |
+SMN.0003 + |
+Parameter: DisplayName is invalid. + |
+Enter a valid topic display name. + |
+
Topic management + |
+403 + |
+SMN.0004 + |
+Exceeded topic limit. + |
+You can create a maximum of 3000 topics. + |
+
Topic management + |
+400 + |
+SMN.0005 + |
+Parameter: TopicUrn is invalid. + |
+Enter a valid topic URN. + |
+
Topic management + |
+404 + |
+SMN.0006 + |
+Topic not found. + |
+The topic does not exist. + |
+
Topic management + |
+403 + |
+SMN.0007 + |
+Exceeded subscription limit. + |
+A maximum of 10,000 subscriptions can be added to a topic. + |
+
Topic management + |
+404 + |
+SMN.0045 + |
+Attribute not found. + |
+Specify an existing attribute. + |
+
Topic management + |
+400 + |
+SMN.0046 + |
+Parameter: Attribute name is invalid. + |
+Enter a valid attribute name. + |
+
Topic management + |
+403 + |
+SMN.0047 + |
+Parameter: Value exceeds the maximum length. + |
+Enter a valid value. + |
+
Topic management + |
+400 + |
+SMN.0048 + |
+Parameter: Access policy is invalid. + |
+Enter a valid value for access_policy. + |
+
Topic management + |
+400 + |
+SMN.0049 + |
+Parameter: Access policy version is invalid. + |
+Enter a valid access policy version. + |
+
Topic management + |
+400 + |
+SMN.0050 + |
+Parameter: Access policy ID is invalid. + |
+Enter a valid policy ID. + |
+
Topic management + |
+400 + |
+SMN.0051 + |
+Parameter: Access policy statement is invalid. + |
+Enter a valid policy statement. + |
+
Topic management + |
+400 + |
+SMN.0052 + |
+Parameter: Access policy statement ID is invalid. + |
+Enter a valid policy statement ID. + |
+
Topic management + |
+400 + |
+SMN.0053 + |
+Parameter: Access policy statement resource is invalid. + |
+Enter a valid policy statement resource. + |
+
Topic management + |
+400 + |
+SMN.0054 + |
+Parameter: Access policy statement effect is invalid. + |
+Enter a valid policy statement effect. + |
+
Topic management + |
+400 + |
+SMN.0055 + |
+Parameter: Access policy statement action is invalid. + |
+Enter a valid policy statement action. + |
+
Topic management + |
+400 + |
+SMN.0056 + |
+Parameter: Access policy statement principal is invalid. + |
+Enter a valid policy statement principal. + |
+
Topic management + |
+400 + |
+SMN.0058 + |
+Parameter: Access policy statement condition is invalid. + |
+Enter a valid policy statement condition. + |
+
Topic management + |
+400 + |
+SMN.0072 + |
+Parameter: Service is invalid. + |
+Enter a valid value for service. + |
+
Topic management + |
+400 + |
+SMN.0073 + |
+Parameter: Invalid action. + |
+Enter a valid value for action. + |
+
Obtaining a Project ID
+A project ID needs to be specified in the URIs of some APIs. Therefore, you need to obtain the project ID before calling APIs. The following procedure describes how to obtain a project ID:
+- Log in to the management console.
- Click the username and choose My Credential from the drop-down list.
On the My Credential page, view project IDs in the project list.
+Figure 1 Viewing project IDs+
In multi-project scenarios, expand the region, and obtain your sub-project ID from the Project ID column.
+
Appendix
+ +-
+
- Topic Attribute List
+
+
Topic Attribute List
+Attribute Name + |
+Function + |
+Default Value + |
+
|---|---|---|
access_policy + |
+Configures topic access policy, which is used to limit the access permission of other users. + |
+Empty string + |
+
Change History
+Date + |
+Description + |
+
|---|---|
2019-02-15 + |
+This issue incorporates the following changes: +
|
+
2018-09-30 + |
+This issue incorporates the following changes: +Added Version Querying. + |
+
2018-06-21 + |
+This issue incorporates the following changes: +Accepted in OTC-3.1 + |
+
2018-06-05 + |
+This issue incorporates the following changes: +Updated the description for resource_type. (Currently, only smn_topic is supported). + |
+
2018-05-24 + |
+This issue incorporates the following changes: +Added the way to obtain a resource ID. + |
+
2018-04-30 + |
+This issue incorporates the following changes: +
|
+
2018-03-30 + |
+This issue incorporates the following changes: +Added the DMS subscription protocol. + |
+
2017-08-30 + |
+This issue incorporates the following changes: +Added description for obtaining a project ID. + |
+
2017-06-30 + |
+This issue incorporates the following changes: +Added Error Code. + |
+
2016-12-30 + |
+This issue is the first official release. + |
+