Skip to content

GitLab

02.App API · Changes

Page history
Update 门户V2 API 文档/02.App API authored by 杜安山's avatar 杜安山
Hide whitespace changes
Inline Side-by-side
Showing with 276 additions and 0 deletions
门户V2-API-文档/02.App-API.md 0 → 100644
View page @ 7f3b9318
# 1.App API v2
## 1.1 App API 概述
- App API 是相关应用关联的接口结合
- App API 有多种设置、更新、删除接口，具体的接口如下：
- 增加单个App
- 查询、更新、删除单个App
- 查询用户相关的App
- 新增APP接口：[https://{site}/portal/v2/app/{bundle}](https://note.youdao.com/) POST
- 删除、更新、查询单个app接口：[https://{site}/portal/v2/app/{bundle}/{uuid}](https://note.youdao.com/) GET, PATCH, DELETE
- 查询基于用户角色和部门授权的相关的app接口： [https://{site}/portal/api/v2/app?_format=json](https://note.youdao.com/) GET
- 如需要额外接口满足项目需求，可以通过后台使用**Portal Views**配置
## 1.2.App API 新增单个数据
```
POST /portal/api/v2/app/{bundle} HTTP/1.1
Host: portal.xx.edu.com.cn
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Authorization: Bearer 39aec9c68b679d43de6803e0f14c223j
{
"data": {
"type": "app--{bundle}",
"attributes": {
"title": "教务系统",
"url_redirection": {"uri":"http://test.com/eww.html"},
"published_date":"2020-10-13T04:48:02+00:00",
"body":"<p>信息描述支持html</p>",
"search_keys":"图书、资料、图书馆",
"status":1,
"uuid":""
},
"relationships": {
"field_access_roles": {
"data": { "type": "user_role--user_role", "id": "b063ed18-e05f-4694-a2a3-0f2e1c584efd" }
},
"field_department": {
"data": { "type": "taxonomy_term--department", "id": "2d062779-4d71-47e1-8519-e8350659158c" }
},
"field_category": {
"data": { "type": "taxonomy_term--app_category", "id": "56bcc47b-9e7a-42d3-9534-fd3bd2d0e384" }
},
"field_icon": {
"data": { "type": "file--file", "id": "9df7d33d-3047-4978-adba-b528272aaca4" }
}
}
}
}
```
## 1.2.1.App API 新增单个数据的请求参数
具体的字段如下：
参数名 | 类型 | 必需 | 描述
---|---|--|----|---
type | string | 是 | bundle可设置为系统默认的类型news，也可以在系统后台定义其他的类型，比如note等
title | string | 是 | 信息标题
field_access_roles | string | 否 | 可以访问资源的用户角色的，默认key有：anonymous、authenticated
field_department | int | 否 | 根据用户所在的部门访问资源。具体的key，根据后台配置得到。
field_category | int | 是 | 属于具体的类别，后台可配置
url_redirection | string | 是 | 跳转地址，
published_date | timestamp | 是 | 信息的发布时间
body | string | 否 | 描述简介
status | int | 是 | 此资源是否发布，1）如果为0，则不发，2）如果为1，则发布。
field_icon | init | 是 | 通过 [File API](https://note.youdao.com/) 上传文件获取icon id
search_keys | string | 否 | 搜索关键字
uuid | string | 否 | 防止重复提交可以使用uuid
## 1.3 更新单个数据
```
PATCH /portal/api/v2/app/{bundle}/{uuid} HTTP/1.1
Host: portal.xx.edu.com.cn
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Authorization: Bearer 39aec9c68b679d43de6803e0f14c223j
{
"data": {
"type": "app--{bundle}",
"id":"{uuid}",
"attributes": {
"title": "教务系统",
"url_redirection": {"uri":"http://test.com/eww.html"},
"published_date":"2020-10-13T04:48:02+00:00",
"body":"<p>信息描述支持html</p>",
"search_keys":"图书、资料、图书馆",
"status":1,
"uuid":""
},
"relationships": {
"field_access_roles": {
"data": { "type": "user_role--user_role", "id": "b063ed18-e05f-4694-a2a3-0f2e1c584efd" }
},
"field_department": {
"data": { "type": "taxonomy_term--department", "id": "2d062779-4d71-47e1-8519-e8350659158c" }
},
"field_category": {
"data": { "type": "taxonomy_term--app_category", "id": "56bcc47b-9e7a-42d3-9534-fd3bd2d0e384" }
},
"field_icon": {
"data": { "type": "file--file", "id": "9df7d33d-3047-4978-adba-b528272aaca4" }
}
}
}
}
```
## 1.3.1.App API 更新单个数据的请求参数
具体的字段如下：
参数名 | 类型 | 必需 | 描述
---|---|--|----|---
type | string | 否 | bundle可设置为系统默认的类型news，也可以在系统后台定义其他的类型，比如note等
title | string | 否 | 信息标题
field_access_roles | string | 否 | 可以访问资源的用户角色，默认key有：anonymous、authenticated
field_department | int | 否 | 根据用户所在的部门访问次资源。具体的key，根据后台配置得到。
field_category | int | 否 | 属于具体的类别，后台可配置
url_redirection | string | 否 | 跳转地址，
published_date | timestamp | 否 | 信息的发布时间
body | string | 否 | 描述简介
status | int | 否 | 此资源是否发布，1）如果为0，则不发，2）如果为1，则发布。
field_icon | init | 否 | 通过 [File API](https://git.qtgl.com.cn/) 上传文件获取icon id
search_keys | string | 否 | 搜索关键字
uuid | string | 否 | 防止重复提交可以使用uuid
## 1.4. 删除单个数据
```
DELETE /portal/api/v2/app/{bundle}/{uuid} HTTP/1.1
Host: etl.dd:8083
Accept: application/vnd.api+json
Authorization: Bearer 49353835a83f30b26f81dc2351330a4b
```
## 1.5. 查询单个数据
```
GET /portal/api/v2/app/{bundle}/{uuid} HTTP/1.1
Host: etl.dd:8083
Authorization: Bearer 49353835a83f30b26f81dc2351330a4b
Accept: application/vnd.api+json
```
## 1.6.查询当前用户自己创建的所有数据
```
GET /portal/api/v2/app/me?_format=json HTTP/1.1
Host: portal.xx.edu.com.cn
Authorization: Bearer 39aec9c68b679d43de6803e0f14c223j
title={value}&field_category={value}&type={value}&promote={value}&sticky={value}&published_date[min]={CCYY-MM-DD HH:MM:SS}&&published_date[max]={CCYY-MM-DD HH:MM:SS}&search_keys={value}&combine={value}
```
## 1.7.基于当前用户角色和部门授权的数据查询
```
GET /portal/api/v2/app?_format=json HTTP/1.1
Host: portal.xx.edu.com.cn
Authorization: Bearer 39aec9c68b679d43de6803e0f14c223j
title={value}&field_category={value}&type={value}&promote={value}&sticky={value}&published_date[min]={CCYY-MM-DD HH:MM:SS}&&published_date[max]={CCYY-MM-DD HH:MM:SS}&search_keys={value}&combine={value}
```
## 1.8.查询数据的请求参数说明
具体的字段如下：
参数名 | 类型 | 必需 | 描述
---|---|--|----|---
title | string | 否 | 根据关键字搜索相关性的数据
field_category | init | 否 | 分类id，根据后台配置确定,多值查询: field_category[]=1&field_category[]=2
type | string | 否 | 可供选择值为news，其他类型可以后台配置确定
promote | init | 否 | 是否推荐到首页，值为1为推荐到首页，值为0不推荐到首页
sticky | int | 否 | 是否置顶， 值为1为置顶，值为0为不置顶
published_date | date | 否 | 发布时间，格式为CCYY-MM-DD HH:MM:SS
field_access_roles | string | 否 | 授权可访问的角色，前端无需传入数值，后端根据当前用户角色自动匹配
field_department | int | 否 | 授权访问的部门，签到无需传入数值，后端根据当前用户所在部门自动匹配
search_keys | int | 否 | 搜索关键字
combine | int | 否 | 组合搜索，从title、body、search_keys里搜索相关内容
## 1.9. 查询数据的响应信息
```
[
{
"uuid": "af0d266b-b1bb-404b-9337-a90e20dcca2d",
"id": "1",
"title": "图书馆",
"field_icon": "/system/files/styles/large/private/app/images/icon/Snip20200716_4.png?itok=EbGMxORR",
"type": "应用",
"field_category": "4, 5",
"field_department": "3, 2",
"sticky": "1",
"sticky_weight": "22",
"promote": "1",
"promoted_weight": "345",
"weight": "56",
"status": "1",
"created": "2020-07-17 15:20:23",
"published_date": "2020-07-17 15:19:58",
"body": "<p>图书馆的应用</p>",
"search_keys": "图书馆、图书、学校、资料",
"url_redirection": "http://etl.dd:8083/app",
"field_access_roles": "administrator, anonymous, authenticated"
}
]
```
## 1.9.1.响应信息字段说明
具体的字段如下：
参数名 | 类型 | 描述
---|---|--|----|---
id | int | 编号
uuid | string | 标识符
title | string | 根据关键字搜索相关性的数据
field_category | init | 分类id
type | string | app类型
promote | init | 是否推荐到首页，值为1为推荐到首页，值为0不推荐到首页
promoted_weight | init | 推荐到首页的item的排序
sticky | int | 是否置顶， 值为1为置顶，值为0为不置顶
sticky_weight | init | 置顶相关items的排序
published_date | date | 发布时间，格式为CCYY-MM-DD HH:MM:SS
field_access_roles | string | 授权可访问的角色的keys
field_department | int | 授权访问的部门的keys
body | int | 描述简介
field_image | int | 图片地址
field_attachment | int | 附件地址
url_redirection | int | 跳转的url
weight | int | 排序
changed | int | 更新时间
created | int | 系统默认创建时间
search_keys|string|搜索关键字
## 1.10 点击量统计
```
GET /portal/api/v2/statistics/{type}/{id}?_format=json HTTP/1.1
Host: portal.xx.edu.com.cn
Authorization: Bearer 39aec9c68b679d43de6803e0f14c223j
```
## 1.10.1 响应结果
```
{
"type": "app",
"totalcount": "3",
"daycount": "3",
"timestamp": "1600098894"
}
```
## 1.10.2 字段说明
具体的字段如下：
参数名 | 类型 | 描述
---|---|--|---
type | string | 目前支持resource实体和app实体
id | int | 统计的具体id
totalcount | int | 总共数据
daycount | int | 当天数据
timestamp | int | 最后一次刷新时间
## 1.11.错误码
融合门户REST API接口较多，开发者使用过程中不可避难会遇到各种问题，这里提供了常见的错误码释义。
错误码 | 含义
---|---
200 | OK
201 | Created
202 | Accepted
204 | No Content
301 |Moved Permanently
302 |Found
400| Bad Request
401| Unauthorized
403 |Forbidden
404 |Not Found
405 |Method Not Allowed
406 |Not Acceptable
415 |Unsupported Media Type
500 |Internal Server Error
501 |Not Implemented