02.App API

1.App API v2

1.1 App API 概述

App API 是相关应用关联的接口结合
App API 有多种设置、更新、删除接口，具体的接口如下：
- 增加单个App
- 查询、更新、删除单个App
- 查询用户相关的App
新增APP接口：https://{site}/portal/v2/app/{bundle} POST
删除、更新、查询单个app接口：https://{site}/portal/v2/app/{bundle}/{uuid} GET, PATCH, DELETE
查询基于用户角色和部门授权的相关的app接口： https://{site}/portal/api/v2/app?_format=json 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 上传文件获取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 上传文件获取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