目录

服务通知

功能介绍

元服务通过调用requestSubscribeNotification获取用户授权后,可调用服务通知REST API,完成订阅消息下发功能。

约束与限制

请求体结构说明

[h2]接口原型

[projectId] :项目ID,登录AppGallery Connect网站,选择“开发与服务”,在项目列表中选择对应的项目,左侧导航栏选择“项目设置”,在该页面获取。

[h2]Request Header

参数 取值描述 样例
Authorization

鉴权方式:

JWT方式

详情参见基于服务账号生成鉴权令牌。

说明:

· 调用服务通知API接口必须使用PS256算法。

· 建议JWT令牌过期时间设置为3600秒,有效期内可以复用。

· Bearer后面拼接空格,再拼接获取的鉴权信息。

Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---****

[h2]Request Body

参数 是否必选 参数类型 描述
msgId 是 String 消息id,唯一确定一条消息。长度范围[1, 64]。由元服务自行生成,生成时请确保消息id唯一,方便用于定位问题。
toOpenId 是 String 接收者(用户)账号登录的openID。使用从端侧上报的openID,或请求华为账号服务器获取用户信息。可参考元服务账号使用规范进行华为账号登录的设计和接入。
appId 是 String

元服务的APP ID。长度范围[1, 64]。

说明:

[appId] :登录AppGallery Connect网站,选择“APP与元服务”,在列表中选择对应的元服务,左侧导航栏选择“应用信息”,在应用信息页面下的基本信息中获取APP ID的值。

templateId 是 String 所需下发的订阅模板ID。长度范围[1, 128]。
templateParams 是 TemplateParams Object 模板参数,形如{"key_0": "value","key_1": "value","key_2": "value"}的对象。单个参数的长度限制见TemplateParams,模板副标题的总长度不超过1024个字节。参数值不可为空。
clickAction 否 ClickAction Object 点击事件。不传时默认跳转首页。

[h2]TemplateParams

模板参数与您在服务通知领用模板时勾选的参数有关,请通过服务通知页面确认您的模板中有哪些参数。详情见选用订阅模板。

参数 参数类型 描述
thing String 可汉字、数字、字母或符号组合,128位以内。值不可为空。
numberdeprecated String 32位以内数字。值不可为空。此字段已经废弃。
letterdeprecated String 32位以内字母。值不可为空。此字段已经废弃。
symboldeprecated String 5位以内符号。值不可为空。此字段已经废弃。
characterdeprecated String 32位以内数字、字母或符号。值不可为空。此字段已经废弃。
time String

代表时间。年月日格式,如:2023年1月1日,24小时制时间格式(支持+年月日),支持填时间段,两个时间点之间用“~”符号连接。值不可为空。

日期或时间范围,取值样例:

· 2023年1月1日 22:22

· 2023年1月1日 22:22:00

· 2023年1月1日 00:00~2023年1月2日 23:59

· 2023年1月1日 00:00:00~2023年1月2日 23:59:59

· 2023年1月1日 00:00~12:30

· 2023年1月1日 00:00:00~12:30:00

· 2023年1月1日

· 2023年1月1日~2023年1月2日

datedeprecated String 代表日期。年月日格式(支持+24小时制时间),支持填时间段,两个时间点之间用“~”符号连接。值不可为空。此字段已经废弃。
amountdeprecated String 代表金额。1个币种符号+10位以内纯数字,可带小数,结尾可带“元”。值不可为空。此字段已经废弃。
phone_number String 代表电话号码。数字,符号,电话号码,如:+86-025-85697456。值不可为空。
car_number String 代表车牌号。8位以内,第一位与最后一位可为汉字,其余为字母或数字,例如车牌号码:粤A8Z888挂。值不可为空。
namedeprecated String 代表姓名。10个以内纯汉字或20个以内纯字母或空格。值不可为空。此字段已经废弃。
phrasedeprecated String 5个以内纯汉字,例如:配送中。值不可为空。此字段已经废弃。

[h2]ClickAction

参数 是否必选 参数类型 描述
actionType 是 Integer

消息点击后的行为。

0:打开元服务首页。

1:打开元服务指定页面。

说明:

当actionType为1时,字段action和uri至少填写一个,若都填写优先寻找与action匹配的应用页面。

action 否 String 应用内置页面ability对应的action。
uri 否 String 应用内置页面ability对应的uri。
data 否 Object

当actionType为0或1时,该字段用于在点击按钮后将数据传递给元服务。格式必须为key-value形式,最大长度1024字节。示例:

{"key1": "value1", "key2": "value2"}

请求示例

// Request URL
POST "https://push-api.cloud.huawei.com/v1/[projectId]/service_notification/send"
 
// Request Header
Content-Type: application/json
Authorization: Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---****

