1. 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 语法,传入 _iddoc 参数值。

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 语法,传入 filtersdoc 参数值。

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