Create a subscription

1. API Description
This API (Subscribe) is used to create a new subscription under one of a user's topics.
Domain for public network API request: cmq-topic-region.api.qcloud.com
Domain for private network API request: cmq-topic-region.api.tencentyun.com
Note:
At any time (including alpha test), any downstream traffic generated when using public network domain will incur traffic fee. It is strongly recommended that users on Tencent Cloud use private network domain, as it will not incur any traffic fee.
2. Input Parameters
The following request parameter list only provides API request parameters. For other parameters, refer to Common Request Parameters.
Parameter Name
Required
Type
Description
topicName
Yes
String
Topic name. It is unique under the same account in a single region. Topic name is a string with no more than 64 characters. It must start with letter, and the rest may contain letters, numbers and dashes (-).
subscriptionName
Yes
String
Subscription name. It is unique for the same topic under the same account in a single region. Subscription name is a string with no more than 64 characters. It must start with letter, and the rest may contain letters, numbers and dashes (-).
protocol
Yes
String
Subscription protocol. Currently, two types of protocols are supported: HTTP, queue. When using HTTP protocol, users need to build web server to receive messages on their own. When using queue, messages will be automatically pushed to the CMQ queue and users can pull the messages concurrently.
notifyStrategy
No
String
Retry policy for the CMQ push server in case of errors when pushing messages to the endpoint. Available values are: 1) BACKOFF_RETRY (backoff retry). Re-push the message at regular intervals. Discard the message after a certain number of reties have been committed, then continue pushing the next message; 2) EXPONENTIAL_DECAY_RETRY (exponential decay retry). The interval between retries is increased exponentially, for example, retry in 1s first, then 2s, 4s, 8s...Since the cycle of a Topic message is one day, the retry operations will last for at most one day before the message is discarded. Default is EXPONENTIAL_DECAY_RETRY.
notifyContentFormat
No
String
Notification content format. Available values are: 1) JSON; 2) SIMPLIFIED, i.e. raw format. If the protocol is queue, the value must be SIMPLIFIED. If the protocol is HTTP, both values are available. Default is JSON.
filterTag.n
No
String
Message body. Message tag (used to filter message). There can be up to 5 tags, each containing no more than 16 characters. It is used in combination with the msgTag parameter of (Batch)PublishMessage. Rules: 1) If filterTag is not configured, the subscribers will receive all the messages published on Topic no matter whether msgTag is configured or not; 2) If filterTag array is configured with values, the subscribers will receive messages published on Topic only if at lease one of the values in the array exists in the msgTag array as well (that is, filterTag and msgTag intersect with each other); 3) If filterTag array is configured with values but msgTag is not configured, the subscribers will not receive any messages published on Topic. This can be considered a special case of 2), when there is no intersection between filterTag and msgTag. The design concept of the rules is based on the wills of the subscribers.
BindingKey
No
String
This field indicates the filtering policy for subscribing to and receiving messages. There can be up to 5 BindingKey, and each of them can contain up to 64 bytes, which can have up to 15 ., i.e., up to 16 phrases.
3. Output Parameters
Parameter Name
Type
Description
code
Int
0: Succeeded, others: Error. For detailed errors, please refer to the table below.
message
String
Error message.
requestId
String
ID of the request generated by server. When there is an internal error on the server, users can submit this ID to backend to locate the problem.
codeDesc
String
Error message description.
Error Code
Module Error Code
Error Message
Description
4490
10470
subscription is already existed
A subscription with the same name already exists under the same Topic of the same account.
4500
10480
number of subscription has reached the limit
The number of subscriptions under the same Topic has exceeded the limit. Currently, the limit is 100.
4000
10490
number of filterTag exceed limit
The number of filterTags exceeded the limit. Currently, the limit is 5.
4000
10500
endpoint format error
Incorrect endpoint format. Possible errors include: 1) URL contains space(s); 2) URL does not start with "http://" for http protocol; 3) Invalid URL; 4) protocol does not match with endpoint.
4000
10510
undefined protocol
Undefined protocol. Please check for spelling errors.
4000
10520
undefined notify retry stragety
Undefined push notification retry policy. Please check for spelling errors.
4000
10530
undefined notify content format
Undefined push notification format. Please check for spelling errors.
4510
10570
url connot contain any blank characters
URL cannot contain any blank characters.
4000
10580
subscription name format error
Incorrect subscription name format.
4000
10620
subscription name format error
Incorrect subscription name format.
4000
10630
illegal endpoint
Invalid endpoint.
4000
10640
notifyContentFormat of protocol queue must be SIMPLIFIED
If the protocol field is "queue", notifyContentFormat must be SIMPLIFIED.
6050
10740
too many filterTag or bindingKey
There are too many filterTag or bindingKey, please check the parameter configuration.
4000
10710
parameters lack of bindingKey
bindingKey is missing.
4000
10670
too many filterTag
There are too many filterTag, please check the number of parameters.
4000
10680
too many bindingKey
There are too many bindingKey, please check the number of parameters.
Note: The error codes listed in the above table are specific to the API. If the error code you are looking for is not here, you may find it in the Common Error Codes.
4. Example
Input:
 https://domain/v2/index.php?Action=Subscribe
 &topicName=test-topic-123
 &subscriptionName=test-subscription-123
 &protocol=http
 &endpoint=http://your_host/your_path 
 &<Common request parameters>
