# 服务通知

#### 功能介绍

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

#### 约束与限制

*   服务通知能力支持Phone、Tablet设备。
    
*   消息发送量，按订阅次数下发：
    
    *   一次性订阅：指用户订阅一次，元服务可不限时间地下发一条对应的订阅消息。
    *   长期订阅：指用户订阅一次，元服务可在模板限制的订阅周期及频次内多次下发通知。（HarmonyOS 6.0正式支持）
*   服务通知API接口当前不支持消息回执功能。
    

#### 请求体结构说明

#### 接口原型

*   **承载协议：** HTTPS POST
    
*   **接口方向：** 开发者服务器 -> 华为Push服务器
    
*   **接口URL：** ]**/service\_notification/send
    
*   **数据格式：** Content-Type: application/json
    

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

#### Request Header

| 参数 | 取值描述 | 样例 |
| --- | --- | --- |
| Authorization | 鉴权方式： JWT方式 详情参见基于服务账号生成鉴权令牌。 说明： · 调用服务通知API接口必须使用PS256算法。 · 建议JWT令牌过期时间设置为3600秒，有效期内可以复用。 - Bearer后面拼接空格，再拼接获取的鉴权信息。 | Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---**** |

#### 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 | 点击事件。不传时默认跳转首页。 |

#### **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个以内纯汉字，例如：配送中。值不可为空。此字段已经废弃。 |

#### **ClickAction**

| 参数 | 是否必选 | 参数类型 | 描述 |
| --- | --- | --- | --- |
| actionType | 是 | Integer | 消息点击后的行为。 0：打开元服务首页。 1：打开元服务指定页面。 |
| action | 否 | String | 应用内置页面ability对应的action。当actionType为1时，字段action和uri至少填写一个，若都填写优先寻找与action匹配的应用页面。 |
| uri | 否 | String | 应用内置页面ability对应的uri。当actionType为1时，字段action和uri至少填写一个，若都填写优先寻找与action匹配的应用页面。 |
| data | 否 | Object | 当actionType为0或1时，该字段用于在点击按钮后将数据传递给元服务。格式必须为key-value形式，最大长度1024字节。示例： {"key1": "value1", "key2": "value2"} |

#### 请求示例

```
// Request URL
POST "]/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号"
    }
}
```

#### 响应参数

#### 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 | 找不到服务。 | 请检查请求URI是否正确。 |
| 500 | 服务内部错误。 | 请通过在线提单提交问题。 |
| 502 | 请求连接异常，常见于网络状况不稳定。 | 建议稍后重试，或通过在线提单提交问题。 |
| 503 | 流量控制。 | · 平均分配发送速度。 · 平均分布推送时间段，不要集中发送。 说明： 单日单项目最多10万次，流控100tps。 |
| 504 | 网关超时。 | 建议稍后重试，或通过在线提单提交问题。 |

#### 业务响应码

#### 80000000 成功

**错误信息**

Success.

**错误描述**

发送成功。

**可能原因**

发送成功。

**处理步骤**

不涉及。

#### 80100001 请求参数部分检查错误

**错误信息**

Check Parameter Error.

**错误描述**

请求参数部分检查错误。

**可能原因**

请求参数部分检查错误。

**处理步骤**

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

#### 81000001 系统内部错误

**错误信息**

Inner Error.

**错误描述**

系统内部错误。

**可能原因**

其他未知错误。

**处理步骤**

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

#### 82500001 模板参数校验异常

**错误信息**

Service notification msg send template param check error.

**错误描述**

模板参数校验异常。

**可能原因**

携带的模板参数不合法。

**处理步骤**

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

#### 82500002 模板获取失败

**错误信息**

Service notification msg send template get error.

**错误描述**

模板获取失败。

**可能原因**

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

**处理步骤**

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

#### 82500003 项目信息异常

**错误信息**

Service notification msg send project info error.

**错误描述**

项目信息异常。

**可能原因**

1.  请求url中项目ID查询不到项目信息。
    
2.  appId在黑名单中。
    
3.  元服务未开通服务通知消息功能。
    

**处理步骤**

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

1.  请检查url中的项目ID是否正确。
    
2.  检查appId是否在黑名单中。
    
3.  请开通对应元服务的服务通知。
    

#### 82500004 风控异常

**错误信息**

Service notification msg send risk check error.

**错误描述**

风控异常。

**可能原因**

模板参数携带违禁参数。

**处理步骤**

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

#### 82500005 消息下发异常

**错误信息**

Service notification msg send push error.

**错误描述**

消息下发异常。

**可能原因**

1.  下发超过订阅次数。
    
2.  请求消息体超过默认大小。
    
3.  用户未订阅消息。
    
4.  元服务未开通推送服务。
    

**处理步骤**

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

1.  下发超过订阅次数，请发起基于账号的订阅请求增加订阅次数。
    
2.  请求消息体超过默认大小，请减小请求体大小并重新下发消息。
    
3.  用户未订阅消息，请发起基于账号的订阅请求。
    
4.  元服务未开通推送服务，请登录AppGallery Connect网站开通推送服务。
    

#### 82500006 openID校验异常

**错误信息**

Service notification msg send openId check error.

**错误描述**

openID校验异常。

**可能原因**

接收者的openID错误。

**处理步骤**

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

#### 82500007 副文本构建异常

**错误信息**

Service notification msg send subtitle build error.

**错误描述**

副文本构建异常。

**可能原因**

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

**处理步骤**

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

#### 82500008 模板消息构建异常

**错误信息**

Service notification msg send msgBody build error.

**错误描述**

模板消息构建异常。

**可能原因**

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

**处理步骤**

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