# 意图共享

#### 功能介绍

应用/元服务通过意图共享接口，把对应意图的相关事件数据共享给Intents Kit，用于事件提醒服务。

#### 场景描述

**用户事件：** 由用户主动行为触发，应用/元服务通过意图共享接口，把对应意图的相关用户事件数据共享给Intents Kit。

**公共事件**：由公共事件触发（如台风天气），华为公共云服务器通过意图共享接口，把对应意图的相关公共事件数据共享给Intents Kit。

#### 接口原型

**承载协议：** HTTPS POST

**接口方向：** 开发者服务器->Intents Kit服务器

**接口URL：** 

**数据格式：** 请求：Content-Type: application/json，响应：Content-Type: application/json

#### 请求参数

**Request Header**

| 参数 | 是否必选 | 类型 | 描述 |
| --- | --- | --- | --- |
| x-appid | 是 | String | 开发者在华为开发者联盟注册的应用编号，可从应用服务>AppGallery Connect（应用市场）>我的项目>选中应用后查看，x-appid即选项的Client ID。 |
| Authorization | 是 | String | 用于身份认证的应用级AccessToken。需通过OAuth 2.0接口获取，并在传输时使用Bearer认证方案，即在Token前添加"Bearer "前缀。（具体获取方式详见下文：x-appid和Authorization的获取步骤描述）。 |
| Content-Type | 是 | String | 固定值，填application/json。 说明： Request Body传参，请务必遵循此请求头格式，否则可能导致请求失败。 |
| Accept | 是 | String | 固定值，填application/json。 |
| x-event-type | 否 | String | 事件类型，USER表示用户事件，COMMON表示通用事件。 |

**Request Body**

| 参数 | 是否必选 | 类型 | 描述 |
| --- | --- | --- | --- |
| events | 是 | List<Object> | 详细参考请求体样例。 |
| userAgree | 是 | Boolean | 表示是否同意捐赠，若要使用该意图功能，则固定填true。 |

**请求体字段样例**

| 成员名称 | 是否必选 | 类型 | 描述 | 取值范围 |
| --- | --- | --- | --- | --- |
| requestTime | 是 | String | 请求报文的发送时间，格式：yyyyMMddhhmmssSSS（UTC）。 | 正则Pattern：[0-9]{17}。 |
| abilityId | 否 | String | 通知的服务ID。 | 最大长度：128。 |
| sid | 否 | String | 华为分配的第三方账号与华为账号的关联ID（非账号绑定场景）——openId与sid不可同时为空，至少填入一项。 | 最大长度：512。 |
| openId | 否 | String | 华为分配的第三方账号与华为账号的关联ID。事件是用户级事件时必选——openId与sid不可同时为空，至少填入一项。 | 最大长度：512。 |
| overwriteByEventName | 否 | Boolean | 是否根据事件名覆盖本用户同Ability的其他卡片。默认不覆盖。 | - |
| overwriteByAbility | 否 | Boolean | 是否覆盖本用户同Ability的其他卡片。默认为true。 | - |
| content | 否 | EventContent | 事件通知内容数据，用于判断事件有效性及事件内容展示。 | - |

**EventContent**

| 成员名称 | 是否必选 | 类型 | 描述 | 取值范围 |
| --- | --- | --- | --- | --- |
| contentData | 是 | List<ContentDataItem> | 事件内容数据列表。 | - |

**ContentDataItem**

| 成员名称 | 是否必选 | 类型 | 描述 | 取值范围 |
| --- | --- | --- | --- | --- |
| header | 是 | EventContentHeader | 内容定义信息。 | - |
| payload | 是 | EventContentPayload | 内容信息。 | - |

**EventContentHeader**

| 成员名称 | 是否必选 | 类型 | 描述 | 取值范围 |
| --- | --- | --- | --- | --- |
| namespace | 是 | String | 内容定义命名空间。 | 取固定值Intent。 |
| name | 是 | String | 意图名称。 | - |

**EventContentPayload**

| 成员名称 | 是否必选 | 类型 | 描述 | 取值范围 |
| --- | --- | --- | --- | --- |
| identifier | 是 | String | 事件的唯一标识。 | 正则Pattern：[a-zA-Z0-9-]{1,64}。 |
| intentEntityInfo | 是 | Object | 意图实体。 | 意图实体的其他信息，表示为一个或多个键值对。其中键的类型为字符，值的类型为Object，键和值的取值范围因意图名称而异，具体请参考各垂域意图Schema。 |

其中，**x-appid**和**Authorization**的获取步骤如下所述：

**x-appid**是来自于AppGallery Connect网站，可从应用服务>AppGallery Connect（应用市场）>我的项目>选中应用后查看，**x-appid**即Client ID。

**Authorization**通过调用Oauth2.0的接口获得，接口地址为：

**Request Header**

