# 服务通知

> phone | 2in1 | tablet | tv | wearable

## 功能介绍

元服务通过调用[requestSubscribeNotification](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/push-servicenotification#servicenotificationrequestsubscribenotification-1)获取用户授权后，可调用服务通知REST API，完成订阅消息下发功能。

## 约束与限制

* 服务通知能力支持Phone、Tablet设备。

* 消息发送量，按订阅次数下发：

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

## 请求体结构说明

### 接口原型

* **承载协议：** HTTPS POST

* **接口方向：** 开发者服务器 -> 华为Push服务器

* **接口URL：** https://push-api.cloud.huawei.com/**v1** /**[projectId]**/service_notification/send

* **数据格式：** Content-Type: application/json

> 说明
>
> **[projectId]** ：项目ID，登录[AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html)网站，选择"开发与服务"，在项目列表中选择对应的项目，左侧导航栏选择"项目设置"，在该页面获取。

### Request Header

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

### Request Body

|参数|是否必选|参数类型|描述|
|:-------------|:---|:---------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|msgId|是|String|消息id，唯一确定一条消息。长度范围[1, 64]。由元服务自行生成，生成时请确保消息id唯一，方便用于定位问题。|
|toOpenId|是|String|接收者（用户）账号登录的openID。使用从端侧上报的openID，或请求华为账号服务器[获取用户信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/account-api-get-user-info-overview)。可参考元服务[账号使用规范](https://developer.huawei.com/consumer/cn/doc/design-guides/accounts-0000001967444380)进行华为账号登录的设计和接入。|
|appId|是|String|元服务的APP ID。长度范围[1, 64]。 **说明：** **[appId]** ：登录[AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html)网站，选择"APP与元服务"，在列表中选择对应的元服务，左侧导航栏选择"应用信息"，在应用信息页面下的基本信息中获取**APP ID**的值。|
|templateId|是|String|所需下发的订阅模板ID。长度范围[1, 128]。|
|templateParams|是|[TemplateParams](#templateparams) Object|模板参数，形如{"key_0": "value","key_1": "value","key_2": "value"}的对象。单个参数的长度限制见TemplateParams，模板副标题的总长度不超过1024个字节。参数值不可为空。|
|clickAction|否|[ClickAction](#clickaction) Object|点击事件。不传时默认跳转首页。|

### **TemplateParams**

模板参数与您在服务通知领用模板时勾选的参数有关，请通过服务通知页面确认您的模板中有哪些参数。详情见[选用订阅模板](https://developer.huawei.com/consumer/cn/doc/atomic-guides/push-as-service-noti#section880418143379)。

|参数|参数类型|描述|
|:--------------------|:-----|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|thing|String|可汉字、数字、字母或符号组合，128位以内。值不可为空。|
|number^deprecated^|String|32位以内数字。值不可为空。此字段已经废弃。|
|letter^deprecated^|String|32位以内字母。值不可为空。此字段已经废弃。|
|symbol^deprecated^|String|5位以内符号。值不可为空。此字段已经废弃。|
|character^deprecated^|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日|
|date^deprecated^|String|代表日期。年月日格式（支持+24小时制时间），支持填时间段，两个时间点之间用"~"符号连接。值不可为空。此字段已经废弃。|
|amount^deprecated^|String|代表金额。1个币种符号+10位以内纯数字，可带小数，结尾可带"元"。值不可为空。此字段已经废弃。|
|phone_number|String|代表电话号码。数字，符号，电话号码，如：+86-025-85697456。值不可为空。|
|car_number|String|代表车牌号。8位以内，第一位与最后一位可为汉字，其余为字母或数字，例如车牌号码：粤A8Z888挂。值不可为空。|
|name^deprecated^|String|代表姓名。10个以内纯汉字或20个以内纯字母或空格。值不可为空。此字段已经废弃。|
|phrase^deprecated^|String|5个以内纯汉字，例如：配送中。值不可为空。此字段已经废弃。|

### **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"}|

## 请求示例

```json5
// 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号"
    }
}
```

## 响应参数

### Response Body

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

## 响应示例

**响应成功示例：**

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

**响应失败示例：**

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

## HTTP响应码

|HTTP响应码|描述|解决方法|
|:------|:-----------------|:----------------------------------------------------------------------------------|
|200|成功。|-|
|400|参数错误。|请检查业务响应码并根据业务响应码进一步排查问题。|
|401|鉴权失败。|请检查HTTP头中Authorization参数。|
|404|找不到服务。|请检查请求URL是否正确。|
|500|服务内部错误。|请通过[在线提单](https://developer.huawei.com/consumer/cn/support/feedback/#/)提交问题。|
|502|请求连接异常，常见于网络状况不稳定。|建议稍后重试，或通过[在线提单](https://developer.huawei.com/consumer/cn/support/feedback/#/)提交问题。|
|503|流量控制。|· 平均分配发送速度。 · 平均分布推送时间段，不要集中发送。 **说明：** 单日单项目最多10万次，流控100tps。|
|504|网关超时。|建议稍后重试，或通过[在线提单](https://developer.huawei.com/consumer/cn/support/feedback/#/)提交问题。|

## 业务响应码

### 80000000 成功

**错误信息**

Success.

**错误描述**

发送成功。

**可能原因**

发送成功。

**处理步骤**

不涉及。

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

**错误信息**

Check Parameter Error.

**错误描述**

请求参数部分检查错误。

**可能原因**

请求参数部分检查错误。

**处理步骤**

请根据响应消息中的提示，检查并修改请求[参数内容](#请求体结构说明)。

### 81000001 系统内部错误

**错误信息**

Inner Error.

**错误描述**

系统内部错误。

**可能原因**

其他未知错误。

**处理步骤**

请通过[在线提单](https://developer.huawei.com/consumer/cn/support/feedback/#/)提交问题。

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

**错误信息**

Service notification msg send template param check error.

**错误描述**

模板参数校验异常。

**可能原因**

携带的模板参数不合法。

**处理步骤**

请按照响应消息中的提示，检查并修改携带的[模板参数](#request-body)。

### 82500002 模板获取失败

**错误信息**

Service notification msg send template get error.

**错误描述**

模板获取失败。

**可能原因**

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

**处理步骤**

请求携带的模板ID不正确，查询不到对应模板信息，请参考[选用订阅模板](https://developer.huawei.com/consumer/cn/doc/atomic-guides/push-as-service-noti#section880418143379)查看模板详情，并修改模板ID。

### 82500003 项目信息异常

**错误信息**

Service notification msg send project info error.

**错误描述**

项目信息异常。

**可能原因**

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

2. appId在黑名单中。

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

**处理步骤**

请登录[AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html)网站，按照响应消息中的提示，检查请求参数内容。

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

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

3. 请开通对应元服务的[服务通知](https://developer.huawei.com/consumer/cn/doc/atomic-guides/push-as-service-noti#section798882510516)。

### 82500004 风控异常

**错误信息**

Service notification msg send risk check error.

**错误描述**

风控异常。

**可能原因**

模板参数携带违禁参数。

**处理步骤**

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

### 82500005 消息下发异常

**错误信息**

Service notification msg send push error.

**错误描述**

消息下发异常。

**可能原因**

1. 下发超过订阅次数。

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

3. 用户未订阅消息。

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

**处理步骤**

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

1. 下发超过订阅次数，请[发起基于账号的订阅请求](https://developer.huawei.com/consumer/cn/doc/atomic-guides/push-as-request-sub)增加订阅次数。

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

3. 用户未订阅消息，请[发起基于账号的订阅请求](https://developer.huawei.com/consumer/cn/doc/atomic-guides/push-as-request-sub)。

4. 元服务未开通推送服务，请登录[AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html)网站[开通推送服务](https://developer.huawei.com/consumer/cn/doc/atomic-guides/push-as-prepare#section73941874447)。

### 82500006 openID校验异常

**错误信息**

Service notification msg send openId check error.

**错误描述**

openID校验异常。

**可能原因**

接收者的openID错误。

**处理步骤**

请按照响应消息中的提示，使用从端侧上报的openID，或请求华为账号服务器[获取用户信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/account-api-get-user-info-overview)中的openID，重新下发消息。

### 82500007 副文本构建异常

**错误信息**

Service notification msg send subtitle build error.

**错误描述**

副文本构建异常。

**可能原因**

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

**处理步骤**

请按照响应消息中的提示，检查并修改[模板参数](#request-body)，详情请参见[选用订阅模板](https://developer.huawei.com/consumer/cn/doc/atomic-guides/push-as-service-noti#section880418143379)。

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

**错误信息**

Service notification msg send msgBody build error.

**错误描述**

模板消息构建异常。

**可能原因**

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

**处理步骤**

请按照响应消息中的提示，检查并修改[模板参数](#request-body)，详情请参见[选用订阅模板](https://developer.huawei.com/consumer/cn/doc/atomic-guides/push-as-service-noti#section880418143379)。