// Request Body
{
    "msgId": "2**********80",
    "appId": "6**********972",
    "toOpenId": "A**********O",
    "templateId": "1**********2",
    "templateParams": {
        "thing_0": "N0001",
        "time_1": "2024年4月27日 22:22",
        "thing_2": "软件大道101号"
    }
}

响应参数

[h2]Response Body

参数 是否必选 参数类型 描述
code 是 String 响应码。
msg 是 String 响应码描述。
requestId 是 String 请求标识。

响应示例

响应成功示例:

{
  "code": "80000000",
  "msg": "Success",
  "requestId": "157*******006"
}

响应失败示例:

{
  "code": "82500003",
  "msg": "Template subscribe msg appId error",
  "requestId": "157*******006"
}

HTTP响应码

HTTP响应码 描述 解决方法
200 成功。 -
400 参数错误。 请检查业务响应码并根据业务响应码进一步排查问题。
401 鉴权失败。 请检查HTTP头中Authorization参数。
404 找不到服务。 请检查请求URL是否正确。
500 服务内部错误。 请通过在线提单提交问题。
502 请求连接异常,常见于网络状况不稳定。 建议稍后重试,或通过在线提单提交问题。
503 流量控制。

· 平均分配发送速度。

· 平均分布推送时间段,不要集中发送。

说明:

单日单项目最多10万次,流控100tps。

504 网关超时。 建议稍后重试,或通过在线提单提交问题。

业务响应码

[h2]80000000 成功

错误信息

Success.

错误描述

发送成功。

可能原因

发送成功。

处理步骤

不涉及。

[h2]80100001 请求参数部分检查错误

错误信息

Check Parameter Error.

错误描述

请求参数部分检查错误。

可能原因

请求参数部分检查错误。

处理步骤

请根据响应消息中的提示,检查并修改请求参数内容。

[h2]81000001 系统内部错误

错误信息

Inner Error.

错误描述

系统内部错误。

可能原因

其他未知错误。

处理步骤

请通过在线提单提交问题。

[h2]82500001 模板参数校验异常

错误信息

Service notification msg send template param check error.

错误描述

模板参数校验异常。

可能原因

携带的模板参数不合法。

处理步骤

请按照响应消息中的提示,检查并修改携带的模板参数。

[h2]82500002 模板获取失败

错误信息

Service notification msg send template get error.

错误描述

模板获取失败。

可能原因

请求携带的模板ID不正确,查询不到对应模板信息。

处理步骤

请求携带的模板ID不正确,查询不到对应模板信息,请参考选用订阅模板查看模板详情,并修改模板ID。

[h2]82500003 项目信息异常

错误信息

Service notification msg send project info error.

错误描述

项目信息异常。

可能原因

  1. 请求url中项目ID查询不到项目信息。

  2. appId在黑名单中。

  3. 元服务未开通服务通知消息功能。

处理步骤

请登录AppGallery Connect网站,按照响应消息中的提示,检查请求参数内容。

  1. 请检查url中的项目ID是否正确。

  2. 检查appId是否在黑名单中。

  3. 请开通对应元服务的服务通知。

[h2]82500004 风控异常

错误信息

Service notification msg send risk check error.

错误描述

风控异常。

可能原因

模板参数携带违禁参数。

处理步骤

请按照响应消息中的提示,检查并修改模板参数中的违禁参数。

[h2]82500005 消息下发异常

错误信息

Service notification msg send push error.

错误描述

消息下发异常。

可能原因

  1. 下发超过订阅次数。

  2. 请求消息体超过默认大小。

  3. 用户未订阅消息。

  4. 元服务未开通推送服务。

处理步骤

按照响应消息中的提示,检查消息下发异常的情况:

  1. 下发超过订阅次数,请发起基于账号的订阅请求增加订阅次数。

  2. 请求消息体超过默认大小,请减小请求体大小并重新下发消息。

  3. 用户未订阅消息,请发起基于账号的订阅请求。

  4. 元服务未开通推送服务,请登录AppGallery Connect网站开通推送服务。

[h2]82500006 openID校验异常

错误信息

Service notification msg send openId check error.

错误描述

openID校验异常。

可能原因

接收者的openID错误。

处理步骤

请按照响应消息中的提示,使用从端侧上报的openID,或请求华为账号服务器获取用户信息中的openID,重新下发消息。

[h2]82500007 副文本构建异常

错误信息

Service notification msg send subtitle build error.

错误描述

副文本构建异常。

可能原因

携带的参数和模板参数不对应。

处理步骤

请按照响应消息中的提示,检查并修改模板参数,详情请参见选用订阅模板。

[h2]82500008 模板消息构建异常

错误信息

Service notification msg send msgBody build error.

错误描述

模板消息构建异常。

可能原因

携带的参数和模板参数不对应。

处理步骤

请按照响应消息中的提示,检查并修改模板参数,详情请参见选用订阅模板。