订阅
功能介绍
为指定Topic添加一个订阅者,如果订阅者的状态为未确认,则向订阅者发送一个确认的消息。待订阅者进行ConfirmSubscription确认后,该订阅者才能收到Topic发布的消息。单Topic默认可添加10000个订阅者,高并发场景下,可能会出现订阅者数量超过10000仍添加成功的情况,此为正常现象。接口是幂等的,如果添加已存在的订阅者,则返回成功,且status code为200,否则status code为201。
调用方法
请参见如何调用API。
URI
POST /v2/{project_id}/notifications/topics/{topic_urn}/subscriptions
请求参数
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
X-Auth-Token |
是 |
String |
用户Token。 通过调用IAM服务获取用户Token接口获取(响应消息头中X-Subject-Token的值)。 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
protocol |
是 |
String |
不同协议对应不同的endpoint(接受消息的接入点)。 目前支持的协议包括: “email”:邮件传输协议,endpoint为邮箱地址。 “sms”:短信传输协议,endpoint为手机号码。 “functionstage”:FunctionGraph(函数)传输协议,endpoint为一个函数。 “functiongraph”:FunctionGraph(工作流)传输协议,endpoint为由一组函数编排成的工作流。 “http”、“https”:HTTP/HTTPS传输协议,endpoint为URL。 “callnotify”:语音通知传输协议,endpoint为手机号码。 “wechat”:微信群机器人传输协议。 “dingding”:钉钉群机器人传输协议。 “feishu”:飞书群机器人传输协议。 “welink”:welink群机器人传输协议。 |
endpoint |
是 |
String |
说明: http协议,接入点必须以“http://”开头。 https协议,接入点必须以“https://”开头。 email协议,接入点必须是邮件地址。 sms协议,接入点必须是一个电话号码。 functionstage协议,接入点必须是一个函数。 functiongraph协议,接入点必须是一个函数工作流。 callnotify协议,接入点必须是一个电话号码。 dingding协议,接入点必须是一个钉钉自定义群机器人的地址,或添加了钉钉企业内部机器人的群组openConversationId。添加钉钉企业内部机器人对应的群组openConversationId时,该字段不能以“http://”或“https://”为开头。 wechat协议,接入点必须是一个微信群机器人的地址。 feishu协议,接入点必须是一个飞书群机器人的地址。 welink协议,接入点必须是一个welink的群号。 |
remark |
否 |
String |
备注。最大支持128字节,约42个中文,必须是UTF-8编码的字符串,否则无法正常显示中文。 |
extension |
否 |
SubscriptionExtension object |
扩展信息。 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
client_id |
否 |
String |
这是应用ID字段。当protocol值为welink时,该字段为必填字段,从welink方获取。 |
client_secret |
否 |
String |
该字段为应用secret字段。当protocol值为welink时,该字段为必填字段,从welink方获取。 |
keyword |
否 |
String |
该字段为关键字字段。当protocol值为feishu时,这里的keyword字段和sign_secret字段二者必选其一。当用户在飞书或钉钉自定义机器人端添加关键字校验的安全策略时,这里的关键字必须是飞书或钉钉自定义机器人中所填写的关键字之一。 |
sign_secret |
否 |
String |
这是加签密钥字段。当protocol协议为feishu时,这个字段和keyword字段二者必选且只能选其一。密钥配置必须与客户在飞书或钉钉自定义机器人的密钥配置完全一致。例如,如果在飞书端配置了密钥并且没有配置关键字,则在此处填入从飞书获取的密钥字段,如果在飞书端没有配置密钥并且配置了关键字,则不填写该字段。 |
响应参数
状态码: 201
参数 |
参数类型 |
描述 |
---|---|---|
request_id |
String |
请求的唯一标识ID。 |
subscription_urn |
String |
订阅者的唯一资源标识。 |
状态码: 400
参数 |
参数类型 |
描述 |
---|---|---|
request_id |
String |
请求的唯一标识ID。 |
code |
String |
服务异常错误信息编码。 |
message |
String |
服务异常错误信息描述。 |
状态码: 403
参数 |
参数类型 |
描述 |
---|---|---|
request_id |
String |
请求的唯一标识ID。 |
code |
String |
服务异常错误信息编码。 |
message |
String |
服务异常错误信息描述。 |
状态码: 404
参数 |
参数类型 |
描述 |
---|---|---|
request_id |
String |
请求的唯一标识ID。 |
code |
String |
服务异常错误信息编码。 |
message |
String |
服务异常错误信息描述。 |
状态码: 500
参数 |
参数类型 |
描述 |
---|---|---|
request_id |
String |
请求的唯一标识ID。 |
code |
String |
服务异常错误信息编码。 |
message |
String |
服务异常错误信息描述。 |
请求示例
在名称为test_topic_v1的主题下添加一个邮件订阅者
POST https://{SMN_Endpoint}/v2/{project_id}/notifications/topics/urn:smn:regionId:762bdb3251034f268af0e395c53ea09b:test_topic_v1/subscriptions { "protocol" : "email", "endpoint" : "xxx@example.com", "remark" : "运维" }
响应示例
状态码: 201
OK
[ { "request_id" : "6a63a18b8bab40ffb71ebd9cb80d0085", "subscription_urn" : "urn:smn:regionId:762bdb3251034f268af0e395c53ea09b:test_topic_v1:2e778e84408e44058e6cbc6d3c377837" } ]
SDK代码示例
SDK代码示例如下。
在名称为test_topic_v1的主题下添加一个邮件订阅者
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 |
package com.huaweicloud.sdk.test; import com.huaweicloud.sdk.core.auth.ICredential; import com.huaweicloud.sdk.core.auth.BasicCredentials; import com.huaweicloud.sdk.core.exception.ConnectionException; import com.huaweicloud.sdk.core.exception.RequestTimeoutException; import com.huaweicloud.sdk.core.exception.ServiceResponseException; import com.huaweicloud.sdk.smn.v2.region.SmnRegion; import com.huaweicloud.sdk.smn.v2.*; import com.huaweicloud.sdk.smn.v2.model.*; public class AddSubscriptionSolution { public static void main(String[] args) { // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security. // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment String ak = System.getenv("CLOUD_SDK_AK"); String sk = System.getenv("CLOUD_SDK_SK"); String projectId = "{project_id}"; ICredential auth = new BasicCredentials() .withProjectId(projectId) .withAk(ak) .withSk(sk); SmnClient client = SmnClient.newBuilder() .withCredential(auth) .withRegion(SmnRegion.valueOf("<YOUR REGION>")) .build(); AddSubscriptionRequest request = new AddSubscriptionRequest(); request.withTopicUrn("{topic_urn}"); AddSubscriptionRequestBody body = new AddSubscriptionRequestBody(); body.withRemark("运维"); body.withEndpoint("xxx@example.com"); body.withProtocol("email"); request.withBody(body); try { AddSubscriptionResponse response = client.addSubscription(request); System.out.println(response.toString()); } catch (ConnectionException e) { e.printStackTrace(); } catch (RequestTimeoutException e) { e.printStackTrace(); } catch (ServiceResponseException e) { e.printStackTrace(); System.out.println(e.getHttpStatusCode()); System.out.println(e.getRequestId()); System.out.println(e.getErrorCode()); System.out.println(e.getErrorMsg()); } } } |
在名称为test_topic_v1的主题下添加一个邮件订阅者
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 |
# coding: utf-8 import os from huaweicloudsdkcore.auth.credentials import BasicCredentials from huaweicloudsdksmn.v2.region.smn_region import SmnRegion from huaweicloudsdkcore.exceptions import exceptions from huaweicloudsdksmn.v2 import * if __name__ == "__main__": # The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security. # In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment ak = os.environ["CLOUD_SDK_AK"] sk = os.environ["CLOUD_SDK_SK"] projectId = "{project_id}" credentials = BasicCredentials(ak, sk, projectId) client = SmnClient.new_builder() \ .with_credentials(credentials) \ .with_region(SmnRegion.value_of("<YOUR REGION>")) \ .build() try: request = AddSubscriptionRequest() request.topic_urn = "{topic_urn}" request.body = AddSubscriptionRequestBody( remark="运维", endpoint="xxx@example.com", protocol="email" ) response = client.add_subscription(request) print(response) except exceptions.ClientRequestException as e: print(e.status_code) print(e.request_id) print(e.error_code) print(e.error_msg) |
在名称为test_topic_v1的主题下添加一个邮件订阅者
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 |
package main import ( "fmt" "github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/basic" smn "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/smn/v2" "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/smn/v2/model" region "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/smn/v2/region" ) func main() { // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security. // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment ak := os.Getenv("CLOUD_SDK_AK") sk := os.Getenv("CLOUD_SDK_SK") projectId := "{project_id}" auth := basic.NewCredentialsBuilder(). WithAk(ak). WithSk(sk). WithProjectId(projectId). Build() client := smn.NewSmnClient( smn.SmnClientBuilder(). WithRegion(region.ValueOf("<YOUR REGION>")). WithCredential(auth). Build()) request := &model.AddSubscriptionRequest{} request.TopicUrn = "{topic_urn}" remarkAddSubscriptionRequestBody:= "运维" request.Body = &model.AddSubscriptionRequestBody{ Remark: &remarkAddSubscriptionRequestBody, Endpoint: "xxx@example.com", Protocol: "email", } response, err := client.AddSubscription(request) if err == nil { fmt.Printf("%+v\n", response) } else { fmt.Println(err) } } |
更多编程语言的SDK代码示例,请参见API Explorer的代码示例页签,可生成自动对应的SDK代码示例。
状态码
状态码 |
描述 |
---|---|
201 |
OK |
400 |
Bad Request |
403 |
Unauthorized |
404 |
Not Found |
500 |
Internal Server Error |
错误码
请参见错误码。