diff --git a/SUMMARY.md b/SUMMARY.md index 286871e3..8b1da86a 100755 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -51,8 +51,14 @@ * [知晓云开放 API](open-api/README.md) * [授权认证](open-api/authentication.md) - * [数据表模块](open-api/record.md) - * [内容模块](open-api/content.md) + * [数据模块](open-api/data/README.md) + * [数据表操作](open-api/data/table.md) + * [数据操作](open-api/data/record.md) + * [内容模块](open-api/content/README.md) + * [内容库操作](open-api/content/content-group.md) + * [内容分类操作](open-api/content/content-category.md) + * [内容操作](open-api/content/content.md) + * [内容操作(不建议使用)](open-api/content-abandoned.md) * [文件模块](open-api/file/README.md) * [文件上传](open-api/file/file-upload.md) * [文件操作](open-api/file/file.md) @@ -65,6 +71,27 @@ ---- +* [知晓云运营 API](user-dash/README.md) + * [授权认证](user-dash/authentication.md) + * [数据模块](user-dash/data/README.md) + * [数据表操作](user-dash/data/table.md) + * [数据操作](user-dash/data/record.md) + * [内容模块](user-dash/content/README.md) + * [内容库操作](user-dash/content/content-group.md) + * [内容分类操作](user-dash/content/content-category.md) + * [内容操作](user-dash/content/content.md) + * [文件模块](user-dash/file/README.md) + * [文件上传](user-dash/file/file-upload.md) + * [文件操作](user-dash/file/file.md) + * [文件分类操作](user-dash/file/file-category.md) + * [分组模块](user-dash/group/README.md) + * [用户组操作](user-dash/group/user-group.md) + * [用户组与用户的操作](user-dash/group/membership.md) + * [组集操作](user-dash/group/super-group.md) + * [用户模块](user-dash/user.md) + +---- + * [管理与支持](support/README.md) * [常见问题](support/qA.md) * [服务协议](support/terms.md) diff --git a/open-api/content/README.md b/open-api/content/README.md new file mode 100644 index 00000000..543b194e --- /dev/null +++ b/open-api/content/README.md @@ -0,0 +1,9 @@ + + +# 内容模块 + +支持了内容库、内容分类和内容的创建、编辑和删除等操作，同时内容接口支持自定义字段数据的获取与修改。 + +* [内容库操作](./content-group.md) +* [内容分类操作](./content-category.md) +* [内容操作](./content.md) diff --git a/open-api/content.md b/open-api/content/content-abandoned.md similarity index 98% rename from open-api/content.md rename to open-api/content/content-abandoned.md index 8f3487ad..0583d5e0 100644 --- a/open-api/content.md +++ b/open-api/content/content-abandoned.md @@ -1,5 +1,8 @@ # 内容操作 +> **danger** +> 以下操作不支持内容表自定义字段的获取，建议使用[内容操作](./content.md)接口。 + ## 内容库 ### 获取内容库详情 @@ -418,4 +421,4 @@ request(opt, function(err, res, body) { } ] } -``` \ No newline at end of file +``` diff --git a/open-api/content/content-category.md b/open-api/content/content-category.md new file mode 100644 index 00000000..21d9a717 --- /dev/null +++ b/open-api/content/content-category.md @@ -0,0 +1,271 @@ +# 内容分类操作 + +## 获取内容分类详情 + +**接口** + +`GET https://cloud.minapp.com/oserve/v1/content/:content_group_id/category/:category_id/` + +其中 `content_group_id` 是内容库的 ID, `category_id` 是内容分类的 ID + +**代码示例** + +{% tabs getContentCategoryCurl="Curl"%} + +{% content "getContentCategoryCurl" %} + +``` +curl -X GET \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/oserve/v1/content/1/category/1/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "id": 1, + "name": "category", + "parent": null, + "subcategories": [ + { + "id": 2, + "name": "subcategory", + "parent": { + "id": 1, + "name": "category" + }, + "subcategories": [], + "created_at": 1519901783, + "updated_at": 1519901783 + } + ], + "created_at": 1516963449, + "updated_at": 1516963449 +} +``` + +**返回参数说明** + +| 参数 | 说明 | +| :--- | :-- | +| id | 分类 ID | +| name | 分类名称 | +| parent | 分类的父类 | +| subcategories | 子类名称 | +| created_at | 分类创建时间 | +| updated_at | 分类更新时间 | + +## 获取内容分类列表 + +**接口** + +`GET https://cloud.minapp.com/oserve/v1/content/1/category/1/` + +**提交参数** + +- parent 内容分类父分类列表查询 + + `https://cloud.minapp.com/oserve/v1/content/:content_id/category/?parent__isnull=true` + +- name 内容分类名称的等值查询 + + `https://cloud.minapp.com/oserve/v1/content/:content_id/category/?name=category` + + +**代码示例** + +{% tabs getContentCategoryListCurl="Curl"%} + +{% content "getContentCategoryListCurl" %} + +``` +curl -X GET \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/oserve/v1/content/1/category/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "meta": { + "limit": 20, + "next": null, + "offset": 0, + "previous": null, + "total_count": 2 + }, + "objects": [ + { + "id": 1, + "name": "category", + "parent": null, + "subcategories": [ + { + "id": 2, + "name": "subcategory", + "parent": { + "id": 1, + "name": "category" + }, + "subcategories": [], + "created_at": 1519901783, + "updated_at": 1519901783 + } + ], + "created_at": 1516963449, + "updated_at": 1516963449 + }, + { + "id": 2, + "name": "subcategory", + "parent": { + "id": 1516963449144537, + "name": "category" + }, + "subcategories": [], + "created_at": 1519901783, + "updated_at": 1519901783 + } + ] +} +``` + +## 创建内容分类 + +**接口** + +`POST https://cloud.minapp.com/oserve/v1/content/` + +**参数说明** + +Content-Type: `application/json` + +| 参数 | 类型 | 必填 | 说明 | +| :--- | :----- | :-- | :-- | +| name | String | Y | 分类名称 | +| parent | Number | N | 父分类 ID | + +> **warning** +> 注意：最多只允许三层嵌套分类 + +**代码示例** + +{% tabs createContentCategoryCurl="Curl"%} + +{% content "createContentCategoryCurl" %} + +``` +curl -X POST \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +-d '{ + "name": "分类1", + }' \ +https://cloud.minapp.com/oserve/v1/content/1/category/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "id": 3, + "name": "分类1", + "parent": null, + "subcategories": [], + "created_at": 1519910966, + "updated_at": 1519910966 +} +``` + +**状态码说明** + +`201`: 创建成功 + +`400`: 同一父分类下的子分类名不能相同 + +`404`: 父分类 ID 不合法 + + +## 编辑内容分类 + +**接口** + +`PUT https://cloud.minapp.com/oserve/v1/content/:content_group_id/catgegory/:category_id/` + + +**代码示例** + +{% tabs updateContentCategoryCurl="Curl"%} + +{% content "updateContentCategoryCurl" %} + +``` +curl -X PUT \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +-d '{ + "name": "Test Category" + }' \ +https://cloud.minapp.com/oserve/v1/content/1/category/3/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "id": 3, + "name": "Test Category", + "parent": null, + "subcategories": [], + "created_at": 1519910966, + "updated_at": 1519910966 +} +``` + +**状态码说明** + +`200`: 修改成功 + +`400`: 同一父分类下的子分类名不能相同 + +`404`: 父分类 ID 不合法 + + +## 删除内容库 + +**接口** + +`DELETE https://cloud.minapp.com/oserve/v1/content/:content_group_id/category/:category_id/` + + +**代码示例** + +{% tabs deleteContentCategoryCurl="Curl"%} + +{% content "deleteContentCategoryCurl" %} + +``` +curl -X DELETE \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/oserve/v1/content/1/category/1/ +``` + +{% endtabs %} + + +**状态码说明** + +`204`: 删除成功 diff --git a/open-api/content/content-group.md b/open-api/content/content-group.md new file mode 100644 index 00000000..71c46a3f --- /dev/null +++ b/open-api/content/content-group.md @@ -0,0 +1,214 @@ +# 内容库操作 + +## 获取内容库详情 + +**接口** + +`GET https://cloud.minapp.com/oserve/v1/content/:content_group_id/` + +其中 `content_group_id` 是内容库的 ID + +**代码示例** + +{% tabs getContentGroupCurl="Curl"%} + +{% content "getContentGroupCurl" %} + +``` +curl -X GET \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/oserve/v1/content/1/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "id": 1, + "name": "内容库", + "acl_gids": [], + "created_at": 1489137188, + "updated_at": 1495769882 +} +``` + +## 获取内容库列表 + +**接口** + +`GET https://cloud.minapp.com/oserve/v1/content/` + +**提交参数** + +- name 内容库名称等值查询查询 + + 例：查询内容库名称为 "内容库1" 的内容库 + + `https://cloud.minapp.com/oserve/v1/content/?name=内容库1` + + + +**代码示例** + +{% tabs getContentGroupListCurl="Curl"%} + +{% content "getContentGroupListCurl" %} + +``` +curl -X GET \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/oserve/v1/content/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "meta": { + "limit": 20, + "next": null, + "offset": 0, + "previous": null, + "total_count": 1 + }, + "objects": [ + { + "id": 1, + "name": "内容库", + "acl_gids": [], + "created_at": 1489137188, + "updated_at": 1495769882 + } + ] +} +``` + +## 创建内容库 + +**接口** + +`POST https://cloud.minapp.com/oserve/v1/content/` + +**参数说明** + +Content-Type: `application/json` + +| 参数 | 类型 | 必填 | 说明 | +| :--- | :----- | :-- | :-- | +| name | String | Y | 内容库名称 | +| acl_gids | Number Array | N | 用户的访问权限，其内为分组 ID | + +**代码示例** + +{% tabs createContentGroupCurl="Curl"%} + +{% content "createContentGroupCurl" %} + +``` +curl -X POST \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +-d '{ + "name": "Content Group", + "acl_gids": [1, 2] + }' \ +https://cloud.minapp.com/oserve/v1/content/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "id": 2, + "name": "Content Group", + "acl_gids": [1, 2], + "created_at": 1489137188, + "updated_at": 1495769882 +} +``` + +**状态码说明** + +`201`: 创建成功 + +`404`: 用户组 ID 不合法 + + +## 编辑内容库 + +**接口** + +`PUT https://cloud.minapp.com/oserve/v1/content/:content_group_id/` + + +**代码示例** + +{% tabs updateContentGroupCurl="Curl"%} + +{% content "updateContentGroupCurl" %} + +``` +curl -X PUT \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +-d '{ + "name": "Test Group" + }' \ +https://cloud.minapp.com/oserve/v1/content/2/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "id": 2, + "name": "Test Group", + "acl_gids": [1, 2], + "created_at": 1489137188, + "updated_at": 1495769882 +} +``` + +**状态码说明** + +`200`: 修改成功 + +`404`: 用户组 ID 不合法 + + +## 删除内容库 + +**接口** + +`DELETE https://cloud.minapp.com/oserve/v1/content/:content_group_id/` + + +**代码示例** + +{% tabs deleteContentGroupCurl="Curl"%} + +{% content "deleteContentGroupCurl" %} + +``` +curl -X DELETE \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/oserve/v1/content/2/ +``` + +{% endtabs %} + + +**状态码说明** + +`204`: 删除成功 diff --git a/open-api/content/content.md b/open-api/content/content.md new file mode 100644 index 00000000..b132b092 --- /dev/null +++ b/open-api/content/content.md @@ -0,0 +1,250 @@ +# 内容操作 + +本文档介绍了内容的获取（包括内容表的自定义字段）和内容的创建、编辑和删除等操作 + +## 获取内容详情 + +**接口** + +`GET https://cloud.minapp.com/oserve/v1/content/:content_group_id/text/:text_id/` + +其中 `content_group_id` 是内容库的 ID, `text_id` 是内容的 ID + +**代码示例** + +{% tabs getRichTextEntryCurl="Curl"%} + +{% content "getRichTextEntryCurl" %} + +``` +curl -X GET \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/oserve/v1/content/1/text/1/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "id": 1, + "title": "Title", + "content": "", + "cover": null, + "description": "", + "group_id": 1, + "categories": [ + { + "id": 1, + "name": "category", + "parent": null + } + ], + "created_at": 1516950540, + "updated_at": 1517800400 +} +``` + +**返回参数说明** + +| 参数 | 说明 | +| :--- | :-- | +| id | 内容 ID | +| title | 内容标题 | +| content | 详细容 | +| cover | 封面图 | +| description | 内容摘要 | +| group_id | 内容库 ID | +| categories | 内容所属分类 | +| created_at | 内容创建时间 | +| updated_at | 内容更新时间 | + +## 获取内容列表 + +**接口** + +`GET https://cloud.minapp.com/oserve/v1/content/1/text/` + +**提交参数** + +内容查询与[数据表接口](../record.md)查询保持一致 + +**代码示例** + +{% tabs getRichTextEntryListCurlCurl="Curl"%} + +{% content "getRichTextEntryListCurlCurl" %} + +``` +curl -X GET \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/oserve/v1/content/1/text/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "meta": { + "limit": 20, + "next": null, + "offset": 0, + "previous": null, + "total_count": 1 + }, + "objects": [ + { + "id": 1, + "title": "Title", + "content": "", + "cover": null, + "description": "", + "group_id": 1, + "categories": [ + { + "id": 1, + "name": "category", + "parent": null + } + ], + "created_at": 1516950540, + "updated_at": 1517800400 + } + ] +} +``` + +## 创建内容分类 + +**接口** + +`POST https://cloud.minapp.com/oserve/v1/content/:content_group_id/text/` + +**参数说明** + +Content-Type: `application/json` + +内容的内置字段 ＋ 自定义字段，参数格式将与[数据表接口](../record.md)保持一致 + + +> **warning** +> 字段 group_id 将会被接口自动赋值，所以即使提交的数据中有 group_id 也将会被覆盖 + + +**代码示例** + +{% tabs createRichTextEntryCurl="Curl"%} + +{% content "createRichTextEntryCurl" %} + +``` +curl -X POST \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +-d '{"title": "Test Title"}' \ +https://cloud.minapp.com/oserve/v1/content/1/text/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "id": 2, + "title": "Test Title", + "group_id": 1, + "categories": [], + "created_at": 1519960085, + "updated_at": 1519960085 +} +``` + + +> **info** +> 在发送创建内容的请求没有对一些内置字段如 content、description 或自定义字段赋值时，接口返回的字段将不会包含这些未被赋值的字段；若希望接口返回所有的字段，可以在创建内容的请求中携带所有的字段； + +> **info** +> 接口会根据字段在数据表中定义的类型对提交的数据进行强类型的判断，提交的数据类型不合法，接口将会过滤掉这些字段，只存储合法的字段 + +**状态码说明** + +`201`: 创建成功 + +`400`: 提交数据为空；提交的数据都不合法 + + +## 编辑内容分类 + +**接口** + +`PUT https://cloud.minapp.com/oserve/v1/content/:content_group_id/text/:text_id/` + + +**代码示例** + +{% tabs updateRichTextEntryCurl="Curl"%} + +{% content "updateRichTextEntryCurl" %} + +``` +curl -X PUT \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +-d '{"name": "Test Category"}' \ +https://cloud.minapp.com/oserve/v1/content/1/text/2/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "id": 2, + "title": "Test Title", + "group_id": 1, + "categories": [], + "created_at": 1519960085, + "updated_at": 1519960085 +} +``` + +**状态码说明** + +`200`: 修改成功 + +`400`: 提交数据为空；提交的数据都不合法 + + +## 删除内容库 + +**接口** + +`DELETE https://cloud.minapp.com/oserve/v1/content/:content_group_id/text/:text_id/` + + +**代码示例** + +{% tabs deleteRichTextEntryCurl="Curl"%} + +{% content "deleteRichTextEntryCurl" %} + +``` +curl -X DELETE \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/oserve/v1/content/1/text/1/ +``` + +{% endtabs %} + + +**状态码说明** + +`204`: 删除成功 diff --git a/open-api/data/README.md b/open-api/data/README.md new file mode 100644 index 00000000..3b6fd9d2 --- /dev/null +++ b/open-api/data/README.md @@ -0,0 +1,6 @@ + + +# 数据模块 + +* [数据表操作](./table.md) +* [数据操作](./record.md) diff --git a/open-api/record.md b/open-api/data/record.md similarity index 97% rename from open-api/record.md rename to open-api/data/record.md index 5f28697e..d988b75c 100644 --- a/open-api/record.md +++ b/open-api/data/record.md @@ -1,5 +1,7 @@ # 数据操作 +获得数据表数据接口，支持对**内置表自定义字段的获取与修改** + ## 查询数据 **接口** @@ -15,7 +17,7 @@ Content-Type: `application/json` | 参数 | 类型 | 必填 | 说明 | | :------- | :----- | :-- | :-- | | where | String | N | 查询语句，参数值应经过 JSON 编码为 JSONString 后，再经过 URL 编码 | -| order_by | String | N | 对资源进行排序字段 | +| order_by | String | N | 对资源进行字段排序 | | limit | Number | N | 限制返回资源的个数，默认为 20 条，最大可设置为 1000 | | offset | Number | N | 设置返回资源的起始偏移值，默认为 0 | @@ -340,7 +342,7 @@ request(opt, function(err, res, body) { ## 数据原子性更新 -当请求同时对一个数据进行修改时，原子性更新使得冲突和覆盖导致的数据不正确的情况不会出现，目前支持的数据类型是**数字类型**和**数字类型** +当请求同时对一个数据进行修改时，原子性更新使得冲突和覆盖导致的数据不正确的情况不会出现，目前支持的数据类型是**数字类型**和**数组类型** **接口** @@ -450,4 +452,4 @@ request(opt, function(err, res, body) { **状态码说明** -`200` 更新成功，`400` 操作符不支持/请求参数有错 \ No newline at end of file +`200` 更新成功，`400` 操作符不支持/请求参数有错 diff --git a/open-api/data/table.md b/open-api/data/table.md new file mode 100644 index 00000000..596f9d96 --- /dev/null +++ b/open-api/data/table.md @@ -0,0 +1,405 @@ +# 数据表操作 + +## 创建数据表 + +**接口** + +`POST https://cloud.minapp.com/oserve/v1/table/` + +**提交参数** + +| 参数 | 类型 | 必填 | 说明 | +| :--- | :-- | :-- | :-- | +| name | String(32) | 是 | 数据表名（表名必须是以字母开头，字母、数字、下划线的组合) | +| schema | Object | 是 | 数据表字段的元信息 | +| row_read_perm | String Array | 是 | 数据表行的读权限 | +| row_write_perm | String Array | 是 | 数据表行的写权限 | +| write_perm | String Array | 是 | 数据表的写权限 | + +参数 row_read_perm 和 row_write_perm 控制数据表数据的读写权限，读权限表示用户是否有权限获取数据，写权限表示用户是否有权限更新数据。 + +参数 write_perm 控制数据表的写权限，即表示用户是否有权限创建数据。 + +权限参数的说明： + +| 参数 | 类型 | 说明 | +| :--- | :-- | :-- | +| user:* | String| 所有人可写／可读 | +| user:<:user_id> | String| 某个用户可写／可读 | +| gid:<:group_id> | String| 某个分组下的用户可写／可读 | + +具体描述与使用场景可参考[ACL 访问控制列表][../dashboard/acl.md]。 + +参数 schema 用于存储数据表字段的元信息，其结构遵循[JSON-Table-Schema][https://frictionlessdata.io/specs/table-schema/]的描述。 + +例： + +```python +{ + "fields": [ + { + "name": "field_name", + "type": "string", + "description": "description of field_name", + "constraints": { + "required": true # 设置写入/更新必填选项 + }, + "default": "hello, world", # 设置默认值 + "acl": { + "clientVisibile": true, # 设置客户端可见 + "clientReadOnly": true, # 设置客户端只读 + "creatorVisible": true # 设置创建者可见 + } + } + ] +} +``` + +数据表列的元信息： + +| 属性 | 类型 | 必填 | 说明 | +| :--- | :-- | :-- | :-- | +| name | String(32) | 是 | 字段名（名称必须是以字母开头，字母、数字、下划线的组合) | +| type | String | 是 | 字段类型，可选：string、integer、number、boolean、array、geojson、file、date 等 | +| items | Object | 否 | 列表元素类型，array 字段类型必填, 可选 string、integer、number、boolean 等 | +| format | String | 否 | geojson 字段类型必填 | +| coordinate_type | String | 否 | 若创建 geojson 类型的字段，geojson 字段类型必填，地球坐标：wgs84，火星坐标：gcj02 | +| description | String | 否 | 字段的描述，不填自动赋值为字段名称 | +| constraints | Object | 否 | 字段的约束属性，仅支持 required 属性 | +| default | 根据字段类型变化 | 否 | 字段的默认值 | +| acl | Object | 否 | 字段权限相关的属性 | + +若字段是 array 类型，字段元信息为： + +```json +{ + "name": "array_field", + "type": "array", + "items": { + "type": "string" + } +} +``` + +若字段是 geojson 类型，字段元信息为： + +```json +{ + "name": "location", + "type": "geojson", + "format": "default", + "coordinate_type": "gcj02" +} +``` + +字段权限相关的属性存储在 acl 中： + +| 属性 | 类型 | 必填 | 说明 | +| :--- | :-- | :-- | :-- | +| clientVisibile | Boolean | 否 | 客户端只读的标志位，true 表示字段在客户端只读，不能被写入／更新 | +| clientReadOnly | Boolean | 否 | 客户端可见的标志位， false 表示字段在客户端不可见 | +| creatorVisible | Boolean | 否 | 客户端创建者可见的标志位，true 表示字段在客户端只有创建者可见 | + +**代码示例** + +{% tabs getTableListCurl="Curl"%} + +{% content "getTableListCurl" %} + +``` +curl -X POST \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +-d '{ + "name": "Table199", + "schema": { + "fields": [ + { + "name": "String", + "type": "string" + } + ] + }, + "row_read_perm": ["user:*"], + "row_write_perm": ["user:*"], + "write_perm": ["user:*"] + }' \ +https://cloud.minapp.com/oserve/v1/table/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "id": 1, + "name": "Table", + "is_protected": false, + "protected_fields": null, + "schema": { + "fields": [ + { + "description": "id", + "name": "id", + "type": "id" + }, + { + "description": "created_by", + "name": "created_by", + "type": "integer" + }, + { + "description": "created_at", + "name": "created_at", + "type": "integer" + }, + { + "description": "updated_at", + "name": "updated_at", + "type": "integer" + }, + { + "name": "String", + "type": "string", + "description": "string", + } + ] + }, + "write_perm": [ + "user:*" + ], + "default_row_perm": { + "_read_perm": [ + "user:*" + ], + "_write_perm": [ + "user:*" + ] + }, + "created_at": 1519538564, + "updated_at": 1519640477 +} +``` + +> **info** +> 字段如 id、created_by、created_at、updated_at 为自动添加的内置字段 + +**返回参数说明** + +| 参数 | 类型 | 说明 | +| :--- | :-- | :-- | +| id | Number | 数据表 ID | +| name | String| 数据表名 | +| is_protected | Boolean | 数据表是否为内置表的标志位，true 为内置表 | +| protected_fields | String Array | 内置表的保护字段，若数据表不是内置表，该字段为 null | +| schema | Object | 数据表字段的元信息 | +| write_perm | String Array | 数据表写权限 | +| default_row_perm | Object | 数据表行数据权限 | +| created_at | Number | 数据表创建时间 | +| updated_at | Number | 数据表更新时间 | + +**状态码说明** + +`201`: 修改成功 + +`400`: 表名已存在；不合法的数据 + + +## 获取数据表详情 + +**接口** + +`GET https://cloud.minapp.com/oserve/v1/table/:table_id/` + +**代码示例** + +{% tabs getTableCurl="Curl"%} + +{% content "getTableCurl" %} + +``` +curl -X GET \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/oserve/v1/table/1/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "id": 1, + "name": "Table", + "is_protected": false, + "protected_fields": null, + "schema": { + "fields": [ + { + "name": "String", + "type": "string" + } + ] + }, + "write_perm": [ + "user:*" + ], + "default_row_perm": { + "_read_perm": [ + "user:*" + ], + "_write_perm": [ + "user:*" + ] + }, + "created_at": 1519538564, + "updated_at": 1519640477 +} +``` + +**状态码说明** + +`200`: 成功 + + +## 获取数据表列表 + +**接口** + +`GET https://cloud.minapp.com/oserve/v1/table/` + +**提交参数** + +- name 支持对数据表名的等值查询 + +`https://cloud.minapp.com/oserve/v1/table/?name=Table` + +**代码示例** + +{% tabs getTableListCurl="Curl"%} + +{% content "getTableListCurl" %} + +``` +curl -X GET \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/oserve/v1/table/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "meta": { + "limit": 20, + "next": null, + "offset": 0, + "previous": null, + "total_count": 1 + }, + "objects": [ + { + "id": 1, + "is_protected": false, + "name": "Table", + "protected_fields": null, + "schema": { + "fields": [ + { + "name": "String", + "type": "string" + } + ] + }, + "write_perm": [ + "user:*" + ], + "default_row_perm": { + "_read_perm": [ + "user:*" + ], + "_write_perm": [ + "user:*" + ] + }, + "created_at": 1519538564, + "updated_at": 1519640477 + } + ] +} +``` + +**状态码说明** + +`200`: 成功 + + +## 更新数据表 + +**接口** + +`PUT https://cloud.minapp.com/oserve/v1/table/:table_id/` + +> **info** +> 数据表更新接口支持一次更新一个或多个字段 + +**代码示例** + +{% tabs getTableCurl="Curl"%} + +{% content "getTableCurl" %} + +``` +curl -X PUT \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +-d '{ + "name": "table" + }' \ +https://cloud.minapp.com/oserve/v1/table/1/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "id": 1, + "name": "table", + "is_protected": false, + "protected_fields": null, + "schema": { + "fields": [ + { + "name": "String", + "type": "string" + } + ] + }, + "write_perm": [ + "user:*" + ], + "default_row_perm": { + "_read_perm": [ + "user:*" + ], + "_write_perm": [ + "user:*" + ] + }, + "created_at": 1519538564, + "updated_at": 1519640477 +} +``` + +**状态码说明** + +`200`: 修改成功 + +`400`: 表名已存在；不合法的数据 diff --git a/user-dash/README.md b/user-dash/README.md new file mode 100644 index 00000000..091e9da7 --- /dev/null +++ b/user-dash/README.md @@ -0,0 +1,7 @@ + + +# 知晓云运营 API + +知晓云支持开发者结合 User Dash API 按需编写一套独立的运营后台，供并非开发者的用户使用。 + +若遇到问题，请联系 或者客服（微信号：minsupport） diff --git a/user-dash/authentication.md b/user-dash/authentication.md new file mode 100644 index 00000000..61e4a839 --- /dev/null +++ b/user-dash/authentication.md @@ -0,0 +1 @@ +# 授权认证（待补充） diff --git a/user-dash/content/README.md b/user-dash/content/README.md new file mode 100644 index 00000000..543b194e --- /dev/null +++ b/user-dash/content/README.md @@ -0,0 +1,9 @@ + + +# 内容模块 + +支持了内容库、内容分类和内容的创建、编辑和删除等操作，同时内容接口支持自定义字段数据的获取与修改。 + +* [内容库操作](./content-group.md) +* [内容分类操作](./content-category.md) +* [内容操作](./content.md) diff --git a/user-dash/content/content-category.md b/user-dash/content/content-category.md new file mode 100644 index 00000000..e054276d --- /dev/null +++ b/user-dash/content/content-category.md @@ -0,0 +1,271 @@ +# 内容分类操作 + +## 获取内容分类详情 + +**接口** + +`GET https://cloud.minapp.com/userve/v1/content/:content_group_id/category/:category_id/` + +其中 `content_group_id` 是内容库的 ID, `category_id` 是内容分类的 ID + +**代码示例** + +{% tabs getContentCategoryCurl="Curl"%} + +{% content "getContentCategoryCurl" %} + +``` +curl -X GET \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/userve/v1/content/1/category/1/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "id": 1, + "name": "category", + "parent": null, + "subcategories": [ + { + "id": 2, + "name": "subcategory", + "parent": { + "id": 1, + "name": "category" + }, + "subcategories": [], + "created_at": 1519901783, + "updated_at": 1519901783 + } + ], + "created_at": 1516963449, + "updated_at": 1516963449 +} +``` + +**返回参数说明** + +| 参数 | 说明 | +| :--- | :-- | +| id | 分类 ID | +| name | 分类名称 | +| parent | 分类的父类 | +| subcategories | 子类名称 | +| created_at | 分类创建时间 | +| updated_at | 分类更新时间 | + +## 获取内容分类列表 + +**接口** + +`GET https://cloud.minapp.com/userve/v1/content/1/category/1/` + +**提交参数** + +- parent 内容分类父分类列表查询 + + `https://cloud.minapp.com/userve/v1/content/:content_id/category/?parent__isnull=true` + +- name 内容分类名称的等值查询 + + `https://cloud.minapp.com/userve/v1/content/:content_id/category/?name=category` + + +**代码示例** + +{% tabs getContentCategoryListCurl="Curl"%} + +{% content "getContentCategoryListCurl" %} + +``` +curl -X GET \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/userve/v1/content/1/category/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "meta": { + "limit": 20, + "next": null, + "offset": 0, + "previous": null, + "total_count": 2 + }, + "objects": [ + { + "id": 1, + "name": "category", + "parent": null, + "subcategories": [ + { + "id": 2, + "name": "subcategory", + "parent": { + "id": 1, + "name": "category" + }, + "subcategories": [], + "created_at": 1519901783, + "updated_at": 1519901783 + } + ], + "created_at": 1516963449, + "updated_at": 1516963449 + }, + { + "id": 2, + "name": "subcategory", + "parent": { + "id": 1516963449144537, + "name": "category" + }, + "subcategories": [], + "created_at": 1519901783, + "updated_at": 1519901783 + } + ] +} +``` + +## 创建内容分类 + +**接口** + +`POST https://cloud.minapp.com/userve/v1/content/` + +**参数说明** + +Content-Type: `application/json` + +| 参数 | 类型 | 必填 | 说明 | +| :--- | :----- | :-- | :-- | +| name | String | Y | 分类名称 | +| parent | Number | N | 父分类 ID | + +> **warning** +> 注意：最多只允许三层嵌套分类 + +**代码示例** + +{% tabs createContentCategoryCurl="Curl"%} + +{% content "createContentCategoryCurl" %} + +``` +curl -X POST \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +-d '{ + "name": "分类1", + }' \ +https://cloud.minapp.com/userve/v1/content/1/category/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "id": 3, + "name": "分类1", + "parent": null, + "subcategories": [], + "created_at": 1519910966, + "updated_at": 1519910966 +} +``` + +**状态码说明** + +`201`: 创建成功 + +`400`: 同一父分类下的子分类名不能相同 + +`404`: 父分类 ID 不合法 + + +## 编辑内容分类 + +**接口** + +`PUT https://cloud.minapp.com/userve/v1/content/:content_group_id/catgegory/:category_id/` + + +**代码示例** + +{% tabs updateContentCategoryCurl="Curl"%} + +{% content "updateContentCategoryCurl" %} + +``` +curl -X PUT \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +-d '{ + "name": "Test Category" + }' \ +https://cloud.minapp.com/userve/v1/content/1/category/3/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "id": 3, + "name": "Test Category", + "parent": null, + "subcategories": [], + "created_at": 1519910966, + "updated_at": 1519910966 +} +``` + +**状态码说明** + +`200`: 修改成功 + +`400`: 同一父分类下的子分类名不能相同 + +`404`: 父分类 ID 不合法 + + +## 删除内容库 + +**接口** + +`DELETE https://cloud.minapp.com/userve/v1/content/:content_group_id/category/:category_id/` + + +**代码示例** + +{% tabs deleteContentCategoryCurl="Curl"%} + +{% content "deleteContentCategoryCurl" %} + +``` +curl -X DELETE \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/userve/v1/content/1/category/1/ +``` + +{% endtabs %} + + +**状态码说明** + +`204`: 删除成功 diff --git a/user-dash/content/content-group.md b/user-dash/content/content-group.md new file mode 100644 index 00000000..e72f0b32 --- /dev/null +++ b/user-dash/content/content-group.md @@ -0,0 +1,214 @@ +# 内容库操作 + +## 获取内容库详情 + +**接口** + +`GET https://cloud.minapp.com/userve/v1/content/:content_group_id/` + +其中 `content_group_id` 是内容库的 ID + +**代码示例** + +{% tabs getContentGroupCurl="Curl"%} + +{% content "getContentGroupCurl" %} + +``` +curl -X GET \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/userve/v1/content/1/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "id": 1, + "name": "内容库", + "acl_gids": [], + "created_at": 1489137188, + "updated_at": 1495769882 +} +``` + +## 获取内容库列表 + +**接口** + +`GET https://cloud.minapp.com/userve/v1/content/` + +**提交参数** + +- name 内容库名称等值查询查询 + + 例：查询内容库名称为 "内容库1" 的内容库 + + `https://cloud.minapp.com/userve/v1/content/?name=内容库1` + + + +**代码示例** + +{% tabs getContentGroupListCurl="Curl"%} + +{% content "getContentGroupListCurl" %} + +``` +curl -X GET \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/userve/v1/content/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "meta": { + "limit": 20, + "next": null, + "offset": 0, + "previous": null, + "total_count": 1 + }, + "objects": [ + { + "id": 1, + "name": "内容库", + "acl_gids": [], + "created_at": 1489137188, + "updated_at": 1495769882 + } + ] +} +``` + +## 创建内容库 + +**接口** + +`POST https://cloud.minapp.com/userve/v1/content/` + +**参数说明** + +Content-Type: `application/json` + +| 参数 | 类型 | 必填 | 说明 | +| :--- | :----- | :-- | :-- | +| name | String | Y | 内容库名称 | +| acl_gids | Number Array | N | 用户的访问权限，其内为分组 ID | + +**代码示例** + +{% tabs createContentGroupCurl="Curl"%} + +{% content "createContentGroupCurl" %} + +``` +curl -X POST \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +-d '{ + "name": "Content Group", + "acl_gids": [1, 2] + }' \ +https://cloud.minapp.com/userve/v1/content/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "id": 2, + "name": "Content Group", + "acl_gids": [1, 2], + "created_at": 1489137188, + "updated_at": 1495769882 +} +``` + +**状态码说明** + +`201`: 创建成功 + +`404`: 用户组 ID 不合法 + + +## 编辑内容库 + +**接口** + +`PUT https://cloud.minapp.com/userve/v1/content/:content_group_id/` + + +**代码示例** + +{% tabs updateContentGroupCurl="Curl"%} + +{% content "updateContentGroupCurl" %} + +``` +curl -X PUT \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +-d '{ + "name": "Test Group" + }' \ +https://cloud.minapp.com/userve/v1/content/2/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "id": 2, + "name": "Test Group", + "acl_gids": [1, 2], + "created_at": 1489137188, + "updated_at": 1495769882 +} +``` + +**状态码说明** + +`200`: 修改成功 + +`404`: 用户组 ID 不合法 + + +## 删除内容库 + +**接口** + +`DELETE https://cloud.minapp.com/userve/v1/content/:content_group_id/` + + +**代码示例** + +{% tabs deleteContentGroupCurl="Curl"%} + +{% content "deleteContentGroupCurl" %} + +``` +curl -X DELETE \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/userve/v1/content/2/ +``` + +{% endtabs %} + + +**状态码说明** + +`204`: 删除成功 diff --git a/user-dash/content/content.md b/user-dash/content/content.md new file mode 100644 index 00000000..04a9a728 --- /dev/null +++ b/user-dash/content/content.md @@ -0,0 +1,250 @@ +# 内容操作 + +本文档介绍了内容的获取（包括内容表的自定义字段）和内容的创建、编辑和删除等操作 + +## 获取内容详情 + +**接口** + +`GET https://cloud.minapp.com/userve/v1/content/:content_group_id/text/:text_id/` + +其中 `content_group_id` 是内容库的 ID, `text_id` 是内容的 ID + +**代码示例** + +{% tabs getRichTextEntryCurl="Curl"%} + +{% content "getRichTextEntryCurl" %} + +``` +curl -X GET \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/userve/v1/content/1/text/1/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "id": 1, + "title": "Title", + "content": "", + "cover": null, + "description": "", + "group_id": 1, + "categories": [ + { + "id": 1, + "name": "category", + "parent": null + } + ], + "created_at": 1516950540, + "updated_at": 1517800400 +} +``` + +**返回参数说明** + +| 参数 | 说明 | +| :--- | :-- | +| id | 内容 ID | +| title | 内容标题 | +| content | 详细容 | +| cover | 封面图 | +| description | 内容摘要 | +| group_id | 内容库 ID | +| categories | 内容所属分类 | +| created_at | 内容创建时间 | +| updated_at | 内容更新时间 | + +## 获取内容列表 + +**接口** + +`GET https://cloud.minapp.com/userve/v1/content/1/text/` + +**提交参数** + +内容查询与[数据表接口](../record.md)查询保持一致 + +**代码示例** + +{% tabs getRichTextEntryListCurlCurl="Curl"%} + +{% content "getRichTextEntryListCurlCurl" %} + +``` +curl -X GET \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/userve/v1/content/1/text/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "meta": { + "limit": 20, + "next": null, + "offset": 0, + "previous": null, + "total_count": 1 + }, + "objects": [ + { + "id": 1, + "title": "Title", + "content": "", + "cover": null, + "description": "", + "group_id": 1, + "categories": [ + { + "id": 1, + "name": "category", + "parent": null + } + ], + "created_at": 1516950540, + "updated_at": 1517800400 + } + ] +} +``` + +## 创建内容分类 + +**接口** + +`POST https://cloud.minapp.com/userve/v1/content/:content_group_id/text/` + +**参数说明** + +Content-Type: `application/json` + +内容的内置字段 ＋ 自定义字段，参数格式将与[数据表接口](../record.md)保持一致 + + +> **warning** +> 字段 group_id 将会被接口自动赋值，所以即使提交的数据中有 group_id 也将会被覆盖 + + +**代码示例** + +{% tabs createRichTextEntryCurl="Curl"%} + +{% content "createRichTextEntryCurl" %} + +``` +curl -X POST \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +-d '{"title": "Test Title"}' \ +https://cloud.minapp.com/userve/v1/content/1/text/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "id": 2, + "title": "Test Title", + "group_id": 1, + "categories": [], + "created_at": 1519960085, + "updated_at": 1519960085 +} +``` + + +> **info** +> 在发送创建内容的请求没有对一些内置字段如 content、description 或自定义字段赋值时，接口返回的字段将不会包含这些未被赋值的字段；若希望接口返回所有的字段，可以在创建内容的请求中携带所有的字段； + +> **info** +> 接口会根据字段在数据表中定义的类型对提交的数据进行强类型的判断，提交的数据类型不合法，接口将会过滤掉这些字段，只存储合法的字段 + +**状态码说明** + +`201`: 创建成功 + +`400`: 提交数据为空；提交的数据都不合法 + + +## 编辑内容分类 + +**接口** + +`PUT https://cloud.minapp.com/userve/v1/content/:content_group_id/text/:text_id/` + + +**代码示例** + +{% tabs updateRichTextEntryCurl="Curl"%} + +{% content "updateRichTextEntryCurl" %} + +``` +curl -X PUT \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +-d '{"name": "Test Category"}' \ +https://cloud.minapp.com/userve/v1/content/1/text/2/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "id": 2, + "title": "Test Title", + "group_id": 1, + "categories": [], + "created_at": 1519960085, + "updated_at": 1519960085 +} +``` + +**状态码说明** + +`200`: 修改成功 + +`400`: 提交数据为空；提交的数据都不合法 + + +## 删除内容库 + +**接口** + +`DELETE https://cloud.minapp.com/userve/v1/content/:content_group_id/text/:text_id/` + + +**代码示例** + +{% tabs deleteRichTextEntryCurl="Curl"%} + +{% content "deleteRichTextEntryCurl" %} + +``` +curl -X DELETE \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/userve/v1/content/1/text/1/ +``` + +{% endtabs %} + + +**状态码说明** + +`204`: 删除成功 diff --git a/user-dash/data/README.md b/user-dash/data/README.md new file mode 100644 index 00000000..3b6fd9d2 --- /dev/null +++ b/user-dash/data/README.md @@ -0,0 +1,6 @@ + + +# 数据模块 + +* [数据表操作](./table.md) +* [数据操作](./record.md) diff --git a/user-dash/data/record.md b/user-dash/data/record.md new file mode 100644 index 00000000..40f2281b --- /dev/null +++ b/user-dash/data/record.md @@ -0,0 +1,455 @@ +# 数据操作 + +获得数据表数据接口，支持对**内置表自定义字段的获取与修改** + +## 查询数据 + +**接口** + +`GET https://cloud.minapp.com/userve/v1/table/:table_id/record/` + +其中 `:table_id` 需替换为你的数据表 ID + +**参数说明** + +Content-Type: `application/json` + +| 参数 | 类型 | 必填 | 说明 | +| :------- | :----- | :-- | :-- | +| where | String | N | 查询语句，参数值应经过 JSON 编码为 JSONString 后，再经过 URL 编码 | +| order_by | String | N | 对资源进行字段排序 | +| limit | Number | N | 限制返回资源的个数，默认为 20 条，最大可设置为 1000 | +| offset | Number | N | 设置返回资源的起始偏移值，默认为 0 | + +例如需要查询价格为 10 元的物品时，我们应该这样构造查询语句: + +```json +{ + "price": {"$eq": 10} +} +``` + +执行 + +``` +curl -X GET \ +-H "Authorization: Bearer token" \ +-H "Content-Type: application/json" \ +-G \ +--data-urlencode 'where={"price":"$eq":10}' \ +https://cloud.minapp.com/userve/v1/table/1/record/ +``` + +该接口完整支持的查询操作符如下： + +| 查询操作符 | 含义 | +| :------- | :-- | +| $eq | 等于 | +| $ne | 不等于 | +| $lt | 小于 | +| $lte | 小于等于 | +| $gt | 大于 | +| $gte | 大于等于 | +| $contains | 包含任意一个值 | +| $nin | 不包含任意一个数组值 | +| $in | 包含任意一个数组值 | +| $isnull | 是否为 NULL | +| $range | 包含数组值区间的值 | + +使用以上查询操作符即可完成一些简单的条件查询，同时，你也可以使用 `$and` 和 `$or` 查询操作符，对以上查询操作符进行组合使用，完成更复杂的条件查询，如查询 __价格为 10 元且产品名称中包含 “包” 的物品__ 或 __价格大于 100 元的物品__，其筛选条件为： + +```json +{ + "$or": [ + { + "$and": [ + { + "price": {"$eq": 10} + }, + { + "name": {"$contains": "包"} + } + ] + }, + { + "price": {"$gt": 100} + } + ] +} +``` + +## 排序返回查询数据 + +查询接口默认按**创建时间倒序**的顺序来返回数据列表，你也可以通过设置 `order_by` 参数来实现。 + +示例： + +``` +# 顺序 +https://cloud.minapp.com/userve/v1/table/:table_id/record/?order_by=id + +# 倒序 +https://cloud.minapp.com/userve/v1/table/:table_id/record/?order_by=-id +``` + +**代码示例** + +{% tabs first="Node", second="Python" %} + +{% content "first" %} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/table/3906/record/', // 3906 对应 :table_id + method: 'GET', + headers: { + Authorization: `Bearer ${token}`, + }, + qs: { // query string, 被附加到uri的参数 + where: JSON.stringify({ // 可选, 参数值应经过 JSON 编码为 JSONString 后，再经过 URL 编码 + "price": {"$eq": 10} + }), + order_by: 'id', // 可选 + offset: 0, // 可选 + limit: 20, // 可选 + } +} + +request(opt, function(err, res, body) { + console.log(body) +}) +``` + +{% content "second" %} + +```python +import json +import urllib + +import requests + + +table_id = '' +BASE_API = r'https://cloud.minapp.com/userve/v1/table/%s/record/' % table_id + +TOKEN = '' +HEADERS = { + 'Authorization': 'Bearer %s' % TOKEN +} + +where_ = { + 'price': {'$gt': 100}, +} + +query_ = urllib.urlencode({ + 'where': json.dumps(where_), + 'order_by': '-id', + 'limit': 10, + 'offset': 0, +}) + +API = '?'.join((BASE_API, query_)) + +resp_ = requests.get(API, headers=HEADERS) +print resp_.content +``` + +{% endtabs %} + + +## 获取数据项 + +**接口** + +`GET https://cloud.minapp.com/userve/v1/table/:table_id/record/:record_id/` + +其中 `:table_id` 需替换为你的数据表 ID，`record_id` 需替换为你的记录 ID + +**代码示例** + +{% tabs itemFirst="Node" %} + +{% content "itemFirst" %} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/table/3906/record/5a2fa9b008443e59e0e678xx/', // 3906 对应 :table_id, 5a2fa9b008443e59e0e678xx 对应 :record_id + method: 'GET', + headers: { + Authorization: `Bearer ${token}`, + } +} + +request(opt, function(err, res, body) { + console.log(body) +}) +``` + +{% endtabs %} + + +## 写入数据 + +**接口** + +`POST https://cloud.minapp.com/userve/v1/table/:table_id/record/` + +其中 `:table_id` 需替换为你的数据表 ID + +**参数说明** + +Content-Type: `application/json` + +| 参数 | 类型 | 必填 | 说明 | +| :--- | :------------------ | :-- | :-- | +| key | key 字段对应的数据类型 | Y | key 应为数据表中定义的字段名 | + +> **info** +> 插入的数据要与预先在知晓云平台设定的数据类型一致 + +**代码示例** + +{% tabs insertNode="Node" %} + +{% content "insertNode" %} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/table/3906/record/', // 3906 对应 :table_id + method: 'POST', + headers: { + Authorization: `Bearer ${token}`, + }, + json: { // 指定 data 以 "Content-Type": 'application/json' 传送 + name: 'nickname', + desc: ['description'], + price: 19, + amount: 19, + code: '18814098707' + } +} + +request(opt, function(err, res, body) { + console.log(res.statusCode) +}) +``` + +{% endtabs %} + +**状态码说明** + +`201` 写入成功，`400` 请求参数有错 + + +## 更新数据 + +本接口提供数据更新的能力，通过指定表 ID 以及 Record ID 来完成操作， 需注意，更新的数据所包含的字段需要与数据表中定义的字段一致。 + +**接口** + +`PUT https://cloud.minapp.com/userve/v1/table/:table_id/record/:record_id/` + +其中 `:table_id` 需替换为你的数据表 ID，`record_id` 需替换为你的记录 ID + +**参数说明** + +Content-Type: `application/json` + +| 参数 | 类型 | 必填 | 说明 | +| :--- | :------------------ | :-- | :-- | +| key | key 字段对应的数据类型 | Y | key 应为数据表中定义的字段名 | + +> **info** +> 更新的数据要与预先在知晓云平台设定的数据类型一致 + +**代码示例** + +{% tabs updateNode="Node" %} + +{% content "updateNode" %} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/table/3906/record/5a6ee2ab4a7baa1fc083e3xx', // 3906 对应 :table_id, 5a6ee2ab4a7baa1fc083e3xx 对应 :record_id + method: 'PUT', + headers: { + Authorization: `Bearer ${token}`, + }, + json: { // 指定 data 以 "Content-Type": 'application/json' 传送 + name: 'nickname' + } +} + +request(opt, function(err, res, body) { + console.log(res.statusCode) +}) +``` + +{% endtabs %} + +**状态码说明** + +`201` 写入成功，`400` 请求参数有错 + + +## 数据删除 + +> **danger** +> 本接口可直接删除任意数据，不受 ACL 控制 + +**接口** + +`DELETE https://cloud.minapp.com/userve/v1/table/:table_id/record/:record_id/` + +其中 `:table_id` 需替换为你的数据表 ID，`record_id` 需替换为你的记录 ID + +**代码示例** + +{% tabs deleteNode="Node" %} + +{% content "deleteNode" %} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/table/3906/record/5a6ee2ab4a7baa1fc083e3xx/',// 3906 对应 :table_id, 5a6ee2ab4a7baa1fc083e3xx 对应 :record_id + method: 'DELETE', + headers: { + Authorization: `Bearer ${token}`, + } +} + +request(opt, function(err, res, body) { + console.log(res.statusCode) +}) +``` + +{% endtabs %} + +**状态码说明** + +`204` 删除成功 + + +## 数据原子性更新 + +当请求同时对一个数据进行修改时，原子性更新使得冲突和覆盖导致的数据不正确的情况不会出现，目前支持的数据类型是**数字类型**和**数组类型** + +**接口** + +`PUT https://cloud.minapp.com/userve/v1/table/:table_id/record/:record_id/` + +其中 `:table_id` 需替换为你的数据表 ID，`record_id` 需替换为你的记录 ID + +**参数说明** + +Content-Type: `application/json` + +| 参数 | 类型 | 必填 | 说明 | +| :--- | :------------------ | :-- | :-- | +| key | key 字段对应的数据类型 | Y | key 应为数据表中定义的字段名 | + +本接口支持以下原子性操作： + +(1) `incr_by` 对数字类型的字段的值进行增减操作 + +将对象中的价格（price）字段加 1 + +```json +{ + "price": { + "$incr_by": 1 + } +} +``` + +将对象中的价格（price）字段减 1 + +```json +{ + "price": { + "$incr_by": -1 + } +} +``` + +(2) `append` 对数组类型的字段的值追加一个数组 + +往对象中的 tag 字段追加 「Hello」 + +```json +{ + "tag": { + "$append": ["Hello"] + } +} +``` + +(3) `append_unique` 对数组类型的字段的值追加一个数组，但追加的数组里的数组项，如果已存在于原数组中，则该**数组项**不会再被追加 + +往对象中的 tag 字段追加 「Hello」，tag 字段依然为 `["Hello"]` + +```json +{ + "tag": { + "$append_unique": ["Hello"] + } +} +``` + +(4) `remove` 从数组类型的字段的值里，删除包含在指定数组中的数组项 + +往对象中的 tag 字段删除 「Hello」 + +```json +{ + "tag": { + "$remove": ["Hello"] + } +} +``` + +**代码示例** + +{% tabs atomicNode="Node" %} + +{% content "atomicNode" %} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/table/3906/record/5a33406909a805412e3169xx/', // 3906 对应 :table_id, 5a33406909a805412e3169xx 对应 :record_id + method: 'PUT', + headers: { + Authorization: `Bearer ${token}`, + }, + json: { // 指定 data 以 "Content-Type": 'application/json' 传送 + desc: { + "$append": ['atomic data'] + }, + price: { + "$incr_by": -1 + } + } +} + +request(opt, function(err, res, body) { + console.log(res.statusCode) +}) +``` + +{% endtabs %} + +**状态码说明** + +`200` 更新成功，`400` 操作符不支持/请求参数有错 diff --git a/user-dash/data/table.md b/user-dash/data/table.md new file mode 100644 index 00000000..315333ad --- /dev/null +++ b/user-dash/data/table.md @@ -0,0 +1,243 @@ +# 数据表操作 + +## 获取数据表详情 + +**接口** + +`GET https://cloud.minapp.com/userve/v1/table/:table_id/` + +**代码示例** + +{% tabs getRichTextEntryCurl="Curl"%} + +{% content "getRichTextEntryCurl" %} + +``` +curl -X GET \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/userve/v1/table/1/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "id": 1, + "name": "Table", + "is_protected": false, + "protected_fields": null, + "schema": { + "fields": [ + { + "description": "id", + "name": "id", + "type": "id" + }, + { + "description": "created_by", + "name": "created_by", + "type": "integer" + }, + { + "description": "created_at", + "name": "created_at", + "type": "integer" + }, + { + "description": "updated_at", + "name": "updated_at", + "type": "integer" + }, + { + "acl": { + "clientReadOnly": false, + "clientVisible": true, + "creatorVisible": false + }, + "constraints": { + "required": false + }, + "default": [ + 1 + ], + "description": "", + "items": { + "type": "integer" + }, + "name": "array_int", + "type": "array" + } + ] + }, + "write_perm": [ + "user:*" + ], + "default_row_perm": { + "_read_perm": [ + "user:*" + ], + "_write_perm": [ + "user:*" + ] + }, + "created_at": 1519538564, + "updated_at": 1519640477 +} +``` + +**返回参数说明** + +接口字段说明： + +| 参数 | 类型 | 说明 | +| :--- | :-- | :-- | +| id | Number | 数据表 ID | +| name | String| 数据表名 | +| is_protected | Boolean | 数据表是否为内置表的标志位，true 为内置表 | +| protected_fields | String Array | 内置表的保护字段，若数据表不是内置表，该字段为 null | +| schema | Object | 数据表字段的元信息 | +| write_perm | String Array |