Output:
{
"code" : 0,
"message" : "",
"requestId":"14534664555"
}
﻿

Was this page helpful?

You can also Contact Sales or Submit a Ticket for help.

Yes

Parameter Name	Required	Type	Description
topicName	Yes	String	Topic name. It is unique under the same account in a single region. Topic name is a string with no more than 64 characters. It must start with letter, and the rest may contain letters, numbers and dashes (-).
subscriptionName	Yes	String	Subscription name. It is unique for the same topic under the same account in a single region. Subscription name is a string with no more than 64 characters. It must start with letter, and the rest may contain letters, numbers and dashes (-).
protocol	Yes	String	Subscription protocol. Currently, two types of protocols are supported: HTTP, queue. When using HTTP protocol, users need to build web server to receive messages on their own. When using queue, messages will be automatically pushed to the CMQ queue and users can pull the messages concurrently.
notifyStrategy	No	String	Retry policy for the CMQ push server in case of errors when pushing messages to the endpoint. Available values are: 1) BACKOFF_RETRY (backoff retry). Re-push the message at regular intervals. Discard the message after a certain number of reties have been committed, then continue pushing the next message; 2) EXPONENTIAL_DECAY_RETRY (exponential decay retry). The interval between retries is increased exponentially, for example, retry in 1s first, then 2s, 4s, 8s...Since the cycle of a Topic message is one day, the retry operations will last for at most one day before the message is discarded. Default is EXPONENTIAL_DECAY_RETRY.
notifyContentFormat	No	String	Notification content format. Available values are: 1) JSON; 2) SIMPLIFIED, i.e. raw format. If the protocol is queue, the value must be SIMPLIFIED. If the protocol is HTTP, both values are available. Default is JSON.
filterTag.n	No	String	Message body. Message tag (used to filter message). There can be up to 5 tags, each containing no more than 16 characters. It is used in combination with the msgTag parameter of (Batch)PublishMessage. Rules: 1) If filterTag is not configured, the subscribers will receive all the messages published on Topic no matter whether msgTag is configured or not; 2) If filterTag array is configured with values, the subscribers will receive messages published on Topic only if at lease one of the values in the array exists in the msgTag array as well (that is, filterTag and msgTag intersect with each other); 3) If filterTag array is configured with values but msgTag is not configured, the subscribers will not receive any messages published on Topic. This can be considered a special case of 2), when there is no intersection between filterTag and msgTag. The design concept of the rules is based on the wills of the subscribers.
BindingKey	No	String	This field indicates the filtering policy for subscribing to and receiving messages. There can be up to 5 `BindingKey`, and each of them can contain up to 64 bytes, which can have up to 15 `.`, i.e., up to 16 phrases.

Error Code	Module Error Code	Error Message	Description
4490	10470	subscription is already existed	A subscription with the same name already exists under the same Topic of the same account.
4500	10480	number of subscription has reached the limit	The number of subscriptions under the same Topic has exceeded the limit. Currently, the limit is 100.
4000	10490	number of filterTag exceed limit	The number of filterTags exceeded the limit. Currently, the limit is 5.
4000	10500	endpoint format error	Incorrect endpoint format. Possible errors include: 1) URL contains space(s); 2) URL does not start with "http://" for http protocol; 3) Invalid URL; 4) protocol does not match with endpoint.
4000	10510	undefined protocol	Undefined protocol. Please check for spelling errors.
4000	10520	undefined notify retry stragety	Undefined push notification retry policy. Please check for spelling errors.
4000	10530	undefined notify content format	Undefined push notification format. Please check for spelling errors.
4510	10570	url connot contain any blank characters	URL cannot contain any blank characters.
4000	10580	subscription name format error	Incorrect subscription name format.
4000	10620	subscription name format error	Incorrect subscription name format.
4000	10630	illegal endpoint	Invalid endpoint.
4000	10640	notifyContentFormat of protocol queue must be SIMPLIFIED	If the protocol field is "queue", notifyContentFormat must be SIMPLIFIED.
6050	10740	too many filterTag or bindingKey	There are too many filterTag or bindingKey, please check the parameter configuration.
4000	10710	parameters lack of bindingKey	bindingKey is missing.
4000	10670	too many filterTag	There are too many filterTag, please check the number of parameters.
4000	10680	too many bindingKey	There are too many bindingKey, please check the number of parameters.

tencent cloud

Sign Up

Log in

Compute

Microservice

Data Migration

Database SaaS Tool

Data Security

Application Security

Big Data

Image Creation

Internet of Things

Stream Services

Cloud Real-time Rendering

Cloud Resource Management

More

Edge Computing

Serverless

Relational Database

Networking

Business Security

Domains & Websites

Face Recognition

AI Platform Service

Middleware

Media On-Demand

Game Services

Management and Audit Tools

Container

Essential Storage Service

Enterprise Distributed DBMS

CDN and Acceleration

Security Services

Enterprise Applications

Voice Technology

Natural Language Processing

Communication

Media Process Services

Education Sevices

Developer Tools

Distributed cloud

Data Process and Analysis

NoSQL Database

Network Security

Cloud Security

Office Collaboration

Tencent Big Model

Optical Character Recognition

Interactive Video Services

Media SDK

Medical Services

Monitor and Operation

1. API Description

2. Input Parameters

3. Output Parameters

4. Example