Skip to content

GitLab

01.Resource API · Changes

Page history
Update 门户V2 API 文档/01.Resource API authored by asdu's avatar asdu
Show whitespace changes
Inline Side-by-side
Showing with 281 additions and 0 deletions
门户V2-API-文档/01.Resource-API.md 0 → 100644
View page @ a5d800e0
## 1.1 Resource API 概述
- Resource API 是所有resource接口的统称
- Resource API 有多种设置、更新、删除接口，具体的接口如下：
- 增加单个resource
- 删除、查询、删除单个resource
- 查询用户相关的resource
- 新增reosurce接口：[https://{site}/portal/api/v2/resource/{bundle}](https://note.youdao.com/) POST
- 删除、更新、查询单个reosurce接口：[https://{site}/portal/api/v2/resource/{bundle}/{uuid}](https://note.youdao.com/) GET, PATCH, DELETE
- 查询用户相关的resource接口： [https://{site}/portal/api/v2/resource?_format=json](https://note.youdao.com/) GET
- 如需要额外接口满足项目需求，可以通过后台使用**Portal Views**配置
## 1.2.Resource API 新增单个数据
```
POST /portal/api/v2/resource/{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": "resource--news",
"attributes": {
"title": "明天召开教职工大会23image2",
"url_redirection": {"uri":"http://test.com/eww.html"},
"published_date":"2020-10-13T04:48:02+00:00",
"body":"<p>信息描述支持html</p>",
"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--resource_category", "id": "56bcc47b-9e7a-42d3-9534-fd3bd2d0e384" }
},
"field_image": {
"data": { "type": "file--file", "id": "9df7d33d-3047-4978-adba-b528272aaca4" }
},
"field_attachment": {
"data": [
{ "type": "file--file", "id": "9df7d33d-3047-4978-adba-b528272aaca4" },
{ "type": "file--file", "id": "9df7d33d-3047-4978-adba-b528272aaca4" }
]
}
}
}
}
```
## 1.2.1.Resource API 新增单个数据的请求参数
具体的字段如下：
参数名 | 类型 | 必需 | 描述
---|---|--|----|---
type | string | 是 | bundle可设置为系统默认的类型news，也可以在系统后台定义其他的类型，比如note等
title | string | 是 | 信息标题
field_access_roles | string | 否 | 可以访问资源的用户角色的，后台可配置其他角色，默认key有：anonymous、authenticated
field_department | int | 否 | 根据用户所在的部门访问次资源。具体的key，根据后台配置得到。
field_category | int | 是 | 属于具体的类别，后台可配置
field_image | init | 否 | 通过 [File API](https://note.youdao.com/) 上传文件获取image id
field_attachment | init | 否 | 通过 [File API](https://note.youdao.com/) 上传文件获取附件id
url_redirection | string | 是 | 跳转地址，
published_date | timestamp | 是 | 信息的发布时间
body | string | 否 | 描述简介
status | int | 是 | 此资源是否发布，1）如果为0，则不发，2）如果为1，则发布。
uuid | string | 否 | 防止重复提交可以使用uuid
## 1.3 更新单个数据
```
PATCH /portal/api/v2/resource/{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": "resource--{bundle}",
"id":"{uuid}"
"attributes": {
"title": "明天召开教职工大会23image2",
"url_redirection": {"uri":"http://test.com/eww.html"},
"published_date":"2020-10-13T04:48:02+00:00",
"body":"<p>信息描述支持html</p>",
"status":1
},
"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--resource_category", "id": "56bcc47b-9e7a-42d3-9534-fd3bd2d0e384" }
},
"field_image": {
"data": { "type": "file--file", "id": "9df7d33d-3047-4978-adba-b528272aaca4" }
},
"field_attachment": {
"data": [
{ "type": "file--file", "id": "9df7d33d-3047-4978-adba-b528272aaca4" },
{ "type": "file--file", "id": "9df7d33d-3047-4978-adba-b528272aaca4" }
]
}
}
}
}
```
## 1.3.1.Resource API 更新单个数据的请求参数
具体的字段如下：
参数名 | 类型 | 必需 | 描述
---|---|--|----|---
type | string | 否 | bundle可设置为系统默认的类型news，也可以在系统后台定义其他的类型，比如note等
title | string | 否 | 信息标题
field_access_roles | string | 否 | 可以访问资源的用户角色的，后台可配置其他角色，默认key有：anonymous、authenticated
field_department | int | 否 | 根据用户所在的部门访问次资源。具体的key，根据后台配置得到。
field_category | int | 否 | 属于具体的类别，后台可配置
field_image | init | 否 | 通过 [File API](https://note.youdao.com/) 上传文件获取image id
field_attachment | init | 否 | 通过 [File API](https://note.youdao.com/) 上传文件获取附件id
url_redirection | string | 否 | 跳转地址，
published_date | timestamp | 否 | 信息的发布时间
body | string | 否 | 描述简介
status | int | 否 | 此资源是否发布，1）如果为0，则不发，2）如果为1，则发布。
## 1.4. 删除单个数据
```
DELETE /portal/api/v2/resource/{bundle}/{8beb578b-7557-4656-90e8-0f12395e35a2} HTTP/1.1
Host: etl.dd:8083
Accept: application/vnd.api+json
Authorization: Bearer 49353835a83f30b26f81dc2351330a4b
```
## 1.5. 查询单个数据
```
GET /portal/api/v2/resource/{bundle}/{d1f94da3-990d-4d70-9441-a30bbed4d91e} HTTP/1.1
Host: etl.dd:8083
Authorization: Bearer 49353835a83f30b26f81dc2351330a4b
Accept: application/vnd.api+json
```
## 1.6.查询当前用户自己创建的所有数据
```
GET /portal/api/v2/resource/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={}&page={}&items_per_page={}&field_access_roles[]=stuff&field_access_roles[]=teacher&field_department_target_id[]=1&field_department_target_id[]=2
```
## 1.7.基于当前用户角色和部门授权的数据查询
```
GET /portal/api/v2/resource?_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}&page={}&items_per_page={}
```
## 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 | 否 | 授权可访问的角色，前端无需传入数值，后端根据当前用户角色自动匹配，/me 接口可传入查询
field_department | int | 否 | 授权访问的部门，签到无需传入数值，后端根据当前用户所在部门自动匹配, /me 接口可传入查询
page | int | 否 | 插叙第几页数据，默认第一页值为0，以此类推。
items_per_page | init |否|每页显示最大的items，值：5,10, 15, 20, 25, 30,35,45,50,55,60,65,70,75等. 其他需求可以在views配置。
## 1.9. 查询数据的响应信息
```
[
{
"uuid": "ac8573f0-75a4-405f-9b04-836bff7b1395",
"id": "1",
"title": "关于返校的通知",
"body": "<p>做好相关的工作</p>",
"field_attachment": "",
"field_image": "",
"field_category": "10",
"changed": "2020-07-17 12:49:18",
"created": "2020-07-17 12:45:10",
"published_date": "2020-07-17 12:28:12",
"field_department": "3, 2, 1",
"promote": "1",
"promoted_weight": "20",
"type": "news",
"sticky": "1",
"sticky_weight": "35",
"url_redirection": "http://etl.dd:8083/news",
"weight": "90",
"status": "1",
"field_access_roles": "administrator, authenticated"
},
{
"uuid": "f9ae884b-2fdc-49d8-882f-9c31de2fd3c4",
"id": "2",
"title": "开学通知",
"body": "<p>做好开学相关的准备工作</p>",
"field_attachment": "",
"field_image": "",
"field_category": "11",
"changed": "2020-07-17 12:46:38",
"created": "2020-07-17 12:46:38",
"published_date": "2020-07-17 12:28:12",
"field_department": "1",
"promote": "1",
"promoted_weight": "13",
"type": "news",
"sticky": "1",
"sticky_weight": "53",
"url_redirection": "http://etl.dd:8083/news",
"weight": "15",
"status": "1",
"field_access_roles": "administrator, anonymous, authenticated"
}
]
```
## 1.9.1.响应信息字段说明
具体的字段如下：
参数名 | 类型 | 描述
---|---|--|---
id | int | 编号
uuid | string | 唯一标识符
title | string | 根据关键字搜索相关性的数据
field_category | init | 分类id，根据后台配置确定
type | string | 可供选择值为news，其他类型可以后台配置确定
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 | 系统默认创建时间
## 1.10.错误码
融合门户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