| 参数 | 是否必选 | 类型 | 描述 |
| --- | --- | --- | --- |
| Content-Type | 是 | String | 固定值，填application/x-www-form-urlencoded。 说明： Request Body传参，请务必遵循此请求头格式，否则可能导致请求失败。 |

**Request Body**

| 参数 | 是否必选 | 类型 | 描述 |
| --- | --- | --- | --- |
| grant_type | 是 | String | 固定值 client_credentials。 |
| client_id | 是 | String | 从AppGallery Connect网站查询。 |
| client_secret | 是 | String | 从AppGallery Connect网站查询。 |

请求体使用表单形式，即x-www-form-urlencoded。

#### 请求示例

完整的请求头样例如下：

```
POST /open-ability/v2/service-events/notify HTTP/1.1
Host: hag.cloud.huawei.com
Content-Type: application/json
Authorization: Bearer DQEBAGf5Mtm9rZl3W1W8sACVmWo0WhGUE3ANb/+KgRHjvmJqacjI3aF++jLEqbZsJ4H472MknoysUMaQrr8FgAHKPCU1YY4EKxUhsA==
x-appid: 1***12345
Accept: application/json
x-event-type: USER
```

以ViewRepayment意图为例，完整的请求体样例如下：

```
POST /open-ability/v2/service-events/notify HTTP/1.1
Host: hag.cloud.huawei.com
Content-Type: application/json

{
  "events": [{
    "requestTime": "20240229143501798", // 请求报文的发送时间，格式：yyyyMMddhhmmssSSS（UTC）
    "abilityId": "389ccb86317f41c19c2aa8762345069c", // 通知的服务ID
    "sid": "0bda3b89e3f44a44940eaad6b863dcc6", // 华为分配的第三方账号与华为账号的关联ID（非账号绑定场景）
    "overwriteByEventName": false, // 是否根据事件名覆盖本用户同Ability的其他卡片。默认不覆盖
    "overwriteByAbility": false, // 是否覆盖本用户同Ability的其他卡片。默认为true
    "content": { // 事件内容数据列表
      "contentData": [{ // 事件内容数据列表
        "header": { // 内容定义信息
          "namespace": "Intent", // 内容定义命名空间，填写Intent
          "name": "ViewRepayment" // 意图名称
        },
        "payload": { // 内容信息
          "identifier": "uuid", // 事件的唯一标识
          "intentEntityInfo": { // 意图实体
            "repaymentType":"CreditCard",
            "statementDate": "2023-10-01",
            "repaymentDate": "2023-10-08",
            "bankName": "xxx银行",
            "bankNameAbbreviation": "xx银行/xx行",
            "availableBeginTime": "2023-10-08T00:00:00+08:00",
            "availableEndTime": "2023-10-08T23:59:59+08:00",
            "eventStatus": "Repayment",
            "eventImage": "",
            "cardTailNumber": "1234",
            "cardType": "CreditCard"
          }
        }
      }]
    }
  }],
  "userAgree": true
}
```

#### 响应参数

**Response Header**

| 参数 | 是否必选 | 类型 | 描述 |
| --- | --- | --- | --- |
| Content-Type | 是 | String | 取值为：application/json;charset=UTF-8。 |

**Response Body**

| 参数 | 是否必选 | 类型 | 描述 |
| --- | --- | --- | --- |
| errorEvents | 否 | List<ErrorEvent> | 层级如下，详细结果见样例。 |

**ErrorEvent**

| 参数 | 是否必选 | 类型 | 描述 |
| --- | --- | --- | --- |
| requestId | 是 | String | 对应请求体中的事件identifier。 |
| resultInfo | 是 | ResultInfo | 错误详细信息。 |

**ResultInfo**

| 参数 | 是否必选 | 类型 | 描述 |
| --- | --- | --- | --- |
| code | 是 | String | 错误类型。 |
| desc | 是 | String | 错误详细描述。 |

#### 响应示例

*   调用成功，响应码为200，响应体为空。
    
*   调用失败，响应码为400，以生失效时间无效错误为例，响应体格式如下：
    
    ```
    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
      "errorEvents":  [{
        "requestId": "02240416001",
        "resultInfo": {
          "code": "invalidParam",
          "desc": "expireTime can not before nowTime"
        }
      }]
    }
    ```
    
    *   调用出错（鉴权信息无效或过期），响应码为401，响应体为空。
    *   调用出错（网关验证开发者权限失败），响应码为403，响应体为空。
    *   调用失败，响应码为404，表示外部推送的sid没有获取到对应的uid，响应体格式如下：
        
        ```
        HTTP/1.1 404 Bad Request
        Content-Type: application/json
        
        {
          "errorEvents": [{
            "requestId": "02240416001",
            "resultInfo": {
              "code": "userNotFound",
              "desc": "User is not found"
            }
          }]
        }
        ```