数据表写权限

- user:* 所有人可写

| +| default_row_perm | Object | 数据表下行数据的默认权限 | +| created_at | Number | 数据表创建时间 | +| updated_at | Number | 数据表更新时间 | + +字段 schema 参数说明： + +| 参数 | 类型 | 说明 | +| :--- | :-- | :-- | +| name | String| 字段名 | +| type | String | 字段类型 | +| description | String | 字段描述 | +| items | Object | 数组字段的元素类型 | +| clientReadOnly | Boolean | 客户端只读的标志位，true 表示字段在客户端不能被写入／更新| +| clientVisible | Boolean | 客户端可见的标志位， true 表示字段在客户端可见 | +| creatorVisible | Boolean | 客户端创建者可见的标志位，true 表示字段在客户端只有创建者可见 | +| required | Boolean | 是否是写入/更新必填选项 | +| default | 与字段类型保持一致 | 字段的默认值 | + +权限参数的说明： + +| 参数 | 类型 | 说明 | +| :--- | :-- | :-- | +| user:* | String| 所有人可写／可读 | +| user:<:user_id> | String| 某个用户可写／可读 | +| gid:<:group_id> | String| 某个分组下的用户可写／可读 | + + +## 获取数据表列表 + +**接口** + +`GET https://cloud.minapp.com/userve/v1/table/` + +**提交参数** + +- name 支持对数据表名的等值查询 + +`https://cloud.minapp.com/userve/v1/table/?name=Table` + +**代码示例** + +{% tabs getTableListCurl="Curl"%} + +{% content "getTableListCurl" %} + +``` +curl -X GET \ +-H "Authorization: Bearer cfb5912724dd7ff0b0c17683cc3074bb548bc7f4" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/userve/v1/table/ +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "meta": { + "limit": 20, + "next": null, + "offset": 0, + "previous": null, + "total_count": 1 + }, + "objects": [ + { + "id": 1, + "is_protected": false, + "name": "Table", + "protected_fields": null, + "schema": { + "fields": [ + { + "description": "id", + "name": "id", + "type": "id" + }, + { + "description": "acl_permission", + "name": "acl_permission", + "type": "integer" + }, + { + "description": "acl_gid", + "name": "acl_gid", + "type": "integer" + }, + { + "description": "created_by", + "name": "created_by", + "type": "integer" + }, + { + "description": "created_at", + "name": "created_at", + "type": "integer" + }, + { + "description": "updated_at", + "name": "updated_at", + "type": "integer" + }, + { + "acl": { + "clientReadOnly": false, + "clientVisible": true, + "creatorVisible": false + }, + "constraints": { + "required": false + }, + "default": [ + 1 + ], + "description": "", + "items": { + "type": "integer" + }, + "name": "array_int", + "type": "array" + } + ] + }, + "write_perm": [ + "user:*" + ], + "default_row_perm": { + "_read_perm": [ + "user:*" + ], + "_write_perm": [ + "user:*" + ] + }, + "created_at": 1519538564, + "updated_at": 1519640477 + } + ] +} +``` diff --git a/user-dash/file/README.md b/user-dash/file/README.md new file mode 100644 index 00000000..401cc2e8 --- /dev/null +++ b/user-dash/file/README.md @@ -0,0 +1,7 @@ + + +# 文件模块 + +* [文件上传](./file-upload.md) +* [文件操作](./file.md) +* [文件分类操作](./file-category.md) \ No newline at end of file diff --git a/user-dash/file/file-category.md b/user-dash/file/file-category.md new file mode 100644 index 00000000..bb1a3438 --- /dev/null +++ b/user-dash/file/file-category.md @@ -0,0 +1,305 @@ +# 文件分类操作 + +## 创建文件分类 + +**接口** + +`POST https://cloud.minapp.com/userve/v1/file-category/` + +**参数说明** + +Content-Type: `application/json` + +| 参数 | 类型 | 必填 | 说明 | +| :--- | :----- | :-- | :-- | +| name | String | Y | 文件分类的名称 | + +**代码示例** + +{% tabs createCategoryCurl="Curl", createCategoryNode="Node" %} + +{% content "createCategoryCurl" %} + + +``` +curl -X POST \ +-H "Authorization: Bearer 58f6cd9f84b1b0c04941fbd4d87bc5f14a785107" \ +-H "Content-Type: application/json" \ +-d '{"name": "Category"}' \ +https://cloud.minapp.com/userve/v1/file-category/ +``` + +{% content "createCategoryNode" %} + + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/file-category/', + method: 'POST', + headers: { + Authorization: `Bearer ${token}` + }, + json: { // 指定 data 以 "Content-Type": 'application/json' 传送 + name: 'testCreateFile' + } +} + +request(opt, function(err, res, body) { + console.log(res.statusCode) +}) +``` + +{% endtabs %} + +**状态码说明** + +`201` 写入成功 + + +## 获取分类详情 + +**接口** + +`GET https://cloud.minapp.com/userve/v1/file-category/:category_id/` + +其中 `:category_id` 需替换为你的文件分类 ID + +**代码示例** + +{% tabs getDetailCurl="Curl", getDetailNode="Node" %} + +{% content "getDetailCurl" %} + +``` +curl -X GET \ +-H "Authorization: Bearer 58f6cd9f84b1b0c04941fbd4d87bc5f14a785107" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/userve/v1/file-category/5a1bb2ed7026d950ca7d2a78/ +``` + +{% content "getDetailNode"%} + + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/file-category/5a2fe91508443e3123dbe1xx/', // 5a2fe91508443e3123dbe1xx 对应 uri :category_id + method: 'GET', + headers: { + Authorization: `Bearer ${token}` + } +} + +request(opt, function(err, res, body) { + console.log(body) +}) +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "files": 0, + "id": "5a1bb2ed7026d950ca7d2a78", + "name": "Category 1", + "created_at": 1511761847, + "parent": null, + "subcategories": [] +} +``` + + +## 获取文件分类列表 + +**接口** + +`GET https://cloud.minapp.com/userve/v1/file-category/` + +**参数说明** + +Content-Type: `application/json` + +| 参数 | 类型 | 必填 | 说明 | +| :------- | :----- | :-- | :-- | +| order_by | String | N | 排序（支持 `created_at` 进行排序）| +| limit | Number | N | 限制返回资源的个数，默认为 20 条，最大可设置为 1000 | +| offset | Number | N | 设置返回资源的起始偏移值，默认为 0 | + +**代码示例** + +{% tabs getCategoryCurl="Curl", getCategoryNode="Node" %} + +{% content "getCategoryCurl" %} + +``` +curl -X GET \ +-H "Authorization: Bearer 58f6cd9f84b1b0c04941fbd4d87bc5f14a785107" \ +-H "Content-Type: application/json" \ +-G \ +-d order_by=-created_at \ +https://cloud.minapp.com/userve/v1/file-category/ +``` + +{% content "getCategoryNode" %} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/file-category/', + method: 'GET', + headers: { + Authorization: `Bearer ${token}` + }, + qs: { // query string, 被附加到uri的参数 + offset: 0, // 可选 + limit: 20, // 可选 + order_by: 'created_at' // 按照创建时间来排序，可选 + } +} + +request(opt, function(err, res, body) { + console.log(body) +}) +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "meta": { + "files": 7, + "limit": 20, + "next": null, + "offset": 0, + "previous": null, + "total_count": 1 + }, + "objects": [ + { + "files": 0, + "id": "5a1bb2ed7026d950ca7d2a78", + "name": "Category 1", + "created_at": 1511761847 + } + ] +} +``` + +字段 `files` 在返回中有两个地方出现；在 `meta` 中表示应用上传文件的数量总和；在 `objects` 中表示每个分类下的上传文件的数量。 + + +## 修改文件分类 + +**接口** + +`PUT https://cloud.minapp.com/userve/v1/file-category/:category_id/` + +其中 `:category_id` 需替换为你的文件分类 ID + +**代码示例** + +{% tabs modifyCategoryCurl="Curl", modifyCategoryNode="Node" %} + +{% content "modifyCategoryCurl" %} + +``` +curl -X PUT \ +-H "Authorization: Bearer 58f6cd9f84b1b0c04941fbd4d87bc5f14a785107" \ +-H "Content-Type: application/json" \ +-d '{"name": "category"}' \ +https://cloud.minapp.com/userve/v1/file-category/5a1bb2ed7026d950ca7d2a78/ +``` + +{% content "modifyCategoryNode" %} + + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/file-category/5a6ad3cffff1d675b9e2cexx/', // 5a6ad3cffff1d675b9e2cexx 对应 uri :category_id + method: 'PUT', + headers: { + Authorization: `Bearer ${token}` + }, + json: { // 指定 data 以 "Content-Type": 'application/json' 传送 + name: 'testCreateFiles' + } +} + +request(opt, function(err, res, body) { + console.log(res.statusCode) +}) +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "files": 0, + "id": "5a1bb2ed7026d950ca7d2a78", + "name": "category", + "created_at": 1511761847 +} +``` + +**状态码说明** + +`200` 修改成功 + + +## 删除文件分类 + +**接口** + +`DELETE https://cloud.minapp.com/userve/v1/file-category/:category_id/` + +其中 `:category_id` 需替换为你的文件分类 ID + +**代码示例** + +{% tabs deleteCategoryCurl="Curl", deleteCategoryNode="Node" %} + +{% content "deleteCategoryCurl" %} + +``` +curl -X DELETE \ +-H "Authorization: Bearer 58f6cd9f84b1b0c04941fbd4d87bc5f14a785107" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/userve/v1/file-category/5a1bb2ed7026d950ca7d2a78/ +``` + +{% content "deleteCategoryNode" %} + + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/file-category/5a6ad3cffff1d675b9e2cexx/', // 5a6ad3cffff1d675b9e2cexx 对应 uri :category_id + method: 'DELETE', + headers: { + Authorization: `Bearer ${token}` + } +} + +request(opt, function(err, res, body) { + console.log(res.statusCode) +}) +``` + +{% endtabs %} + +**状态码说明** + +`204` 删除成功 \ No newline at end of file diff --git a/user-dash/file/file-upload.md b/user-dash/file/file-upload.md new file mode 100644 index 00000000..3fce40fd --- /dev/null +++ b/user-dash/file/file-upload.md @@ -0,0 +1,195 @@ + + +# 上传文件 + +**上传流程图** + +``` + +-----------------+ +-----------------+ +-----------------+ + | Client/Browser | | FORM API | | 知晓云 | + +-----------------+ +-----------------+ +-----------------+ + | | | + +++ Request authorization +++ + |-|====================================>|-| + |-| | |-| + |-| Response authorization |-| + |-|<====================================|-| + +++ | +++ + | | | + +++ Upload +++ +++ + |-|================>|-| |-| + |-| |-| |-| + |-| Response |-| |-| + |-|<================|-| |-| + +++ +++ +++ + | | | +``` + +使用知晓云开放 API 上传文件需要以下两个步骤： + +#### 1. 获取上传文件所需授权凭证和上传地址 + +**接口** + +`POST https://cloud.minapp.com/userve/v1/upload/` + +**参数说明** + +Content-Type: `application/json` + +| 参数 | 类型 | 必填 | 说明 | +| :------------ | :----- | :-- | :-- | +| filename | String | N | 上传的文件名 | +| categories | String | N | 上传文件的所属分类，格式为文件分类的 ID 数组 | + +**返回参数** + +| 参数 | 类型 | 说明 | +| :---------- | :----------- | :-- | +| id | String | 上传的文件 ID | +| policy | String | 文件上传配置 | +| authorization | String | 文件上传凭证 | +| file_link | String | 文件上传成功后的访问地址 | +| upload_url | String | 上传文件的目标地址 | + +**代码示例** + +{% tabs getTokenCurl="Curl", getTokenNode="Node" %} + +{% content "getTokenCurl"%} + +``` +curl -X POST \ +-H "Authorization: Bearer 52ce223c5adbb66fa188a959a8b08889adb3580c" \ +-H "Content-Type: application/json" \ +-d '{ + "filename":"crop.gif", + "categories":["5a1ba7b708443e7fc5f2fb18"] + }' \ +https://cloud.minapp.com/userve/v1/upload/ +``` + +{% content "getTokenNode"%} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/upload/', + method: 'POST', + headers: { + Authorization: `Bearer ${token}` + }, + json: { // 指定 data 以 "Content-Type": 'application/json' 传送 + filename: 'aTest.xlsm', + categories: '5a3b569109a80579061d63xx' + } +} + +request(opt, function(err, res, body) { + console.log(res.statusCode, body) +}) +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "policy": "eyJkYXRlIjogIldlZCwgMDYgRGVjIDIwMTcgMDM6MzI6MzMgR01UIiwgIm5vdGlmeS11cmwiOiAiaHR0cHM6Ly9zc28uaWZhbnIuY29tL2V4dGFwaS9oeWRyb2dlbi91cHl1bi9jYWxsYmFjay8yODcvNWEyNzY0ZDFmZmYxZDYxYWQwZWNhMjQ1LyIsICJidWNrZXQiOiAiY2xvdWQtbWluYXBwLTI4NyIsICJzYXZlLWtleSI6ICIxZU1RUmxrSndoZ2FNaUNnLmdpZiIsICJleHBpcmF0aW9uIjogMTUxMjUzMTQ1M30=", + "upload_url": "https://v0.api.upyun.com/cloud-minapp-287", + "file_link": "https://cloud-minapp-287.cloud.ifanrusercontent.com/1eMQRlkJwhgaMiCg.gif", + "id": "5a2764d1fff1d61ad0eca245", + "authorization": "UPYUN allenzhang:MzmYCcWVjrWoeovC4+tM5Bgwusg=" +} +``` + +**状态码说明** + +`200` 获得授权凭证成功，`400` 参数错误（不支持上传的文件格式)，`404` 找不到文件分类 ID + +#### 2. 使用上一步获取的授权凭证和上传地址，进行文件上传 + +**接口** + +`POST {UPLOAD_URL}` + +`UPLOAD_URL` 是调用上一步的接口所返回的字段 `upload_url` 的值，形如： + +``` + https://v0.api.upyun.com/cloud-minapp-287 +``` + +**参数说明** + +Content-Type: `multipart/form-data` + +| 参数 | 类型 | 必填 | 说明 | +| :------------ | :----- | :-- | :-- | +| authorization | String | Y | 授权凭证 | +| file | String | Y | 上传的文件流 | +| policy | String | Y | 授权凭证 | + +**代码示例** + +{% tabs uploadFileCurl="Curl", uploadFileNode="Node" %} + +{% content "uploadFileCurl" %} + +``` +curl -X POST \ +-H "Authorization: Bearer 52ce223c5adbb66fa188a959a8b08889adb3580c" \ +-H "Content-Type: multipart/form-data" \ +-F authorization="UPYUN allenzhang:MzmYCcWVjrWoeovC4+tM5Bgwusg=" \ +-F file=@"filename" \ +-F policy="eyJkYXRlIjogIldlZCwgMDYgRGVjIDIwMTcgMDM6MzI6MzMgR01UIiwgIm5vdGlmeS11cmwiOiAiaHR0cHM6Ly9zc28uaWZhbnIuY29tL2V4dGFwaS9oeWRyb2dlbi91cHl1bi9jYWxsYmFjay8yODcvNWEyNzY0ZDFmZmYxZDYxYWQwZWNhMjQ1LyIsICJidWNrZXQiOiAiY2xvdWQtbWluYXBwLTI4NyIsICJzYXZlLWtleSI6ICIxZU1RUmxrSndoZ2FNaUNnLmdpZiIsICJleHBpcmF0aW9uIjogMTUxMjUzMTQ1M30=" \ +https://v0.api.upyun.com/cloud-minapp-287 +``` + +{% content "uploadFileNode" %} + +```js +var request = require('request'); +var fs = require('fs'); + +var opt = { + uri: upload_url, // 获取上传文件的授权凭证成功返回的 upload_url + method: 'POST', + headers: { + Authorization: `Bearer ${token}` + }, + formData: { // 指定 data 以 "Content-Type": "multipart/form-data" 传送 + authorization, + policy, + file: fs.createReadStream(__dirname + '/demo.js') // 参数需为文件流 + } +} + +request(opt, function(err, res, body) { + console.log(res.statusCode, body) +}) +``` + +{% endtabs %} + +**返回示例** + +``` +{ + "image-type": "GIF", + "image-frames": 8, + "image-height": 8, + "code": 200, + "file_size": 329, + "image-width": 8, + "url": "1eMQRlkJwhgaMiCg.gif", + "time": 1512531154, + "message": "ok", + "mimetype": "image/gif" +} +``` + +**状态码说明** + +`200` 上传成功 \ No newline at end of file diff --git a/user-dash/file/file.md b/user-dash/file/file.md new file mode 100644 index 00000000..b830a14e --- /dev/null +++ b/user-dash/file/file.md @@ -0,0 +1,212 @@ +# 文件操作 + +## 获取文件详情 + +**接口** + +`GET https://cloud.minapp.com/userve/v1/file/:file_id/` + +其中 `:file_id` 需替换为你的文件 ID + +**代码示例** + +{% tabs getFileDetailCurl="Curl", getFileDetailNode="Node" %} + +{% content "getFileDetailCurl" %} + +``` +curl -X GET \ +-H "Authorization: Bearer 58f6cd9f84b1b0c04941fbd4d87bc5f14a785107" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/userve/v1/file/5a1ba9c1fff1d651135e5ff1/ +``` + +{% content "getFileDetailNode" %} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/file/5a2fe93308443e313a428cxx/', // 5a6ad3cffff1d675b9e2cexx 对应 uri :file_id + method: 'GET', + headers: { + Authorization: `Bearer ${token}` + } +} + +request(opt, function(err, res, body) { + console.log(body) +}) +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "categories": [ + { + "id": "5a1ba7b708443e7fc5f2fb18", + "name": "Category", + } + ], + "cdn_path": "1eJCS1MFGdvaaBoV.png", + "created_at": 1511762369, + "id": "5a1ba9c1fff1d651135e5ff1", + "media_type": "image", + "mime_type": "image/png", + "name": "box_close.png", + "path": "https://cloud-minapp-287.cloud.ifanrusercontent.com/1eJCS1MFGdvaaBoV.png", + "size": 3652, + "status": "success" +} +``` + + +## 获取文件列表 + +**接口** + +`GET https://cloud.minapp.com/userve/v1/file/` + +**参数说明** + +Content-Type: `application/json` + +| 参数 | 类型 | 必填 | 说明 | +| :------- | :----- | :-- | :-- | +| order_by | String | Y | 排序（支持 `created_at` 进行排序）| +| limit | Number | N | 限制返回资源的个数，默认为 20 条，最大可设置为 1000 | +| offset | Number | N | 设置返回资源的起始偏移值，默认为 0 | + +**代码示例** + +{% tabs getFileListCurl="Curl", getFileListNode="Node" %} + +{% content "getFileListCurl" %} + +``` +curl -X GET \ +-H "Authorization: Bearer 58f6cd9f84b1b0c04941fbd4d87bc5f14a785107" \ +-H "Content-Type: application/json" \ +-G \ +-d order_by=-created_at \ +-d category=5a1ba7b708443e7fc5f2fb18 \ +https://cloud.minapp.com/userve/v1/file/ +``` + +{% content "getFileListNode" %} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/file/', + method: 'GET', + headers: { + Authorization: `Bearer ${token}` + }, + qs: { // query string, 被附加到uri的参数 + offset: 0, // 可选 + limit: 20, // 可选 + order_by: 'created_at' // 按照创建时间来排序，可选 + } +} + +request(opt, function(err, res, body) { + console.log(body) +}) +``` + +{% endtabs %} + + +## 删除文件 + +**接口** + +`DELETE https://cloud.minapp.com/userve/v1/file/:file_id/` + +其中 `:file_id` 需替换为你的文件 ID + +**代码示例** + +{% tabs deleteFileCurl="Curl", deleteFileNode="Node" %} + +{% content "deleteFileCurl" %} + +``` +curl -X DELETE \ +-H "Authorization: Bearer 58f6cd9f84b1b0c04941fbd4d87bc5f14a785107" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/userve/v1/file/5a1ba9c1fff1d651135e5ff1/ +``` + +{% content "deleteFileNode" %} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/file/5a45f22bfff1d659681c87xx/', // 5a6ad3cffff1d675b9e2cexx 对应 uri :file_id + method: 'DELETE', + headers: { + Authorization: `Bearer ${token}` + } +} + +request(opt, function(err, res, body) { + console.log(res.statusCode) +}) +``` + +{% endtabs %} + +**状态码说明** + +`204` 删除成功 + + +## 批量删除文件 + +**接口** + +`DELETE https://cloud.minapp.com/userve/v1/file/?id__in=:file1_id,:file2_id` + +**代码示例** + +{% tabs patchDeleteCurl="Curl", patchDeleteNode="Node" %} + +{% content "patchDeleteCurl" %} + +``` +curl -X DELETE \ +-H "Authorization: Bearer 58f6cd9f84b1b0c04941fbd4d87bc5f14a785107" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/userve/v1/file/?id__in=5a1ba9c1fff1d651135e5ff1,59ca3d275f281f58523fc47a +``` + +{% content "patchDeleteNode" %} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/file/?id__in=5a3b8e8908443e06aa6f0a99,5a3b673308443e643f1b0c47', + method: 'DELETE', + headers: { + Authorization: `Bearer ${token}` + } +} + +request(opt, function(err, res, body) { + console.log(res.statusCode) +}) +``` + +{% endtabs %} + +**状态码说明** + +`204` 删除成功 \ No newline at end of file diff --git a/user-dash/group/README.md b/user-dash/group/README.md new file mode 100644 index 00000000..f6ed9986 --- /dev/null +++ b/user-dash/group/README.md @@ -0,0 +1,9 @@ + + +# 分组操作 + +知晓云开放 API 支持用户组和组集的获取、创建、修改和删除等相关操作。 + +* [用户组操作](./user-group.md) +* [组集操作](./super-group.md) +* [用户组与用户的操作](./membership.md) diff --git a/user-dash/group/membership.md b/user-dash/group/membership.md new file mode 100644 index 00000000..c59843b6 --- /dev/null +++ b/user-dash/group/membership.md @@ -0,0 +1,62 @@ +# 用户 加入／移出 用户组操作 + +**接口** + +`PATCH https://cloud.minapp.com/userve/v1/miniapp/group/membership/` + +**参数说明** + +Content-Type: `application/json` + +| 参数 | 类型 | 必填 | 说明 | +| :-------| :----- | :-- | :-- | +| op | String | N | 将要执行的操作，即 `add` 为将用户加入用户组；`remove` 将用户从用户组中移出 | +| path | String | N | 访问的路径，默认为 `/membership` | +| users | String | N | 用户的 user_id 列表，列表不能为空 | +| groups | String | N | 用户组 ID 列表，列表不能为空 | + +提交的数据是一个数组，数组中包含一系列由上面参数组成的操作。 + +**代码示例** + +{% tabs patchCurl="Curl", patchNode="Node" %} + +{% content "patchCurl"%} + +``` +curl -X PATCH \ +-H "Authorization: Bearer 58f6cd9f84b1b0c04941fbd4d87bc5f14a785107" \ +-H "Content-Type: application/json" \ +-d '[ + {"op": "add", "path": "/membership", "users": [5, 6], "groups": [53,54]}, + {"op": "remove", "path": "/membership", "users": [5, 6], "groups":[53,54]} + ]' \ +https://cloud.minapp.com/userve/v1/miniapp/group/membership/ +``` + +{% content "patchNode"%} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/miniapp/group/membership/', + method: 'PATCH', + headers: { + Authorization: `Bearer ${token}` + }, + json: [ // 指定 data 以 "Content-Type": 'application/json' 传送 + {"op": "add", "path": "/membership", "users": [36476036], "groups": [561]} + ] +} + +request(opt, function(err, res, body) { + console.log(res.statusCode) +}) +``` + +{% endtabs %} + +**状态码说明** + +`204` 修改成功，`400` 参数错误 \ No newline at end of file diff --git a/user-dash/group/super-group.md b/user-dash/group/super-group.md new file mode 100644 index 00000000..7c97cf8d --- /dev/null +++ b/user-dash/group/super-group.md @@ -0,0 +1,319 @@ +# 组集操作 + +## 获取组集详情 + +**接口** + +`GET https://cloud.minapp.com/userve/v1/user-supergroup/:group_id/` + +其中 `:group_id` 需替换为你的用户组 ID + +**代码示例** + +{% tabs getDetailCurl="Curl", getDetailNode="Node" %} + +{% content "getDetailCurl" %} + +``` +curl -X GET \ +-H "Authorization: Bearer 58f6cd9f84b1b0c04941fbd4d87bc5f14a785107" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/userve/v1/user-supergroup/52/ +``` + +{% content "getDetailNode" %} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/user-supergroup/666', // 666 对应 :group_id + method: 'GET', + headers: { + Authorization: `Bearer ${token}`, + } +} + +request(opt, function(err, res, body) { + console.log(body) +}) +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "children": [ + { + "id": 51, + "name": "User Group" + } + ], + "id": 52, + "name": "Super Group" +} +``` + + +## 获取组集列表 + +**接口** + +`GET https://cloud.minapp.com/userve/v1/user-supergroup/` + +**参数说明** + +| 参数 | 类型 | 必填 | 说明 | +| :----- | :----- | :-- | :-- | +| limit | Number | N | 限制返回资源的个数，默认为 20 条，最大可设置为 1000 | +| offset | Number | N | 设置返回资源的起始偏移值，默认为 0 | + +**代码示例** + +{% tabs getCurl="Curl", getNode="Node" %} + +{% content "getCurl" %} + +``` +curl -X GET \ +-H "Authorization: Bearer 58f6cd9f84b1b0c04941fbd4d87bc5f14a785107" \ +-H "Content-Type: application/json" \ +-G \ +https://cloud.minapp.com/userve/v1/user-supergroup/ +``` + +{% content "getNode" %} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/user-supergroup/', + method: 'GET', + headers: { + Authorization: `Bearer ${token}`, + } +} + +request(opt, function(err, res, body) { + console.log(body) +} +``` + +{% endtabs %} + + +## 创建组集 + +**接口** + +`POST https://cloud.minapp.com/userve/v1/user-supergroup/` + +**参数说明** + +Content-Type: `application/json` + +| 参数 | 类型 | 必填 | 说明 | +| :--------| :----- | :-- | :-- | +| name | String | Y | 组集的名称 | +| children | String | N | 用户组 ID 列表 | + +**代码示例** + +{% tabs createCurl="Curl", createNode="Node" %} + +{% content "createCurl" %} + +``` +curl -X POST \ +-H "Authorization: Bearer 58f6cd9f84b1b0c04941fbd4d87bc5f14a785107" \ +-H "Content-Type: application/json" \ +-d '{"name": "Super Group", "children": [51]}' \ +https://cloud.minapp.com/userve/v1/user-supergroup/ +``` + +{% content "createNode" %} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/user-supergroup/', + method: 'POST', + headers: { + Authorization: `Bearer ${token}`, + }, + json: { // 指定 data 以 "Content-Type": 'application/json' 传送 + name: 'super group', + children: [561] + } +} + +request(opt, function(err, res, body) { + console.log(res.statusCode) +}) +``` + +{% endtabs %} + +**状态码说明** + +`201` 写入成功 + + +## 修改组集 + +> **danger** +> 该接口会清除掉旧有的组集和用户组的关系，重新与传入的用户组建立关系 + +**接口** + +`PUT https://cloud.minapp.com/userve/v1/user-supergroup/:group_id/` + +其中 `:group_id` 需替换为你的用户组 ID + +**状态码说明** + +`200` 修改成功 + +**代码示例** + +{% tabs updateCurl="Curl", updateNode="Node" %} + +{% content "updateCurl" %} + +``` +curl -X PUT \ +-H "Authorization: Bearer 58f6cd9f84b1b0c04941fbd4d87bc5f14a785107" \ +-H "Content-Type: application/json" \ +-d '{"name": "super group 3", "children": [51]}' \ +https://cloud.minapp.com/userve/v1/user-supergroup/52/ +``` + +{% content "updateNode" %} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/user-supergroup/666/', // 665 对应 :group_id + method: 'PUT', + headers: { + Authorization: `Bearer ${token}`, + }, + json: { // 指定 data 以 "Content-Type": 'application/json' 传送 + name: 'super group', + children: [561] + } +} + +request(opt, function(err, res, body) { + console.log(res.statusCode, body) +}) +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "children": [ + { + "id": 51, + "name": "User Group" + } + ], + "id": 52, + "name": "super group 3" +} +``` + +## 删除组集 + +**接口** + +`DELETE https://cloud.minapp.com/userve/v1/user-supergroup/:group_id/` + +**代码示例** + +{% tabs deleteCurl="Curl", deleteNode="Node" %} + +{% content "deleteCurl" %} + +``` +curl -X DELETE \ +-H "Authorization: Bearer 58f6cd9f84b1b0c04941fbd4d87bc5f14a785107" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/userve/v1/user-supergroup/52/ +``` + +{% content "deleteNode" %} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/user-supergroup/666/', // 666 对应 :group_id + method: 'DELETE', + headers: { + Authorization: `Bearer ${token}`, + } +} + +request(opt, function(err, res, body) { + console.log(res.statusCode) +}) +``` + +{% endtabs %} + +**状态码说明** + +`204` 删除成功 + + +## 批量删除组集 + +**接口** + +`DELETE https://cloud.minapp.com/userve/v1/user-supergroup/?id__in=:group_id,group1_id` + +**代码示例** + +{% tabs patchDeleteCurl="Curl", patchDeleteNode="Node" %} + +{% content "patchDeleteCurl" %} + +``` +curl -X DELETE \ +-H "Authorization: Bearer 58f6cd9f84b1b0c04941fbd4d87bc5f14a785107" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/userve/v1/user-supergroup/?id__in=58,56 +``` + +{% content "patchDeleteNode" %} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/user-supergroup/?id__in=667,668', // id__in=:667,668 对应 id__in=:group_id,group1_id + method: 'DELETE', + headers: { + Authorization: `Bearer ${token}`, + } +} + +request(opt, function(err, res, body) { + console.log(res.statusCode) +}) +``` + +{% endtabs %} + +**状态码说明** + +`204` 删除成功 \ No newline at end of file diff --git a/user-dash/group/user-group.md b/user-dash/group/user-group.md new file mode 100644 index 00000000..ca90159e --- /dev/null +++ b/user-dash/group/user-group.md @@ -0,0 +1,308 @@ +# 用户组操作 + +## 获取用户组详情 + +**接口** + +`GET https://cloud.minapp.com/userve/v1/user-group/:group_id/` + +其中 `:group_id` 需替换为你的用户组 ID + +**代码示例** + +{% tabs userGroupDetailCurl="Curl", userGroupDetailNode="Node" %} + +{% content "userGroupDetailCurl" %} + +``` +curl -X GET \ +-H "Authorization: Bearer 58f6cd9f84b1b0c04941fbd4d87bc5f14a785107" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/userve/v1/user-group/47/ +``` + +{% content "userGroupDetailNode" %} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/user-group/655', // 655 对应 :group_id + method: 'GET', + headers: { + Authorization: `Bearer ${token}`, + } +} + +request(opt, function(err, res, body) { + console.log(body) +}) +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "id": 47, + "members": 0, + "name": "User Group", + "parent": { + "id": 1, + "name": "Super Group" + } +} +``` + +`members` 表示在用户组下的用户数量，`parent` 表示用户组的组集 + + +## 获取用户组列表 + +**接口** + +`GET https://cloud.minapp.com/userve/v1/user-group/` + +**参数说明** + +| 参数 | 类型 | 必填 | 说明 | +| :---------| :----- | :-- | :-- | +| parent_id | String | N | 用户组的组集 ID | +| limit | Number | N | 限制返回资源的个数，默认为 20 条，最大可设置为 1000 | +| offset | Number | N | 设置返回资源的起始偏移值，默认为 0 | + +**代码示例** + +{% tabs userGroupCurl="Curl", userGroupNode="Node" %} + +{% content "userGroupCurl" %} + +``` +curl -X GET \ +-H "Authorization: Bearer 58f6cd9f84b1b0c04941fbd4d87bc5f14a785107" \ +-H "Content-Type: application/json" \ +-G \ +-d parent_id=1 \ +https://cloud.minapp.com/userve/v1/user-group/ +``` + +{% content "userGroupNode" %} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/user-group/', + method: 'GET', + headers: { + Authorization: `Bearer ${token}`, + }, + qs: { // query string, 被附加到uri的参数 + parent_id: "234565423456787645xx", // 可选, 没有用户组的组集 ID, 可以设置为 null 或者不设置 + offset: 0, // 可选 + limit: 20 // 可选 + } +} + +request(opt, function(err, res, body) { + console.log(body) +}) +``` + +{% endtabs %} + + +## 创建用户组 + +**接口** + +`POST https://cloud.minapp.com/userve/v1/user-group/` + +**参数说明** + +Content-Type: `application/json` + +| 参数 | 类型 | 必填 | 说明 | +| :----- | :----- | :-- | :-- | +| name | String | Y | 用户组的名称 | +| parent | String | N | 组集 ID | + +**代码示例** + +{% tabs createUserGroupCurl="Curl", createUserGroupNode="Node" %} + +{% content "createUserGroupCurl" %} + +``` +curl -X POST \ +-H "Authorization: Bearer 58f6cd9f84b1b0c04941fbd4d87bc5f14a785107" \ +-H "Content-Type: application/json" \ +-d '{"name": "User Group"}' \ +https://cloud.minapp.com/userve/v1/user-group/ +``` + +{% content "createUserGroupNode" %} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/user-group/', + method: 'POST', + headers: { + Authorization: `Bearer ${token}`, + }, + json: { // 指定 data 以 "Content-Type": 'application/json' 传送 + name: 'testGroup' + } +} + +request(opt, function(err, res, body) { + console.log(res.statusCode, body) +}) +``` + +{% endtabs %} + +**状态码说明** + +`201` 写入成功 + + +## 修改用户组 + +**接口** + +`PUT https://cloud.minapp.com/userve/v1/user-group/:group_id/` + +其中 `:group_id` 需替换为你的用户组 ID + +**代码示例** + +{% tabs updateGroupCurl="Curl", updateGroupNode="Node" %} + +{% content "updateGroupCurl" %} + +``` +curl -X PUT \ +-H "Authorization: Bearer 58f6cd9f84b1b0c04941fbd4d87bc5f14a785107" \ +-H "Content-Type: application/json" \ +-d '{"name": "user group"}' \ +https://cloud.minapp.com/userve/v1/user-group/47/ +``` + +{% content "updateGroupNode" %} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/user-group/655/', // 655 对应 :group_id + method: 'PUT', + headers: { + Authorization: `Bearer ${token}`, + }, + json: { // 指定 data 以 "Content-Type": 'application/json' 传送 + name: 'testGroup_3' // 修改后的用户组名 + } +} + +request(opt, function(err, res, body) { + console.log(res.statusCode) +}) +``` + +{% endtabs %} + +**状态码说明** + +`200` 修改成功 + + +## 删除用户组 + +**接口** + +`DELETE https://cloud.minapp.com/userve/v1/user-group/:group_id/` + +**代码示例** + +{% tabs deleteGroupCurl="Curl", deleteGroupNode="Node" %} + +{% content "deleteGroupCurl" %} + +``` +curl -X DELETE \ +-H "Authorization: Bearer 58f6cd9f84b1b0c04941fbd4d87bc5f14a785107" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/userve/v1/user-group/47/ +``` + +{% content "deleteGroupNode" %} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/user-group/655/', // 655 对应 :group_id + method: 'DELETE', + headers: { + Authorization: `Bearer ${token}`, + } +} + +request(opt, function(err, res, body) { + console.log(res.statusCode) +}) +``` + +{% endtabs %} + +**状态码说明** + +`204` 删除成功 + + +## 批量删除用户组 + +**接口** + +`DELETE https://cloud.minapp.com/userve/v1/user-group/?id__in=:group_id,group1_id` + +**代码示例** + +{% tabs patchDeleteGroupCurl="Curl", patchDeleteGroupNode="Node" %} + +{% content "patchDeleteGroupCurl" %} + +``` +curl -X DELETE \ +-H "Authorization: Bearer 58f6cd9f84b1b0c04941fbd4d87bc5f14a785107" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/userve/v1/user-group/?id__in=48,50 +``` + +{% content "patchDeleteGroupNode" %} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/user-group/?id__in=652,653', // id__in=652,653 对应 id__in=:group_id,group1_id + method: 'DELETE', + headers: { + Authorization: `Bearer ${token}`, + } +} + +request(opt, function(err, res, body) { + console.log(res.statusCode) +}) +``` + +{% endtabs %} + +**状态码说明** + +`204` 删除成功 \ No newline at end of file diff --git a/user-dash/user.md b/user-dash/user.md new file mode 100644 index 00000000..b41a14b4 --- /dev/null +++ b/user-dash/user.md @@ -0,0 +1,129 @@ +# 用户模块 + +## 获取用户详情 + +**接口** + +`GET https://cloud.minapp.com/userve/v1/miniapp/user-profile/:profile_id/` + +其中 `:profile_id` 需替换为用户 ID + +**代码示例** + +{% tabs curl="Curl", node="Node" %} + +{% content "curl"%} + +``` +curl -X GET \ +-H "Authorization: Bearer 58f6cd9f84b1b0c04941fbd4d87bc5f14a785107" \ +-H "Content-Type: application/json" \ +https://cloud.minapp.com/userve/v1/miniapp/user-profile/55019/ +``` + +{% content "node" %} + +```js +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/miniapp/user-profile/4271xx/', // 4271xx 对应 :profile_id + method: 'GET', + headers: { + Authorization: `Bearer ${token}`, + } +} + +request(opt, function(err, res, body) { + console.log(body) +}) +``` + +{% endtabs %} + +**返回示例** + +```json +{ + "avatar": "https://media.ifanrusercontent.com/media/tavatar/55/c3/55c3dbebcc61891be10d29ded808c84a01dcf864.jpg", + "city": "Guangzhou", + "country": "China", + "created_at": 1504504504, + "gender": 1, + "id": 55019, + "nickname": "PCG", + "openid": "onzns0KsLKFyg3-VcW0GwTE652_k", + "unionid": "onzns0KsLKFyg3-VcW0GwTE652_k", + "province": "Guangdong", + "user_group": [ + 137 + ], + "user_id": 36619758 +} +``` + + +## 获取用户列表 + +**接口** + +`GET https://cloud.minapp.com/userve/v1/miniapp/user-profile/` + +**参数说明 +** + +| 参数 | 类型 | 必填 | 说明 | +| :--------- | :----- | :-- | :-- | +| created_at | String | N | 用户创建的时间，值为时间戳。查询创建时间大于等于 2017-01-01 的用户 `created_at__gte=1483228800`，查询创建时间小于等于 2017-01-01 的用户：`created_at__lte=1483228800` | +| gender | Number | N | 户的性别，其中 `1` 表示男，`2` 表示女 | +| group | String | N | 给定用户组 ID 查询在用户组下的用户列表。只支持 `in` 查询：`group__in=258,360`| +| limit | Number | N | 限制返回资源的个数，默认为 20 条，最大可设置为 1000 | +| nickname | String | N | 用户的微信昵称，支持等值查询 `nickname=Tom`, 模糊查询 `nickname__contains=Tom` | +| offset | Number | N | 设置返回资源的起始偏移值，默认为 0 | +| openid | String | N | 用户的 OpenID | +| order_by | String | N | 排序（支持 `created_at` 进行排序） | +| unionid | String | N | 用户的 UnionID | +| user_id | String | N | 用户 ID | + +**代码示例** + +{% tabs first="Curl", second="Node" %} + +{% content "first" %} + +``` +curl -X GET \ +-H "Authorization: Bearer 58f6cd9f84b1b0c04941fbd4d87bc5f14a785107" \ +-H "Content-Type: application/json" \ +-G \ +-d nickname__contains=Tom \ +-d gender=1 \ +-d created_at__gt=1483228800 \ +-d order_by=-created_at \ +https://cloud.minapp.com/userve/v1/miniapp/user-profile/ +``` + +{% content "second" %} + +```js +var request = require('request'); + +var opt = { + uri: 'https://cloud.minapp.com/userve/v1/miniapp/user-profile/', + method: 'GET', + headers: { + Authorization: `Bearer ${token}`, + }, + qs: { // query string, 被附加到uri的参数 + nickname__contains: 'username', + gender: 1, + created_at__gte: 1483228800, + user_id: '363953xx', + order_by: '-created_at' + } +} + +request(opt, function(err, res, body) { + console.log(body) +}) +``` + +{% endtabs %} \ No newline at end of file