Getting Subscription List

Last updated: 2019-07-05 15:23:22

PDF

1. API Description

This API (ListSubscriptionByTopic) is used to display the subscription list under one of a user's topics. Data can be acquired in pages.

Domain for public network API request: cmq-topic-region.api.qcloud.com

Domain for private network API request: cmq-topic-region.api.tencentyun.com

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.

  • The "region" should be replaced by a specific region: gz (Guangzhou), sh (Shanghai), bj (Beijing). The "region" value in the common parameter should be kept consistent with that in the domain. In case of inconsistency, the one in the domain should prevail. The request should be sent to the region specified by the domain.
  • Requests for accessing via public network domain support both HTTP and HTTPS. Requests for accessing via private network only support HTTP.
  • Some of the input parameters are optional, so the default values are not required.
  • All output parameters will be returned to the user when the request is successful; otherwise, at least code, message, and requestId will be returned.

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 (-).
searchWord No String It is used to filter subscription lists. The backend will return subscription lists that match with the conditions using fuzzy match method. If this parameter is not specified, all the subscriptions of the account will be returned by default.
offset No Int This is the starting point from where the current page will acquire subscription lists when displaying data in pages. If this value is specified, "limit" is also required. The backend will use 0 as default value. Value range: 0-1000.
limit No Int Number of subscriptions to be acquired by the current page when displaying data in pages. Value range: 0-100. If not specified, this parameter is 20 by default.

The meanings of offset and limit here are the same as the offset and limit of SQL.

3. Output Parameters

Parameter Name Type Description
code Int Please refer to Error Codes
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.
totalCount Int Total number of topics returned for the current request, under the user account. (This is not the number of topics acquired by the current page when displaying data in pages).
subscriptionList Array Topic list information. Each element indicates the information of one topic.

topicList is defined as follows:

Parameter Name Type Description
subscriptionId String Subscription ID. It is used when you pull monitoring data.
subscriptionName 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 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.
endpoint String endpoint used to receive notification. It varies with the protocol: for HTTP, endpoint must start with "http://", and host can be either domain or IP; for queue, queueName is entered here.

4. Example

Input:

 https://domain/v2/index.php?Action=ListSubscriptionByTopic
 &searchWord=abc
 &<Common request parameters>

Output:

{
"code" : 0,
"message" : "",
"requestId":"14534664555",
"totalCount":2
"topicList":
[
{
"subscriptionId":"subsc-sdkfl",
"subscriptionName":"test-sub2",
"protocol":"http"
"endpoint":"http://testhost/testpath"
}
,
{
"subscriptionId":"subsc-34lasdk",
"subscriptionName":"test-sub1",
"protocol":"queue"
"endpoint":"test-queue-name"
}
]
}