- GraphQL API 向导
GraphQL API 向导
如何通过 GraphQL API，查询和操作系统中的数据。
GraphQL 控制台
可以在浏览器端访问 GraphQL 控制台，查询和操作系统中的数据。访问网址为: ${服务器地址}/graphql
GraphQL接口内置权限控制，执行查询前必须先登录系统，当前查询的访问权限为当前登录的账户。
接口验证
调用接口前，首先需要先进行接口的身份验证。采用API Key来作为 Token，可以更加方便地进行接口调用。不仅如此，还可以实现单点登录、验证登录状态以及注销等功能，这将使得接口调用更加灵活与便捷。
获取 API Key
由于接口验证是以 API Key 作为 Token 进行验证，因此需要先获取 API Key。可以在设置-高级设置-API Key菜单下，获取用户的API Key。
设置 Header
获取到 API Key 之后设置在请求头 Header 当中就可以进行接口调用了。
Authorization : Bearer apikey,${apikey}其中 ${apikey} 替换为获取到的 API Key
查询数据
可以在使用GraphQL查询数据时设置要查询的对象、字段、翻页、排序及过滤条件等，所有查询都基于当前登录用户被授权查看的数据范围。
查询对象和字段
输入对象名称和字段名称，可以查询对象中的所有记录。例如以下查询可以查询分部信息。
{
company{
_id,
name,
admins
}
}查询结果
{
"data": {
"company": [
{
"_id": "CqY8Dy4MCFgXCbMjT",
"name": "华炎软件",
"admins": [
"60f6a630d5d0f30031bba318"
]
},
{
"_id": "EX4Ro64TjLaMnves8",
"name": "华炎网络",
"admins": [
"60f6a630d5d0f30031bba318"
]
}
]
}
}查询参数：翻页
您可以定义一个skip要跳过多少条记录，以及一个查询要返回多少条记录top。
如下查询将仅返回第二条记录：
query{
space_users(top:1, skip:1){
name,
mobile
}
}查询参数：排序
您可以定义如何用sort对结果进行排序。
关键字desc表示降序，关键字asc表示升序。
示例：按字段name降序排序
query{
space_users(sort:"name asc"){
name,
mobile
}
}查询参数：过滤
您可以添加 filters 筛选特定记录。示例：查询分部名称包含 ‘华炎’ 的记录。过滤条件详情请见下方 ”查询过滤条件详解“。
query{
company(filters: ["name","contains","华炎"]){
_id,
name,
}
}扩展查询相关表
对于 lookup 和 master/detail 类型字段，使用 ${field_api_name}__expand 语法，可以扩展查询相关表中的数据。如果相关表字段是多选类型，返回的也是数组数据。
{
company{
_id,
name,
admins__expand{
name
mobile
}
}
}返回结果
{
"data": {
"company": [
{
"_id": "CqY8Dy4MCFgXCbMjT",
"name": "华炎软件",
"admins__expand": [
{
"_id": "60f6a630d5d0f30031bba318",
"name": "管理员",
"mobile": "18600000000"
}
]
}
]
}
}返回格式化数据
对于 boolean , select , date , datetime , lookup类型字段，使用 _display{ field_api_name } 语法，可以格式化查询到的数据。
其中 0 、null 、false 值格式化后为空字符串。
query{
space_users(top:1, skip:1){
name,
# boolean null
email_verified
# boolean false
mobile_verified
# boolean true
is_supplier
# lookup 单选
organization
# lookup 多选
organizations_parents
# select
locale
# number
sort_no
# date
last_logon
# datetime
created
_display{
email_verified
mobile_verified
is_supplier
organization
organizations_parents
locale
sort_no
last_logon
created
}
}
}返回结果
{
"data": {
"space_users": [
{
"name": "ldx_test2_app",
"email_verified": null,
"mobile_verified": false,
"is_supplier": true,
"organization": "dZM6e9zgdrrk8rPZZ",
"organizations_parents": [
"dZM6e9zgdrrk8rPZZ",
"EzrZricSyxyJARRut",
"3bJaD7L8jjbYW4vY8",
"z4KogJQ26nFpJeui8"
],
"locale": "zh-cn",
"sort_no": 1,
"last_logon": "1634028562052",
"created": "1618108487329",
"_display": {
"email_verified": "",
"mobile_verified": "",
"is_supplier": "√",
"organization": "教育部门/部门1/部门1-1",
"organizations_parents": "教育部门,教育部门/部门1,教育部门/部门1/部门1-1,星陨阁",
"locale": "简体中文",
"sort_no": 1,
"last_logon": "2021-10-12",
"created": "2021-04-11 10:34"
}
}
]
}
}查询相关子表
当其他表与当前表关联时，可以同时查询相关的子表信息。
查询语法
_related_${object_api_name}_${field_api_name}例如以下查询可以查询当前分部中的人员清单，也就是人员对象（space_users）中，company_ids 字段与 company 绑定的记录信息。
{
company{
_id,
name,
admins__expand{
_id
name
mobile
}
space_users: _related_space_users_company_ids(filters: ["job_number","=","10"]) {
name
mobile
}
}
}注意：为了提升返回结果的可读性，这里给返回结果起了一个别名： space_users
返回结果
{
"data": {
"company": [
{
"_id": "CqY8Dy4MCFgXCbMjT",
"name": "华炎软件",
"admins__expand": [
{
"_id": "60f6a630d5d0f30031bba318",
"name": "管理员",
"mobile": "18600000000"
}
],
"space_users": [
{
"name": "小明",
"mobile": "18600000000"
}
]
}
]
}
}操作数据
可以使用GraphQL对数据执行增、删、改操作，所有数据处理操作都基于当前登录用户被授权的数据范围。
新增数据
当调用 GraphQL API 新增数据时，系统会首先验证当前用户是否有对应的新增权限。
新增单条数据
使用 mutation.{object_api_name}__insert 语法，传入 doc 参数值。
mutation {
tasks__insert(doc:{name:"Task One", assignees: []}) {
name
_id
}
}其中，tasks 代表要插入记录的对象名称，{name:"Task One", assignees: []} 代表要插入的JSON数据。
关键字 __insert 表示通过 GraphQL API 在系统中插入一条记录。
结果如下：
{
"data": {
"tasks__insert": {
"name": "Task One",
"_id": "5cb98489d09a343e14daae95"
}
}
}新增多条数据
使用 mutation.{object_api_name}__insert_many 语法，传入 docs 参数值。
mutation {
tasks__insert_many(docs:[{name:"Task One", assignees: []}]) {
name
_id
}
}其中， tasks 代表要插入记录的对象名称，[{name:"Task One", assignees: []}] 代表要插入的JSON数据。
关键字 __insert_many 表示通过 GraphQL API 在系统中插入多条记录。
结果如下：
{
"data": {
"tasks__insert_many": [{
"name": "Task One",
"_id": "5cb98489d09a343e14daae95"
}]
}
}修改数据
当调用 GraphQL API 修改数据时，系统会首先验证当前用户是否有对应的修改权限。
修改单条数据
使用 mutation.{object_api_name}__update 语法，传入 _id 和 doc 参数值。
mutation {
tasks__update(_id:"5cb98489d09a343e14daae95", doc:{name:"Task Important"}) {
name
_id
}
}其中，tasks代表要修改记录的对象名称，_id 的值 5cb98489d09a343e14daae95 代表要修改的记录的 _id，{name:"Task Important"} 代表要更新的JSON数据。
关键字__update表示通过 GraphQL API 在系统中修改一条记录。
结果如下：
{
"data": {
"tasks__update": {
"name": "Task Important",
"_id": "5cb98489d09a343e14daae95"
}
}
}修改多条数据
使用 mutation.{object_api_name}__update_many 语法，传入 filters 和 doc 参数值。
mutation {
tasks__update_many(filters: ["name","contains","Important"], doc:{important: true}) {
name
_id
important
}
}其中，tasks 代表要修改记录的对象名称，filters 的值代表要修改的数据范围的过滤条件，{important: true} 代表要更新的JSON数据。
关键字 __update_many 表示通过 GraphQL API 在系统中修改多条记录。
结果如下：
{
"data": {
"tasks__update_many": [{
"name": "Task Important",
"_id": "5cb98489d09a343e14daae95",
"important": true
}]
}
}删除数据
当调用 GraphQL API 删除数据时，系统会首先验证当前用户是否有对应的删除权限。
删除单条数据
使用 mutation.{object_api_name}__delete 语法，传入 _id 参数值。
mutation {
tasks__delete(_id:"5cb98489d09a343e14daae95")
}其中，tasks 代表要删除记录的对象名，_id 的值 5cb98489d09a343e14daae95 代表要删除的记录的_id
关键字__delete表示通过 GraphQL API 在系统中删除一条记录。
结果如下：
{
"data": {
"tasks__delete": 1
}
}删除多条数据
使用 mutation.{object_api_name}__delete_many 语法，传入 filters 参数值。
mutation {
tasks__delete_many(filters: ["name","contains","Important"])
}其中，tasks代表要删除记录的对象名称，filters 的值代表要删除的数据范围的过滤条件。
关键字 __delete_many 表示通过 GraphQL API 在系统中删除多条记录。
结果如下：
{
"data": {
"tasks__delete_many": 1
}
}返回值
1表示成功删除的数据条数。
参考：GraphQL